Upgrade from 6.7 to 6.8

The 6.8.0 platform release brings some new features that deserve attention when upgrading. Certain non-standard XPath selectors can trigger deprecation warnings, schema files can now be lazy-loaded and most user interface strings can be localized.

Upgrading XPath usage

In older versions of the XPath engine, some unfortunate choices were made regarding the standard. Namely, nodeType tests and functions were mixed up. In later versions, we discovered this and fixed it, but a few legacy XPath queries may be present in some instances.

These XPath queries should be removed as part of the upgrade. To assist with refactoring them, warnings will be printed to the console whenever these queries are parsed. All of the ‘custom tests’ previously supplied by the platform have an overload using arguments instead of a context node. As we intend to remove the non-standard behavior, selectors that trigger these warning in the 6.8 version of the platform will not work on the next version of the platform.

As part of this effort, the deprecated matchNodeName / matchProcessingInstruction / matchAnything functions also print console errors. Use XPath expressions wherever possible in APIs that ask for a selector.

  1. After upgrading the instance, open the instance and open the console.

  2. Remove the console warnings by resolving the problems in one of two ways:

    'match(…) will be removed in the next release'


    matchNodeName('someElement') -> 'self::someElement' or 'name() = "someElement"'
    matchProcessingInstruction('someTarget').requireParent('someParentElement') -> self::processing-instruction(someTarget)[parent::someParentElement]

    Functions as tests (like self::XXX()) are not correct XPath. They will be removed next release. Please refactor the selector "(…)"


    self::fonto:dita-class('topic/p) -> fonto:dita-class(., 'topic/p')
  3. Retest the instance. Do all selectors still work?

After this step, all warning should be removed and the configuration should be equivalent.

Lazy-loading schemas

Starting from the platform version 6.8, schemas can be lazy loaded to improve load-time and build-time performance for instances. Instances that include multiple schemas, but only use a few in a single session will profit from this in particular.

Because the SDK portal will only generate schemas using the new structure, it is advised to upgrade any existing schemas to the lazy-loading API.

  1. Convert the schema using the SDK-portal. This upgrades them to a new directory structure.

    The new structure places the schema in the assets folder, which ensures it remains a separate file when the instance is built. As a convention, we place the schemas in a schemas folder, using the package name as their filename to avoid conflicts.

  2. Open the file config/schemaExperienceResolver.js

  3. Remove the imports for the SCHEMA_DATA files

  4. Change the registration calls for the schema locations

    The calls to sxManager.createSchemaExperienceshould be rewritten to calls to sxManager.defineSchemaExperience. This function accepts a URL to a schema file, instead of a SCHEMA_DATA. The SDK portal will output a directory structure placing the schema at assets/schemas/SCHEMA_URI.json. Note that the assets directories for all packages are combined at build-time, so these paths start with assets rather than the package name.

    Change the following snippet:


    schemaLocationToSchemaExperienceResolver.register( sxManager.createSchemaExperience( SCHEMA_DATA, ['SCHEMA_PACKAGE_NAME'].concat(ADDONS)), SCHEMA_LOCATIONS);

    To look like the following snippet:


    schemaLocationToSchemaExperienceResolver.register( sxManager.defineSchemaExperience( 'assets/schemas/SCHEMA_PACKAGE_NAME.json', ['SCHEMA_PACKAGE_NAME'].concat(ADDONS), SCHEMA_LOCATIONS);
  5. Load the instance to test the changes.

  6. Check if the mimetype handlers on the server are configured correctly.

    The schemas are now served as separate .json files. Some servers may require additional configuration to be able to serve these correctly. Please refer to the documentation for your server software for further details.

The FontoXML instance will now lazy-load its schemas as soon as a document requiring the schema is loaded. It will not load unused schemas.


Starting with the 6.8 version of the FontoXML platform, most user-facing text in the FontoXML application can be translated. This includes labels and descriptions for all operations provided by the platform, as well as various modals and other user interface components.

As certain modals and other UI elements are scheduled to be replaced in the releases following the 6.8 release, some text displayed in these elements can not currently be localized. When replaced, the new implementations will include localization support.

Some instances may have localized text in previous releases by overriding operations and/or UI components with versions containing localized text. As this often requires duplicating implementation details subject to change, we recommend replacing such approaches with a proper localization based on the new API.

The localization system can also be used to alter texts to use more appropriate terminology for the application, even if the language used is still English. For instance, you may prefer to refer to the CMS by its name, or refer to documents as “chunks”. In these cases, simply define your messages as usual, but use the “en” locale to override the built-in text.

  1. Upgrade the application to 6.8.0 (or newer) using the SDK portal

    The .zip file created by the SDK portal for platform upgrades contains the file messages-template.json. This is a message bundle template for all localizable text in the selected platform and add-ons.

  2. Create a new package directory for containing the translated strings

    Localization bundles can be placed in the src folder of any package. When in doubt, create a single package named [instance-name]-localization. Make sure that the config package depends on this localization package, either directly or via another package. For more information on how to create packages, please read the documentation on the structure of a package directory.

    Because this package redefines messages used in the platform, it should depend on the platform using a fonto-manifest.json with the following contents:


    	"dependencies": {
    		"fontoxml-platform-base": "platform/fontoxml-platform-base"

    Use fontoxml-platform-dita instead of fontoxml-platform-base if you are using the DITA platform.

  3. Copy the messages-template.json file to the package directory as src/messages.[IETF language tag].json.

    The IETF language tag is used to select the appropriate plural forms for your localization. Make sure to use the appropriate code from the CLDR plural rules chart in order for the correct plural forms to be used for your localization. Variations on a language can be made using a dash and suffix after the language code.

    Translating an instance to Lojban should be done in a file called messages.jbo.json. Dialects would create a file messages.en-US.json.

  4. Fill in the blanks

    Message bundles are JSON files, containing an array of message objects. Each message contains an in property with the original message, and optionally some metadata reflecting the use of the message in the FontoXML source files.


    [{ "in": "Insert character", "meta": [{...}] }]

    To turn this template into a usable message bundle, add a new field called out to each message containing the translated string. For example, to translate this string to Lojban, add an 'out' key, containing the translated text as a string:


    [{ "in": "Insert character", "out": "Setca lo lerfu", ... }]

    Repeat this part for all strings in the application. In the future, the localization tooling will contain a converter from and to other file formats, to ease collaboration with translation services.

    The translation messages use the MessageFormat format, which also supports genders and pluralization. The message {REPORT_COUNT, plural, one{# content issue} other{# content issues}} can output either 1 content issue or 9001 content issues, depending on the variable REPORT_COUNT.

    When translating such messages, make sure to leave the MessageFormat syntax intact and to use the appropriate plural forms for your language.

  5. Configure the locales to use

    Set the configuration variable preferred-locales to an array of IETF language tags, in order of preference. If a message is not translated in a preferred locale, it will fall back to a locale higher in the array.

    It is recommended to always include the “en” language tag as the last entry in the array. This way, when new messages are added in future releases of the platform for which no localization has been created yet, the application will fall back to the built-in English localization for these messages rather than causing an error.


    configurationManager.set('preferred-locales', ['jbo', 'en-US', 'en']);
  6. Remove old workarounds

    If all went well, the instance is now translated. Remove any operations and toolbar button properties that were only intended to override built-in text - using the localization framework for this purpose is less likely to break your application in unexpected ways. Additionally, translating these messages using the localization files will keep all messages in the same location.

After performing these steps, the instance-level code is reduced and the translated messages are located in a single file.

Please refer to the documentation on localization for further details, including instructions on how to enable localization in your own packages, and how to maintain and upgrade your message bundles for future releases of the FontoXML platform.