Application structure

FontoXML defines a structure for an application. Fonto requires a number of files to be placed at set locations and advices on the overall structure of your application. Use this guide to consult on the naming and structure of the files and packages of your application.

Files and directories

The following sections outline the general file, directory structure and purpose in a typical FontoXML instance.

manifest.json

The SDK manifest. This file records the packages, platform version and add-ons, used in this build of the instance.

When upgrading a FontoXML instance you will be required to upload this file. This enables the FontoXML development tools to select the appropriate add-ons for the new version when upgrading and/or adding/removing add-ons.

messages-template.json

The message bundle template for the FontoXML platform and add-ons used by your application.

This file is generated when creating or upgrading a FontoXML editor instance. It can be used to generate or update localizations used by your application.

config/

Contains files which define instance-specific configuration:

Name Purpose
config/assets/ This directory may contain assets used for branding, such as the favicon image file.
config/configuration.js Defines settings for platform components, including selection of standard and custom connectors, and the choice of side panels visible in the instance (uses the ConfigurationManager).
config/schemaExperienceResolver.js Defines the schemas used in this instance. See Schema experiences for more information.
config/fonto-manifest.json The root package manifest for your application. See below.

dev-cms/

Contains example content to be served by the development server for this instance in the files directory. The example content is only used when using the stubbed CMS server and is not included in builds.

If the development server is running in disk save mode (the default), an uploads directory will be created next to files. This file holds updated versions of the example content files, to avoid overwriting the original. This allows the content to be reset to its original state by simply removing the uploads directory.

We recommend not storing the uploads directory in your source control solution.

In addition to the example content, this folder may be used to define application-specific custom development server extension routes.

dist/

After building the instance, this directory contains the production-ready version of the instance, which can be deployed to and/or integrated in the client’s content management system.

node_modules/

Contains the modules required for the build tool to work. These files are installed and managed by the NodeJS package manager.

As these files may be platform-specific, we recommend not storing the node_modules directory in your source control solution.

packages/

Contains the packages for this application. Packages and their structure are discussed in more detail below.

packages-shared/

This optional directory may be used to store packages that are shared between instances, but not provided by FontoXML.

platform/

The SDK’s source code. When performing an upgrade, this directory should be completely removed and replaced by the upgrade.

About packages

FontoXML uses a modular architecture. JavaScript code is written in separate files called modules, using the ES module format. These modules are combined with other relevant files, such as CSS style sheets, JSON data and image assets, into feature-specific packages.

FontoXML provides a number of features to automatically integrate packages into the instance. Instance-specific packages should be created as separate folders in the packages folder under the root of the instance. Each package generally falls in one of three categories:

  • an add-on, a global schema-independent extension providing a feature or set of tools used by other packages.
  • a schema experience module, containing mainly CVK configuration and operations for specific elements in a schema.
  • a schema experience (often called shell in accordance with DITA terminology), providing the schema definition and integrating appropriate sx modules.

Each package should have the following structure:

Name Type Description
fonto-manifest.json file Optional. The manifest for the package, specifying the dependencies of the package. See below for further information.
src folder Required. Contains source files for the instance.

By convention, only files in the root of the package are considered public. That is, these files are allowed to be imported from other packages. Files internal to the package should be placed in subfolders of the src folder.

This folder may contain a number of special files, listed in the rows below. These files will automatically be integrated in the application if the config package directly or indirectly depends on the package (see "The package manifest" below).
src/assets folder Contains files that are required by the application at run-time. When the application is built or served using the FontoXML development server, the assets folders for all packages (and the ones in the config/assets folder) are merged into one, served under the "assets/*" path. This means that assets can always be referred to using a path starting with "assets/", but also means that you should ensure that the files placed here do not conflict with assets for any other package.
src/configureSxModule.js file Optional. Should export a single function which will be invoked with an SxModule. Only place CVK configuration inside this function.
src/install.js file Optional. Should export a single function. Any set-up for the package involving managers, such as setting up notifier callbacks, should be done in this function.
src/setDefaultConfiguration.js file Optional. Should export a single function, which should only call ConfigurationManager#setDefault. This can be used to provide, or override, default configuration values in a package shared between multiple applications.
src/styles.css file Optional. Styles for the package.
src/messages.*.json file Optional. Localization message bundles. The * should be an IETF language code for the target language of the bundle. See Localize the interface for further details.
src/operations.json
src/operations-*.json
file Optional. Operations defined by the package. For packages containing a large number of operations, multiple files can be used using the format operations-*.json.
src/*.xqm file Optional. XQuery module defined by the package.

The package manifest (fonto-manifest.json)

Each package may contain a fonto-manifest.json file which specifies the dependencies for the package. Dependencies determine the order in which packages are initialized, which is important to ensure that any features used by a package are available and working correctly when the package is initialized. Dependencies from your applications packages on the platform and installed add-ons are inferred automatically, as long as these packages are mentioned in the config/fonto-manifest.json file. If your package does not have dependencies other than the automatically inferred ones, the fonto-manifest.json file can be omitted.

You probably need to specify a dependency in the following cases:

  • Your package uses API provided by another package in the application.
  • Your package is a schema experience, which integrates a schema experience module defined by another package (see "Integrating a package" below).

If the fonto-manifest.json file exists, it should contain a single property called dependencies, with as its value an object mapping package names to their path relative to the application.

Although the path specified here is not used at this time, we recommend following this convention to support future releases that may assign semantics to this value.

For example, a package that uses the base platform, some platform add-ons and a locally defined package only needs to specify the local dependency, and therefore may have a manifest as follows:

fonto-manifest.json
{
	"dependencies": {
		"my-local-package": "packages/my-local-package"
	}
}

Integrating a package

Each package should be represented by a folder in the packages folder of your application (or packages-shared where appropriate). In order for the package to be registered to load, it needs to be integrated in your application. This is always done by introducing a dependency on the package. Where to specify this dependency depends on whether the package is an add-on, or contains schema-specific configuration.

Add-ons are packages that apply to all schema experiences, or provide features that are independent of any specific schema. Add-ons are integrated by adding a dependency on the package in the top-level manifest, that is config/fonto-manifest.json. If the add-on contains configuration that affects the schema, it should be marked as an add-on by calling sxModule.markAsAddon() in the configureSxModule.js file. Add-ons that do not contain a configureSxModule.js do not require this step.

Packages that apply only to a limited set of schema experiences are often called schema experience modules, as these will most likely contain a configureSxModule.js file containing the majority of their configuration. The page on Schema experiences discusses this concept in more detail. In short, such a package may be integrated either by including a dependency from another package that is itself a dependency of the same schema experience, or by directly including the package name in the array of package names passed to sxManager.defineSchemaExperience in your schemaExperienceResolver.js file. Any package listed in these arrays should also be listed in config/fonto-manifest.json.

Packages that themselves define a schema experience (or shell) follow the same conventions as schema experience modules. By convention, each schema experience is represented by a single root package containing the compiled schema .json file. This package then specifies the packages that provide configuration for the schema as its dependencies. By structuring your schema experiences in this way, only the shell packages need to be mentioned in schemaExperienceResolver.js and the config/fonto-manifest.json.