Upgrade from 6.11 to 7.0

FontoXML 7.0.0 is a major version release. This means that a number of APIs that previously remained stable have changed, in order to simplify the task of configuring FontoXML for your application. Upgrading to 7.0 will therefore likely require more changes to your application than previous upgrades. In particular, the 7.0 release introduces FDS, a new framework for defining the UI of your application. Any previous UI modifications will have to be reconfigured to use FDS in order to upgrade your application.

To provide enough time to upgrade to this new release, we aim to continue support for the latest 6.x release with critical bug fixes until the next major version release of FontoXML (8.0). The documentation and SDK portal for the 6.x version will remain available while this support lasts, although we strongly recommend that new applications always use the latest version of FontoXML.

For larger applications, or applications with large amounts of customization, we recommend first stripping down the application to a minimum, and then re-adding features one by one. These upgrade instructions therefore consist of two phases. The first set of steps is intended to reconfigure those parts of your application that are required to start your application using the 7.0 platform. After this, we dive into specific areas that need to be reconfigured in order to restore the full functionality of your application.

Before you start

FontoXML 7.0 requires some changes to your CMS:

  • Due to problems encountered with some network infrastructures, FontoXML 7.0 no longer uses the Etag HTTP header as part of its contracts. Various endpoints related to documents are now required to provide and/or accept a revisionId property to replace its functionality.The following APIs have been affected by this change:

    • document GET: The CMS should not return an ETag anymore but should provide a revisionId.

    • document POST: The CMS should not return an ETag anymore but should provide a revisionId.

    • document PUT: The editor provides a revisionId for the old version of the document, if it was assigned one in an other CMS call. This revisionId may be checked by the CMS to detect a dirty save. The CMS may return a revisionId. If the CMS does not return one, the revisionId will not be changed.

    • document/lock PUT: The documentETag property is not provided anymore. Instead, a revisionId is provided.

    Please refer to the CMS connectors API documentation for the new contracts.

  • All document related APIs may pass a documentContext property. This is optional and may be omitted. If the CMS provides a documentContext, the editor will pass that context to all CMS requests related to that document. If the CMS provides a new documentContext, the editor will provide that new one to all future CMS requests.The following APIs are affected by this change:

    • document GET: The CMS may return a documentContext.

    • document POST: The CMS may return a documentContext.

    • document PUT: The editor will provide a documentContext if one was provided by the CMS. The CMS may return a documentContext.

    • document/lock PUT: The editor will provide a documentContext if one was provided by the CMS. The CMS may return a documentContext

  • A new document/state endpoint has been introduced to allow the FontoXML application to periodically update the state of loaded documents from the CMS. This feature improves collaboration by allowing authors to see the changes made by other authors to lock state and document contents. If you do not wish to implement this endpoint at this time, it can be disabled by setting the remote-document-state-update-interval-ms @ fontoxml-remote-documents/src/setdefaultconfiguration.js configuration value to -1. This enw API may use both the new documentContext and revisionId.

FontoXML 7.0 introduces officially supported add-ons for various standard table models. Previously, some applications have included table support based on internal APIs that have now been removed. These implementations should be replaced with the new add-ons for the 7.0 release. If you are using a table model that is not supported by the current set of add-ons, please contact us. The currently supported table implementations are CALS tables, XHTML tables and DITA simple tables.

In addition to these add-ons, the 7.0 release decouples a number of features from the base platform by providing them as add-ons instead. The SDK portal will suggest selecting these features when you upload the manifest for your 6.x application. Please double-check whether the features selected match the requirements of your application before you download the 7.0 upgrade.

The schema format used by FontoXML 6.x is not compatible with the 7.0 release due to the introduction of full support for XML namespaces. Before you start the upgrade process, please make sure you have access to the original XSD files and the corresponding catalog and fonto.json configuration file.

Getting up and running with the 7.0 release

Upgrade the application

  1. First, use the SDK portal to download the 7.0 upgrade for your application, double-checking the selected add-ons.

  2. Remove any package-lock.json files that may exist.

  3. Follow the default upgrade instructions.

While using the SDK portal to upgrade your application a list will be shown of removed and renamed add-ons and show the add-ons you have selected. It is advised to keep this window open until after you've completed the "Integrate new add-ons" section of the upgrade instructions.

Upgrade your schema(s)

Make sure the zip file containing your schemas includes a fonto.json file. This file specifies for each root schema (XSD file) in use by your application the name of the corresponding FontoXML package, as well as (optionally) the schema location values to be associated with the schema. While previous releases allowed omitting this file, results could be unpredictable. Therefore, the fonto.json file is now required, and package names and schema locations are no longer editable in the SDK portal UI. Make sure your fonto.json file contains the correct values for each schema package to be generated.

As FontoXML 6.9 introduced support for XML simple types, the use of strict mode is not recommended, as it may allow schema-invalid content to be created. Remove the compilerFlags section from your fonto.json file.

Make sure the zip file contains all schema files (XSD files) that are referenced, including the DITA 1.2, DITA 1.3 and MathML schema files. Previous releases used built-in DITA 1.2, DITA 1.3 and MathML schema files, but these could result in unpredictable schema packages. They have been removed from the schema compiler so they should be provided in the zip file.

Make sure references to files in your schema(s) and/or catalog are case-sensitive as specified in the URI specifications RFC 3986 Uniform Resource Identifier (URI): Generic Syntax (for schema files) and RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax (for catalog files). Previous versions of the schema compiler incorrectly gave some leniency with the case-sensitivity of the URIs.

After these changes have been made, upload the schema zip file to the SDK portal in the "Convert XML schema" section to generate the new schema packages, and replace these files in your application. Note that, as of the 7.0 release, the schema compiler is less forgiving of errors in your schemas or catalog. Resolve any issues that are reported if your schemas fail to compile.

Integrate new add-ons

Add-ons should now be integrated simply by listing them as dependencies in config/fonto-manifest.json. Make sure that all add-ons selected in the SDK portal are listed as dependencies. The SDK portal will report on removed and renamed add-ons, remove and rename all dependencies on these add-ons. Remove any mention of add-ons from schemaExperienceResolver.js; the ADDONS array used in previous versions is no longer required. Both the ADDONS variable and the .concat(ADDONS) part can be removed. Do include a dependency on an add-on in any package that directly imports API exposed by the add-on.

If your application contains packages that should be included in every schema experience and that also include a configureSxModule.js file, call sxModule.markAsAddon() in that file, then include it as a dependency in config/fonto-manifest.json in the same way as add-ons provided by FontoXML. Add-ons that do not include configureSxModule.js can skip the markAsAddon step.

If you used the DITA platform, remove all dependencies on fontoxml-platform-dita and instead add dependencies on fontoxml-platform-base and the fontoxml-dita add-on to config/fonto-manifest.json.

Dependencies from your packages on the base platform and add-ons provided by the SDK portal are now inferred automatically and no longer need to be specified manually in your packages' fonto-manifest.json, as long as they are included in the dependencies of the config/fonto-manifest.json file. In fact, you can safely remove any fonto-manifest.json that only includes dependencies on these packages.

Update essential configuration values

Open config/configuration.js to update configuration values for the 7.0 platform:

  • The configuration for the unique ID generation feature has been simplified. It is no longer necessary to import the UniqueIdConfiguration class (in fact, it has been removed). Remove the unique-id-configuration value. Instead, add a unique-id-configurations @ fontoxml-unique-ids/src/setdefaultconfiguration.js value set to an array of objects, each describing an ID attribute to automatically populate. For example, if your schema uses the xml:id attribute on elements div, p and bibl, use the following configuration value:


    configurationManager.set('unique-id-configurations', [{
    	namespaceURI: 'http://www.w3.org/XML/1998/namespace',
    	localName: 'id',
    	selector: 'name(.) = ("bibl", "div", "p")'

    For attributes without a namespace, make sure to set namespaceURI to null.

  • The configuration value required-aspects-to-make-document-editable has been removed. Consider using the documentcapabilitiesmanager @ fontoxml-documents/src/documentcapabilitiesmanager.js, or use the equivalent aspect cap/operable.

Configure namespaces

FontoXML introduces support for XML namespaces. If your application uses XML namespaces in any way other than having all elements in the default (null) namespace, you will need to make FontoXML aware of the prefixes used in your documents and configuration. To do this, import fontoxml-dom-namespaces/namespaceManager in configuration.js and call the addNamespace method on the namespacemanager @ fontoxml-dom-namespaces/src/namespacemanager.js for each prefix / namespace combination. Note that in the 7.0 release, each namespace can only be assigned a single prefix and vice versa.

Namespace registration examples


namespaceManager.addNamespace('', 'http://www.tei-c.org/ns/1.0');
namespaceManager.addNamespace('math', 'http://www.w3.org/1998/Math/MathML');
namespaceManager.addNamespace('xl', 'http://www.w3.org/1999/xlink');

Namespace prefixes configured here may be used in XPath expressions and stencils / JsonML. We'll discuss other new APIs related to dealing with namespaced elements and attributes later.

DITA-based schemas do not require namespace configuration, except when including foreign XML fragments such as MathML.

As a consequence of fully supporting XML namespaces, FontoXML will now fail to load any XML documents that are not namespace-valid. If you encounter validation errors loading your documents, make sure the elements within are namespaced in accordance with your schema.

Update element configuration

There have been a number of changes that affect the way you configure your schemas' elements in the 7.0 release:

If your application uses tables, replace the configuration for any such elements with configureAsRemoved for now. We'll reconfigure these elements later using the new table add-ons.

Disable structure view configuration

There have been some slight changes to the structure view API to support the new implementation and the changes in the way structure view operations are configured. For now, remove or comment out all calls to configureasstructureviewitem @ fontoxml-structure-view/src/configureasstructureviewitem.js, configureAsStructureViewStructure and configureAsTopicrefInMapStructureViewItem, and remove imports for the latter two as these functions have been removed. We'll restore the structure view configuration later in this guide.

Remove reference type registration

FontoXML 7.0 no longer uses the ReferenceType API. For now, simply remove all references to implementations of the ReferenceType base class and all calls to referenceManager.addReferenceType from your application. We'll reconfigure any reference elements used in your application later.

Disable UI customizations

All APIs related to AngularJS-based UI customizations have been removed. Remove all references to jade templates and AngularJS controllers and directives from your packages' install.js (and related files). We'll reconfigure these later using the new FDS framework.

Reconfigure the index page

Remove config/index-page.jade. In its place, create config/index-page.json with contents similar to the following, replacing title and the favicon path as desired. The favicon path may be omitted to use the default FontoXML icon.


	"title": "FontoXML for You",
	"favicon": "assets/images/your-favicon.gif"

Start your application

Now try starting your application and loading a document. If everything starts up, continue with the next steps. Common errors at this point include:

  • Trying to import files that no longer exist in the 7.0 release ("Error: Script error for X, needed by: Y")These errors shows up in the browser's development console. Check your packages for imports of the files mentioned and remove these for now.

  • Missing dependencies ("Package X not found")These errors show up in the OS terminal window that runs the fontoxml-dev-server. Double-check whether all your packages' dependencies refer to existing add-ons, and whether you included those add-ons in the upgrade package generated in the SDK portal.

  • Duplicate operations ("Error: The operation X is defined multiple times")It is no longer allowed to override operations, as this may cause unexpected behavior. This will cause the error page to appear and will show a message in the browser's developer console. Consider renaming your operations to avoid conflicts with those defined in the platform. It is still possible to re-assign a key-binding by adding it to a new operation in a package that depends on the one containing the original. If solving these conflicts is not possible, set the enable-experiment/disallow-overriding-operations @ fontoxml-operations/src/setdefaultconfiguration.js configuration value to false to disable this check for now.

  • Registry "fontoxml-structure-view" is not definedThe structure view is an add-on now. It seems the application uses it, otherwise there would have been an other error thrown. To continue, add a dependency on it.

For any other errors, please refer to the documentation on Errors.

Reconfiguring the rest of your application

The application should now be able to load your documents, although some functionality may be missing. The following steps discuss how to reconfigure the remaining parts of your application to restore its full functionality.

Reconfigure the toolbar

In FontoXML 7.0 and later, the application masthead, including all toolbars, is defined by implementing a React component registered as "Masthead" in the uimanager @ fontoxml-modular-ui/src/uimanager.js. Please refer to Create a masthead for step-by-step instructions on how to create your toolbars using FDS and fontoxml-fx components.

The following table lists directives used in FontoXML 6.x toolbars and their FDS or Fx equivalent:

FontoXML 6.x toolbar directive

FontoXML 7.0 component equivalent


fxoperationbutton @ fontoxml-fx/src/fxoperationbutton.jsx.js


mastheadtoolbarbuttons @ fds/src/components/masthead/mastheadtoolbarbuttons.js


fxoperationssplitbuttonwithdropmenu @ fontoxml-fx/src/fxoperationssplitbuttonwithdropmenu.jsx.js


fxmultioperationsbutton @ fontoxml-fx/src/fxmultioperationsbutton.jsx.js


buttonwithdrop @ fds/src/components/button/buttonwithdrop.js, drop @ fds/src/components/drop/drop.js, menu @ fds/src/components/menu/menu.js


fxoperationmenuitem @ fontoxml-fx/src/fxoperationmenuitem.jsx.js


fxmultioperationsmenuitem @ fontoxml-fx/src/fxmultioperationsmenuitem.jsx.js


menugroup @ fds/src/components/menu/menugroup.js


menuitemwithdrop @ fds/src/components/menu/menuitemwithdrop.js


fxsavebutton @ fontoxml-fx/src/fxsavebutton.jsx.js


findandreplacedropbutton @ fontoxml-find-and-replace/src/findandreplacedropbutton.jsx.js, now part of the fontoxml-find-and-replace @ /opt/app/workspace/editor-source/fontoxml-find-and-replace/readme.md add-on


fxoperationinserttablemenu @ fontoxml-fx/src/fxoperationinserttablemenu.jsx.js


symbolsgrid @ fontoxml-special-characters/src/symbolsgrid.jsx.js, now part of the fontoxml-special-characters @ /opt/app/workspace/editor-source/fontoxml-special-characters/readme.md add-on

Update add-on configuration

Various features are no longer part of the base platform in the 7.0 release, but are instead made available as separate add-ons. The following sections discuss each of these add-ons and highlight changes that should be made to their configuration to support the 7.0 release. Please also refer to the integration guide for each add-on for more details on how to integrate and use the add-on in your application, and to Application structure for the general process of integrating add-on packages in your application.

Comments (fontoxml-annotations @ /opt/app/workspace/editor-source/fontoxml-annotations/readme.md)

The fontoxml-review add-on is now integrated automatically and does not need to be mentioned in your application's files, nor be downloaded separately from the SDK portal. The fontoxml-review-workflow add-on no longer exists - the sidebar tab will be enabled automatically when fontoxml-annotations is integrated in the application.

Properties editor (fontoxml-attributes-editor @ /opt/app/workspace/editor-source/fontoxml-attributes-editor/readme.md)

The API for this add-on is unchanged. Simply integrate the add-on in your application to add the sidebar tab.

Note that, in order to save space in compiled applications, the default value for the languages configuration value has been reduced to a placeholder list containing only English and Dutch. If your application used the default list, the old dataset can be downloaded here. It can be placed in the config folder and loaded in configuration.js using something like the following:


], function (
) {
	'use strict'

	configurationManager.set('languages', languages);

Clipboard instruction (fontoxml-clipboard-instruction-modal @ /opt/app/workspace/editor-source/fontoxml-clipboard-instruction-modal/readme.md)

The clipboard instruction modal is the modal that shows up when the user clicks the “Paste” button. It explains that, due to browse security measures, Fonto can not access the clipboard through a button, and the user must press a keyboard shortcut to paste content. The paste @ fontoxml-clipboard-instruction-modal/src/operations.json operation is now provided by the fontoxml-clipboard-instruction-modal add-on. Make sure to install this add-on if you want to use this operation to provide a “paste” button in the masthead.

Find and replace (fontoxml-find-and-replace @ /opt/app/workspace/editor-source/fontoxml-find-and-replace/readme.md)

Publication preview (fontoxml-publication-preview)

This add-on was formerly called fontoxml-document-preview and has been renamed to prevent naming conflicts with other types of document previews. The operation provided by this add-on is now called open-publication-preview @ fontoxml-publication-preview/src/operations.json.

Special characters (fontoxml-special-characters)

Add one or more instances of the symbolsgrid @ fontoxml-special-characters/src/symbolsgrid.jsx.js UI component to a drop @ fds/src/components/drop/drop.js in your masthead to replace any uses of the old ui-special-character-grid directive.

Spell checker (fontoxml-spell-checker @ /opt/app/workspace/editor-source/fontoxml-spell-checker/readme.md)

Aside from becoming an add-on, the API for the spell checker is unchanged.

Structure view (fontoxml-structure-view)

In FontoXML 7.0, the structure view is provided by the fontoxml-structure-view add-on. If you want to use this feature, make sure the add-on is integrated in your application.

Please refer to the documentation for the structure view add-on for general instructions on how to configure the structure view. For those upgrading from FontoXML 6.x, the following changes are important to note:

  • The label option has been removed because setting it could unexpectedly overwrite the titleQuery property, which is now in line with the CVK TitleQuery option. To still make a static query, set the titleQuery option to the XPath string literal: titleQuery: '"static label"'.

  • The visibleChildSelectorOrNodespec parameter has been removed. Use a recursionQuery instead.

  • The structure view item will now get a default label 'Untitled ' + markupLabel, when the titleQuery isn't used or the title is empty.

  • configureAsStructureViewStructure has been removed. Use configureasstructureviewitem @ fontoxml-structure-view/src/configureasstructureviewitem.js with the isHiddenFromView option set to true to exclude ancestors of other structure view items from the structure view.

  • The structure view no longer supports widgets. To add an icon, simply pass the icon property to configureasstructureviewitem @ fontoxml-structure-view/src/configureasstructureviewitem.js.

  • The operations shown in the structure view are no longer separate from the contextual operations used in other parts of the FontoXML UI. The operations shown for an item are a combination of the contextual operations configured for the source node of the document hierarchy entry (e.g., the DITA topicref element) and those for the target DOM node (e.g., the DITA topic element at the root of the referenced document). Use configurecontextualoperations @ fontoxml-families/src/configurecontextualoperations.js or configureproperties @ fontoxml-families/src/configureproperties.js to configure contextual operations for any selector. Remember that contextual operations can be hidden from specific locations in the UI by adding the hideIn property to their configuration. The value "structure-view" may be used to hide contextual operations from the dropdown shown on the selected structure view item.

  • configureAsTopicrefInMapStructureViewItem has been removed, as its only functions were to integrate DITA map mutation operations and set a default icon ("file-text-o"). Use configureasstructureviewitem @ fontoxml-structure-view/src/configureasstructureviewitem.js with the icon option, and configure DITA map mutation operations as contextual operations on map, topicref and related elements. Please refer to the documentation for the DITA add-on for a code example.

Track textual changes (fontoxml-track-changes)

The fontoxml-review add-on is now integrated automatically and does not need to be mentioned in your application's files, nor be downloaded separately from the SDK portal. The fontoxml-review-workflow add-on no longer exists - the sidebar tab will be enabled automatically when fontoxml-track-changes is integrated in the application.

XML Source view (fontoxml-xml-view)

The XML Source sidebar tab is now provided as an add-on and will appear automatically if this add-on is integrated in your application.

Browser and references libraries

Previous releases of FontoXML have included various configurable dialogs (or modals) that could be used to compose operations that involve data entry and/or browsing. The 7.0 release contains a completely redesigned set of browse modals to replace the modals provided as part of the 6.x platform. As these add-ons provide building blocks rather than complete features, we refer to these as "libraries". The new modals should be functionally similar to the old modals, although they are more limited in their configurability. For instance, the new CMS browser does not include a search UI at this time.

However, we acknowledge that many applications have very different needs regarding how to browse and handle results. For this reason, these add-ons are provided as open source software. You are free to fork the repository and add your own modifications. Our guide on Open-source add-ons provides more details on using and modifying these add-ons.

Please refer to the documentation for each add-on for an overview of the operations and other API provided. Each interface is composed from independent components that you can add, move or delete. Use the existing compositions and the FDS documentation as a reference to guide your own implementation. Please consider the install.js file of each add-on as an example of the extra information a browse interface needs, such as the query parameters for a (CMS) data provider.

For use of these modals in operations that insert or modify references, also refer to the section below on reconfiguring references in your application. The guide on references describes in detail how the operations provided by these libraries can be composed with other steps to form operations to insert or edit elements that link to items selected in the modals.

The new CMS browse modals now have the ability to allow the CMS to control the folder where browsing starts, given a context document. To take advantage of this requires some slight extensions to the CMS browse endpoint in order to communicate the folder hierarchy for each item returned by the CMS. This functionality is optional, and enabled automatically if the CMS returns the required information.

Reconfigure tables

From release 7.0 onwards, FontoXML supports CALS tables (including CALS tables in non-DITA documents), XHTML tables and DITA simpletables with easily configurable add-ons. If your tables do not use any of these standards, please contact us so we can include support for other table standards in future releases of FontoXML.

If your application contains any custom code using fontoxml-table-flow, this code will likely no longer work in this release. Remove it from your application.

Please refer to the documentation for the add-on supporting your table model for details on how to configure table elements in your application.

A new operation table-delete is now provided by the platform. All operations on the application level doing something similar can be removed.

All set-cell-border-…, set-cell-horizontal-alignment-… and set-cell-vertical-alignment- operations are CALS table standard specific. That is why these operations are renamed to cals-set-cell-border-, cals-set-cell-horizontal-alignment-… and cals-set-cell-vertical-alignment-, see fontoxml-table-flow-cals @ /opt/app/workspace/editor-source/fontoxml-table-flow-cals/readme.md for more information about these operations.

Reconfigure references

Please refer to our reconfiguring references page for steps on how to convert the different types of references. If you would like to read more about why we changed our references mechanism please read our "How and why we changed the way our references work" page.

Reconfigure the html paste configuration

FontoXML 7.0 introduces namespace support. Because of this, the nodeName property in the pivot model translation has been renamed to qualifiedName. The content of this field is the same; the nodeName property effectively contained a qualified name, optionally including a prefix. Please refer to the Define copy & paste behaviour guide for more information.

Reconfigure custom styles

FontoXML 7.0 no longer supports SASS for defining custom styles. If your application contains any *.scss files, convert the rules within to plain CSS and include them in a styles.css file in the src folder of your package. Remove the scss files from your application. The styles.css files will be combined automatically by the development server and when building your application.

Locking and remote document state

FontoXML 7.0 includes improved support for collaboration. By default, FontoXML will periodically refresh the state of any locks from the CMS, as well as checking whether the document was updated remotely. This is then visualized using a new icon shown on every sheet frame, as well as by making documents read-only or editable when appropriate. This way, users get near-real-time feedback on the activity of other users working on the same collection of documents.

This functionality requires a new REST endpoint to be implemented by the CMS called /document/state/. This endpoint is further described in Document saving, loading, locking, and state management. If you do not wish to implement this endpoint at this time, make sure to set the remote-document-state-update-interval-ms @ fontoxml-remote-documents/src/setdefaultconfiguration.js configuration value to -1 to disable the periodic updates.

Some editors may not use locking at all. In these cases, the CMS should return all loaded documents with the lock marked both available (isLockAvailable) and acquired (isLockAcquired). To prevent the (in this case unnecessary) widgets from being shown on each sheet frame with this lock state, set the remote-document-state-hide-widget-when-acquired @ fontoxml-remote-documents/src/setdefaultconfiguration.js configuration value to true.

FontoXML will still show the widget for documents in other lock states, or when it notices that the content of the document has changed remotely. If the CMS does not implement the document/state endpoint, this could occur if a save or lock request returns a 412 status code, indicating that the revisionId provided by FontoXML no longer matches the latest stored version in the CMS.

Save and close

The save-and-close add-on and operation was used by some applications to ask Fonto to save and release locks on documents, and after that signal back to the parent window that the iframe containing Fonto can be closed. This add-on no longer exists in the 7.0 release.

Editing XML with namespaces

The 7.0 platform supports and enforces correct namespace usage. See the Handle namespaces guide for more information on using these namespaces. In short, prefer the methods on blueprint @ fontoxml-blueprints/src/blueprint.js and document @ fontoxml-dom-utils/src/typedefs.js ending in NS to those that don't, and consider using the namespacemanager @ fontoxml-dom-namespaces/src/namespacemanager.js API.

Clean up obsolete configuration values

Open config/configuration.js to update configuration values for the 7.0 platform:

  • The map-mutations-operation-names configuration value has been removed. DITA map mutation operations (and any other structure view mutations) can now be configured as contextual operations. Remove any reference to the value, then configure map mutation operations as desired as contextual operations on the map and topicref elements. Refer to the documentation for the DITA add-on for more details

  • Sidebar tabs provided by add-ons are now enabled automatically. The panes-configuration-sidebar configuration value is therefore no longer used and should be removed. If your application includes custom sidebar tabs, see the Reconfigure UI customizations section below for upgrade instructions.

  • The use-compact-masthead configuration value has been removed. To obtain a more compact masthead, set the showFontoLogo prop on your fxeditormasthead @ fontoxml-fx/src/fxeditormasthead.jsx.js to false to omit the FontoXML logo.

Reconfigure UI customizations

As FontoXML 7.0 completely replaces the UI framework, it will be necessary to reconfigure any UI customizations your application may have using FDS. Please refer to the following guides for step-by-step instructions on how to create various bits of UI in FontoXML 7.x.

  • Create a sidebar when converting a custom sidebar tab.

  • Create a popover when converting a custom popover. Consider using fxreferencepopover @ fontoxml-fx/src/fxreferencepopover.jsx.js to create popovers for your references.

  • Create a modal when converting a custom modal. Operation steps that reference a modal no longer need to include an options object. A modal is now defined by a React component, registered using the uimanager @ fontoxml-modular-ui/src/uimanager.js. It can be opened by using an operation step with type modal/MyModalComponentName, and is passed the current step data as its data prop. When determining the state of an operation with a modal step, the default value of the data prop is used as stub data for the rest of the operation.

  • For modals that support inserting and editing references, the page on Work with references discusses which of the various modal add-ons provided with FontoXML 7.0 may be appropriate for common reference types.

Additionally all imports previously done from the fontoxml-vendor-fds package are now acquired through the fds package:

import { Button } from 'fontoxml-vendor-fds/components'; → import { Button } from 'fds/components';

Changes in existing components

Component name


Additional info

All form Components:

New property "name"

The Form can track the form component with this.

The properties "onChange" and "value" or "values" are no longer required

The Form component can now handle these. Given that the component has a "name" property

All components with paddingSize property

The "paddingSize" property does now also accept an object value with separate values for 'bottom', 'horizontal', 'left', 'right', 'top', 'vertical'

multipleautocomplete @ fds/src/components/autocomplete/multipleautocomplete.js

Property is removed "filterItems"

It is no longer possible to customly filter the items.

The property "label" on "items" is now required

Property is removed "primaryLabelKey"

The primary label key should always be 'label'

Property is removed "renderItem"

MultipleAutocomplete now always renders default items

New property "onRef"

Property is removed "rendererName"

singleautocomplete @ fds/src/components/autocomplete/singleautocomplete.js

Property is removed "filterItems"

It is no longer possible to customly filter the items.

The property "label" on "items" is now required

Property is removed "primaryLabelKey"

The primary label key should always be 'label'

Property is removed "renderItem"

SingleAutocomplete now always renders default items

New property "onRef"

Property is removed "rendererName"

breadcrumbs @ fds/src/components/breadcrumbs/breadcrumbs.js

New properties:

  • "renderBreadcrumbItem"

  • "truncatedItemWidth"

There are two types of breadcrumb items now, originally 'BreadcrumbItemLink" was rendered by default

Properties are removed:

  • "onItemClick"

  • "renderGoToFolderLink"

button @ fds/src/components/button/button.js

Button automatically adjusts its styling based on its context and should now also be used in masthead and toolbar components.

New properties:

  • "hasKeyBoardBehavior"

  • "isFullWidth"

  • "onRef"

Properties are removed:

  • "onMouseEnter"

  • "onMouseLeave"

calendarinput @ fds/src/components/calendar/calendarinput.js

Property is removed "buttonLabel"

The button now only contains an icon

Property is removed "rendererName"

checkbox @ fds/src/components/checkbox/checkbox.js

New properties:

  • "validate"

  • "value"

  • ("name")

Checkbox is now also a form component

Property is removed "isSelected"

Equivalent to new 'value' property

checkboxgroup @ fds/src/components/checkbox/checkboxgroup.js

Property is removed "tooltipContent"

Each item can still have there own tooltip

datetimeselect @ fds/src/components/date-time/datetimeselect.js

Property is removed "rendererName"

New properties:

  • "hoursPlaceholder"

  • "minutesPlaceholder"

  • "secondsPlaceholder"

timeselect @ fds/src/components/date-time/timeselect.js

Property is removed "rendererName"

New properties:

  • "hoursPlaceholder"

  • "minutesPlaceholder"

  • "secondsPlaceholder"

dropbutton @ fds/src/components/drop-button/dropbutton.js

The property "renderDropContent" is replaced with "renderDrop"

New properties:

  • "onDropToggled"

  • "onRef"

The property "renderButton" has a new parameter "onFocusableRef"

Property is removed "tooltipContent"

Use the tooltipContent of the button in 'renderButton' instead

Property is removed "rendererName"

form @ fds/src/components/form/form.js

New properties:

  • "feedbackByName"

  • "labelPosition"

  • "onFieldBlur"

  • "onFieldChange"

  • "onFieldFocus"

  • "valueByName"

The Form component now manages these props for the whole form

formrow @ fds/src/components/form/formrow.js

Property is removed "labelPosition"

This property is moved to Form. Form now determines the labelPosition for all FormRow's at once

grid @ fds/src/components/grid/grid.js

New properties:

  • "itemSize"

  • "maxColumns"

  • "paddingSize"

  • "spaceSize"

The property "renderItem" no longer passes parameters through that come from item ('isDisabled', 'isInvalid', 'tooltipContent') and 'itemSize' is added to the list of parameters

griditem @ fds/src/components/grid/griditem.js

Property is removed "isInvalid"

isDisabled has the same styling

New properties:

  • "size"

  • "type"

  • "cursor"

The property "children" is now required

heading @ fds/src/components/heading/heading.js

Property is removed "paddingBottomSize"

icon @ fds/src/components/icon/icon.js

Property is removed "align"

Should be determined by the container of this component

collapsibleinlay @ fds/src/components/inlay/collapsibleinlay.js

New properties:

  • "flex"

  • "spaceVerticalSize"

keyvaluelist @ fds/src/components/key-value-list/keyvaluelist.js

The property "items" is replaced with "valueByKey"

This should be an object filled with key value pairs, each pair represents an item.

label @ fds/src/components/label/label.js

Property is removed "align"

Should be determined by the container of this component

Property is removed "isFullWidth"

Is no longer needed

New properties:

  • "letterSpacing"

  • "spaceVerticalSize"

list @ fds/src/components/list/list.js

New property "paddingSize"

The property "renderItem" no longer passes parameters through that come from item ('isDisabled', 'isInvalid', 'tooltipContent')

listitem @ fds/src/components/list/listitem.js

Property is removed "isInvalid"

isDisabled has the same styling

New property "cursor"

mastheadcontent @ fds/src/components/masthead/mastheadcontent.js

Properties are removed:

  • "paddingLeftSize"

  • "paddingRightSize"


The property "renderDropContent" is replaced with "renderDrop"

New property "type"

For determining the type of the MastheadButton

Property is removed "rendererName"


Properties are removed:

  • "isAngleDownButtonDisabled"

  • "rendererName"

  • "onItemClick"

Property is removed "items"

Use renderDrop to render items

New property "renderDrop"

mastheadtoolbar @ fds/src/components/masthead/mastheadtoolbar.js

New property "onRef"

mastheadtoolbarbuttons @ fds/src/components/masthead/mastheadtoolbarbuttons.js

New property "onRef"

multipletextinput @ fds/src/components/text-input/multipletextinput.js

New property "addButtonLabel"

itemsmenu @ fds/src/components/items-menu/itemsmenu.js

Property is removed "renderItem"

ItemsMenu now always renders default items

New properties:

  • "virtualBufferFactor"

  • "maxHeight"

Properties are removed:

  • "onItemMouseEnter"

  • "onItemMouseLeave"

menu @ fds/src/components/menu/menu.js

New properties:

  • "maxHeight"

  • "onRef"

menuitem @ fds/src/components/menu/menuitem.js

New properties:

  • "icon"

  • "iconAfter"

  • "keyBindingLabel"

  • "label"

  • "onRef"

Property is removed "children"

modal @ fds/src/components/modal/modal.js

New properties:

  • "connotation"

  • "isFullHeight"

  • "onKeyDown"

The property "size" has different possible values

's', 'm', 'l', 'none' are replaced with 's', 'm', 'l', 'auto'

modalbody @ fds/src/components/modal/modalbody.js

Property is removed "paddingSize"

Padding is now always set to paddingSize 'l'

modalheader @ fds/src/components/modal/modalheader.js

New property "connotation"

Should not be needed, the Modal passes the connotation through

multiplevaluesinput @ fds/src/components/multiple-values-input/multiplevaluesinput.js

The property "renderFormField" has a new parameter "onFocusableRef"

optionalinput @ fds/src/components/optional-input/optionalinput.js

The property "renderFormField" has a new parameter "onFocusableRef"

popover @ fds/src/components/popover/popover.js

Properties are removed:

  • "position"

  • "referenceRect"

These props will now be handled by the component self

popoveranchor @ fds/src/components/popover/popoveranchor.js

The properties "popoverFactoryName" and "popoverProps" are replaced by renderPopover

The property "renderAnchor" has a new parameter "onRef"

Property is removed "rendererName"

popoverbody @ fds/src/components/popover/popoverbody.js

Property is removed "paddingSize"

Padding is now always set to paddingSize 'm'

radiobuttongroup @ fds/src/components/radio-button/radiobuttongroup.js

Property is removed "tooltipContent"

Each item can still have their own tooltip

singleselect @ fds/src/components/select/singleselect.js

The property "label" on "items" is now required

Property is removed "primaryLabelKey"

The primary label key should always be 'label'

Property is removed "renderItem"

SingleSelect now always renders default items

New property "onRef"

Properties are removed:

  • "rendererName"

  • "onItemMouseEnter"

  • "onItemMouseLeave"

horizontalseparationline @ fds/src/components/separation-line/horizontalseparationline.js

Property is removed "marginSize"

"marginSizeBottom" and "marginSizeTop" can be used instead

verticalseparationline @ fds/src/components/separation-line/verticalseparationline.js

Default value of "size" has changed from '100%' to 'auto'

Property is removed "marginSize"

"marginSizeLeft" and "marginSizeRight" can be used instead

spinnericon @ fds/src/components/spinner-icon/spinnericon.js

New property "size"

Property is removed "align"

Should be determined by the container of this component

statemessage @ fds/src/components/state-message/statemessage.js

New property "callToAction

text @ fds/src/components/text/text.js

New properties:

  • "fontStackName"

  • "size"

textarea @ fds/src/components/text-area/textarea.js

New property "rows"

textinput @ fds/src/components/text-input/textinput.js

New property "onRef"

textlink @ fds/src/components/text-link/textlink.js

New property "onRef"

Property is removed "isHovered"

The component determines this self now

toast @ fds/src/components/toast/toast.js

New property "fontStackName"

virtuallist @ fds/src/components/virtual-list/virtuallist.js

New properties:

  • "hasKeyboardBehavior"

  • "itemKeyToUseAsId"

  • "maxHeight"

  • "onItemClick"

  • "onItemDoubleClick"

  • "onResize"

  • "virtualBufferFactor"

Properties are removed:

  • "renderEmptyState"

  • "renderRenderers"

The property "renderItem" has new parameters:

  • "isHovered"

  • "onClick"

  • "onDoubleClick"

  • "onMouseEnter"

  • "onMouseLeave"

New components

Component name




breadcrumbitembutton @ fds/src/components/breadcrumbs/breadcrumbitembutton.js


breadcrumbitemlink @ fds/src/components/breadcrumbs/breadcrumbitemlink.js


buttonwithdrop @ fds/src/components/button/buttonwithdrop.js


compactbutton @ fds/src/components/button/compactbutton.js




formfeedbackmessageslist @ fds/src/components/form/formfeedbackmessageslist.js


iframe @ fds/src/components/iframe/iframe.js


containedimage @ fds/src/components/image/containedimage.js


coveredimage @ fds/src/components/image/coveredimage.js


menugroup @ fds/src/components/menu/menugroup.js


menuitemwithdrop @ fds/src/components/menu/menuitemwithdrop.js


modalbodytoolbar @ fds/src/components/modal/modalbodytoolbar.js


modalcontent @ fds/src/components/modal/modalcontent.js


modalcontenttoolbar @ fds/src/components/modal/modalcontenttoolbar.js


orderedlist @ fds/src/components/ordered-list/orderedlist.js


orderedlistitem @ fds/src/components/ordered-list/orderedlistitem.js


popoverheader @ fds/src/components/popover/popoverheader.js


searchinput @ fds/src/components/search-input/searchinput.js


sidebarheader @ fds/src/components/sidebar/sidebarheader.js

SidebarTabContentHeader and SidebarTabContentHeading

sidebarinlay @ fds/src/components/sidebar/sidebarinlay.js

Inlay in the sidebar

sidebartoolbar @ fds/src/components/sidebar/sidebartoolbar.js


sidebartoolbaralignright @ fds/src/components/sidebar/sidebartoolbaralignright.js


sidebartoolbarbuttons @ fds/src/components/sidebar/sidebartoolbarbuttons.js


compactstatemessage @ fds/src/components/state-message/compactstatemessage.js


unicodesymbol @ fds/src/components/unicode-symbol/unicodesymbol.js


virtualgrid @ fds/src/components/virtual-grid/virtualgrid.js

Can replace Grid, especially when the grid is large

Removed components

Component name

Replaced by

Additional info


calendarinput @ fds/src/components/calendar/calendarinput.js or datetimeselect @ fds/src/components/date-time/datetimeselect.js


Block or Flex


containedimage @ fds/src/components/image/containedimage.js or coveredimage @ fds/src/components/image/coveredimage.js


button @ fds/src/components/button/button.js

Button will derive the styling from the context in which it's used.


mastheadtabbuttons @ fds/src/components/masthead/mastheadtabbuttons.js or mastheadtoolbarbuttons @ fds/src/components/masthead/mastheadtoolbarbuttons.js


dropbutton @ fds/src/components/drop-button/dropbutton.js

DropButton will derive the styling from the context in which it's used.



Directly use FontoLogo or your own logo instead.


buttonwithdrop @ fds/src/components/button/buttonwithdrop.js

Use a ButtonWithDrop with an "onClick" prop.





You no longer need to make custom renderers with custom positioners. All components that need these already have them build-in.



You no longer need to make custom renderers. All components that need these already have them build-in.




sidebarheader @ fds/src/components/sidebar/sidebarheader.js


sidebarheader @ fds/src/components/sidebar/sidebarheader.js



Use the tooltipContent property that is on supported components.



Use the tooltipContent property that is on supported components.

Changes in system utilities

System utility


buttonbase @ fds/src/system/styles/button/buttonbase.js

Has parameters "isFullWidth", "paddingSizeHorizontal" and "height"

color @ fds/src/system/styles/color/color.js

New colors "chip-background:hover", "content-background:selected", "form-field-border-connotation-muted", "form-field-border-connotation-success", "form-field-border-connotation-error", "form-field-border-connotation-warning", " "form-field-border-connotation-info", "form-field-placeholder-color", "grid-item-default-background", "grid-item-unicode-symbol-background", "menu-item-with-submenu-background", "menu-item-with-submenu-background:hover", "modal-backdrop-background", "modal-content-background", "modal-content-border", "modal-content-toolbar-background", "modal-content-toolbar-border", "modal-header-warning-background", "popover-header-background", "popover-header-warning-color", "sidebar-background", "structure-view-node-children-border", "structure-view-node-item-background", "structure-view-node-item-background:hover", "structure-view-node-item-border", "structure-view-node-item-border:hover", "structure-view-node-item-active-document-background", "structure-view-node-item-active-document-background:hover", "structure-view-node-item-active-document-border", "structure-view-node-item-active-document-border:hover", "structure-view-node-item-parent-of-active-document-background", "structure-view-node-item-parent-of-active-document-background:hover", "structure-view-node-item-parent-of-active-document-border", "structure-view-node-item-parent-of-active-document-border:hover", "table-size-grid-item-background", "table-size-grid-item-background:hover", "table-size-grid-item-border", "table-size-grid-item-border:disabled", "table-size-grid-item-border:hover", "tab-button-border", "tab-button-border:active", "tab-button-color", "tab-button-color:active"

Removed colors "grid-item-background", "sidebar-tab-content-background", "tab-button-background", "tab-button-background:active", "masthead-route-heading-background" and "masthead-route-heading-color"

Renamed colors masthead-button-default-... -> masthead-button-masthead-... and masthead-button-tab-... -> masthead-button-masthead-tab-...


The allowed values for flexDirection have changed. Changed from horizontal -> row, vertical -> column, horizontal-reverse -> row-reverse and vertical-reverse -> column-reverse

inlineflex @ fds/src/system/styles/flex/inlineflex.js

The allowed values for flexDirection have. Changed from horizontal -> row, vertical -> column, horizontal-reverse -> row-reverse and vertical-reverse -> column-reverse

fontsize @ fds/src/system/styles/font-size/fontsize.js

Does no longer accept the value "heading-pane" as font size name


New possible value for font stack name "monospace"

margin @ fds/src/system/styles/margin/margin.js, marginbottom @ fds/src/system/styles/margin/marginbottom.js, marginhorizontal @ fds/src/system/styles/margin/marginhorizontal.js, marginleft @ fds/src/system/styles/margin/marginleft.js, marginright @ fds/src/system/styles/margin/marginright.js, margintop @ fds/src/system/styles/margin/margintop.js and marginvertical @ fds/src/system/styles/margin/marginvertical.js

An extra possible value in all margin size utilities "sm"


Does now also accept an object value with separate values for "bottom", "horizontal", "left", "right", "top" and "vertical"

scrollcontainer @ fds/src/system/styles/scroll-container/scrollcontainer.js

New parameter "overflowY"

New system utilities

Removed system utilities

  • withBoundClosures

  • filterItemsKeyContainingValue

  • focusable

  • onlyResolveLastPromise

  • formField

  • formFieldBase

  • formFieldInput

  • inlineFormField

  • label

  • registerPopoverFactory (use renderPopover in PopoverAnchor instead)

  • reset

  • registerTooltipFactory

  • truncate

  • truncateContainer

  • zIndex

  • isNumeric

  • withWindowEvent

Known issues

FontoXML is known to be incompatible with browser extensions that modify the page. This is characterized by poor performance or an unresponsive editor, and the error message "Detected unexpected view mutation, reverting" being displayed in the browser's developer console. We always try to work with the developers of such extensions to resolve any problems. If you encounter an incompatible browser extension, please contact us and disable or remove such extensions when working with FontoXML.