Upgrade from 7.13 to 7.14

A number of APIs will be removed in the 7.16 release. They are listed on the Upcoming removals 7.16 page.

Please update your copy of FDT. If you have it globally installed, you can run the following command from anywhere:

Shell

npm install -g @fontoxml/fontoxml-development-tools

Mandatory changes

Most of the APIs have already been deprecated in past releases so it is possible that some of these changes have already been applied to your editor.

The instructions are grouped by their area and then sorted by difficulty.

Obsolete and unused react props

The following props or usages of props in Fonto components are deprecated:

  • The prop truncatedItemWidth of the Breadcrumbs component does not have to be set. It is safe to remove its usage.

  • The prop isFullColor of the FontoLogo component will be removed. It has been obsolete since the new Fonto logo we introduced in the 7.5 release. It is safe to remove its usage.

  • The prop onlyUpdateStateAgainAfterMs of the FXOperationButton will be removed. It is safe to remove its usage.

Unused FDS constants

  • The truncatedBreadcrumbItemLinkWidth and the truncatedBreadcrumbItemButtonWidth imports are unused. They can safely be removed.

Unused CVK properties

Renames

The following renames have taken place in recent Fonto versions. Currently, they still work because the old name is aliased to the new one, but this will be removed in the 7.15 release.

Operations

  • The unload-dita-document operation is the same as the unload-document operation.

    • Replace all occurrences of the old unload-dita-document operation with the new unload-document operation.

  • The open-ui-pane operation has been replaced with the open-sidebar-tab operation.

  • The toggle-ui-pane operation has been replaced with the toggle-sidebar-tab operation.

Files

The following files have had their extension changed:

The following files have been moved to a different directory:

  • The file addDragAndDropOperation.js was moved to the directory fontoxml-structure.

  • The file StructureView.jsx was moved to the directory fontoxml-structure.

  • The file getClosestStructureViewItem.js was moved to the directory fontoxml-structure.

  • For all of these files, simply change the fontoxml-structure-view part of the import to fontoxml-structure.

  • The file configureStructureViewItemProperties.js was moved to the directory fontoxml-families.

  • The file configureAsStructureViewItem.js was moved to the directory fontoxml-families.

  • For all of these files, simply change the fontoxml-structure-view part of the import to fontoxml-families.

Configuration variables

The following configuration variables have changed:

The configuration value maximum-number-of-find-results is now included in the find-and-replace-configuration.

The configuration value wiris-initialization-parameters is now called wiris-mathtype-initialization-parameters.

The scope property wirisEditorScriptUrl was replaced with the wiris-mathtype-script-url configuration variable.

Connectors

In the 7.8 release, we have changed how connectors work. If you use the old way of configuring connectors, please follow the Upgrade Instructions from 7.7 to 7.8 to upgrade your custom connectors if you have not already done so.

Image families

In the past, all of these families (configureAsImage, configureAsInlineImage, configureAsImageInFrame and configureAsInlineImageInFrame) assumed the application used permanent ids. For all of these families, replace the argument like this:

JavaScript

// Before:
configureAsImage(sxModule, 'self::img', 'image', 'href');
// After:
configureAsImage(sxModule, 'self::img', 'image', {referenceQuery: '@href', isPermanentId: true});

Widgets

LabelQueryWidget

A number of widgets are obsolete with the introduction of the LabelQueryWidget. Replace them accordingly:

createAttributeLabelWidget:

We are aware of a known issue in Fonto Editor 7.12.0 where the deprecation warning for createAttributeLabelWidget is thrown from the platform code of Fonto Editor.

If you see the message "createAttributeLabelWidget is deprecated and will be removed in 7.14. Please use the createLabelQueryWidget instead. See Upcoming deprecations 7.14 for more information.", perform a manual search through your editor for "createAttributeLabelWidget" and replace occurrences as described below.

JavaScript

// Before
createAttributeLabelWidget('title')
// After:
createLabelQueryWidget('@title', { inline: true })

JavaScript

// Before
createAttributeLabelWidget('title', {
	prefix: '[',
	suffix: ']',
	defaultValue: '(no title)'
})
// After:
createLabelQueryWidget('(@title, "(no title)")[1]', {
	inline: true,
	prefixQuery: '"["',
	suffixQuery: '"]"'
})

createBulletingWidget:

JavaScript

// Before
createBulletingWidget('-')
// After:
createLabelQueryWidget('"-"')

RelatedNodesQueryWidget

createRelatedNodesWidget:

JavaScript

// Before
createRelatedNodesWidget('self::fn')
// After:
createRelatedNodesQueryWidget('descendant::fn => outermost()')

Overriding operations, actions and transforms

Overriding operations, actions and transforms trigger a warning. It will trigger an error starting from the 7.14 release. For every operation, action or transform that causes these errors, find out why the override happens and find a public API to do the same.

Rebasing forked table flow packages

The table implementations for .fontoxml-table-flow-cals, fontoxml-table-flow-xhtml, fontoxml-table-flow-tei and fontoxml-table-flow-basic are open source to allow others to fork them to make improvements. In recent releases, we have improved the performance of our versions a lot. Please rebase your local version. If you have made changes to your version, consider to pull-request them. If those changes are integrated, we will maintain those changes so that you can use the version that is supported by the platform.

CellsHighlightButton

The CellsHighlightButton component that was introduced in the 7.13 release is replaced by the CellHighlightModeSwitch in the 7.14 release.

Fonto Review reference configuration SheetFrameHeader

The SheetFrameHeader component has been removed from the Fonto Review reference configuration. Use the default SheetFrameHeader instead. See the guide on SheetFrameHeaders for more information. The SheetFrameHeader component included in the reference configuration was an old copy of the default SheetFrameHeader of the Fonto Editor platform.

Fonto Content Quality

If you're using Fonto Content Quality, please also refer to the specific upgrade instructions.

Recommended changes

In Fonto Editor 7.13 we changed some of our behavior in regards to managing focus. This causes the editor to no longer aggressively steal the focus from the host page. As a side effect this causes the editor to no longer be automatically focused when loaded into an iframe. Adding window.focus() in the CMS code will enable the focus on the Fonto Editor frame and scroll the cursor to the previously expected position.

Use curated text functions in title queries

The fonto:curated-text-in-node and fonto:curated-text-in-range functions were introduced in release 7.9.0 to provide a convenient way to obtain a plain text representation of a node or range. The advantage of these functions over other approaches (such as casting nodes to strings in XPath) is that they take configuration into account. Starting from this release, we've extended these functions to also include the text for any elements that are configured as an inclusion.

In cases where titles in your application may contain inclusions, footnotes or removed elements, consider updating the corresponding titleQuery configuration to make use of these functions. That way, any Fonto UI making use of this configuration can automatically take advantage of these improvements.

When using the fonto:curated-text-in-node function, please be aware that calling this function will fail if the argument is not exactly a single node. When using a path or other expression that may result : in zero or multiple nodes, consider using an expression such as the following : to avoid errors:

JavaScript

// Instead of a titleQuery that results in zero or more elements...
configureProperties(sxModule, 'self::topic', {
	titleQuery: './title'
});

// ...import and use the configuration-aware curated text functions.
// The expression used here also gracefully handles cases where the 
// `./title` path returns either no nodes or more than one node.
configureProperties(sxModule, 'self::topic', {
	titleQuery: 'import module namespace fonto = "http://www.fontoxml.com/functions"; string-join(./title ! fonto:curated-text-in-node(.))'
});

Rebase forks of fontoxml-crosslink-references

In introducing a new API to enable the "Edit reference" link in the open-document-preview-modal operation, we've made some changes to remove usage of a previously internal version of that API in the fontoxml-crosslink-references add-on. This is an open-source add-on. If your application includes a fork of this add-on rather than the version included in the platform, please rebase your changes on the most recent version to ensure that the "Edit reference" link continues to work for previews opened from cross-link popovers.

Table highlighting button

The Fonto 7.13 release introduced a way to select multiple cells at once. It did this by introducing a button which allowed an author to chose a first cell, a second cell, and so on.

Fonto 7.14 removes the use of that button. Editors that used the old CellsHighlightButton should now use the new CellHighlightModeSwitch. This new switch will also introduce the new behavior to select multiple cells.

The cell highlight mode is still only usable for certain specific operations. For more information on working with the cell highlight mode, see the documentation on the setCellNodeIdsToHighlightedCells and the setBordersByCellNodeIdToHighlightedCells transforms. More operations will support the cell highlight mode in the future.

Add labels to operations with shortcuts

This release of Fonto Editor introduces a shortcut overview modal, which can be opened through the keyboard icon in the Editor status bar. This modal shows operations that have keybindings configured with their label and icon. Operations that don't have a label configured will be hidden from the overview. If you have defined operations with a keybinding that should be included in the modal, please give those operations a label and possibly an icon.

If your operation has an empty label, please remove that empty label or configure it to let it show in the modal.