Upgrade from 7.8 to 7.9

For the full release notes, head over to Fonto 7.9.0

Starting from this release, new Fonto Editor SDK versions can only be obtained through the Fonto Development Tools. The SDK portal will remain on version 7.8.3 and will be taken offline in the coming months. Please make sure to install the latest version of the Fonto Development Tools. Installation instructions are available on its npm page.

Required changes

Fonto Development Tools

As a result of changes made to be able to work with multiple Fonto Editor SDK versions, the fdt editor init and fdt editor upgrade commands will now prompt for a version number instead of assuming the latest stable version. If you run these commands non-interactively, please make sure to specify the --version option. The fdt editor schema compile command requires the --version option only when running it from a directory which doesn't contain a Fonto Editor instance. Additionally, fdt editor upgrade cannot be used to add/remove Fonto Editor add-ons anymore. Please use the new fdt editor add-ons command instead.

Changes to how we run XPath/XQuery

The 7.9 release of Fonto brings two large changes to how Fonto executes XPath queries. In most, if not all cases, the behaviour should not be affected, except for a number of very specific uses:

Default language is XQuery

Starting from Fonto 7.9, the default language of all XPath related APIs is actually XQuery. This means XQuery-only features such as importing namespaces, declaring modules and more is now possible in APIs like evaluatexpath @ fontoxml-selectors/src/evaluatexpath.js or usexpath @ fontoxml-fx/src/usexpath.jsx. Because all XPath expressions are valid XQuery too, this should not affect any of your queries. There is one rare case where it may affect your query, when using XML-style character references. Previously, the XPath string """ would by interpreted as a string with a length of 6 characters. However, in XQuery,this string only has a single character, since the character reference will be resolved. If this occurs anywhere in an XPath that was not being interpreted as an XQuery script, the string should be re-encoded: """ should become """.

Document type declarations (DOCTYPE)

The Fonto editor uses FontoXPath to evaluate XPath and XQuery. Older versions of FontoXPath contained a bug regarding document type declarations (<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">). It regarded them as children of the document node. According to the XPath XQuery Data Model (XDM) specification, DOCTYPE declarations are not a child of the document node. This bug is fixed in FontoXPath, but it may cause a possibly unwanted behavioral change when loading documents that use Document Type declarations.

If your editor does not edit documents that use Document Type nodes, in the following cases:

  1. When storing paths to a node in an external system in format like this: /node()[2]/node()[2]. The offsets will be effectively off-by-one when using the new version of Fonto. A better approach of storing these paths would be to either rewrite your paths by incorporating node names like this: /xml/body[1]/div[3]/p[2], or by at least assuming the position will always reside in the document element of a document, by making the paths look like this: /*/node()[2]/node()[2].

  2. When navigating to the document type node using XPath or XQuery. Because document type nodes are not part of the XDM, they can not be navigated to. This navigation needs to be done by configuring a custom XPath function that performs this navigation instead.

Image Browsing

In certain cases, when not passing a browseContextDocumentId, the editor could crash when trying to replace an image without a selection. Because passing a referrerDocumentId to FxImageLoader was optional and when you do not pass it, FxImageLoader was assuming that referrerDocumentId is the id of selected document. However this is not always true. that's why we made referrerDocumentId for FxImageLoader required. To fix this, we made a few changes to the fontoxml-cms-browser.

To fix your editor, you should follow these steps:

  • Update any forks you have of fontoxml-cms-browser.

  • At the moment, you are using 'open-image-browser-modal' operation as a step for an operation to insert an image and another operation to edit your images in your editor. Find these operations to insert and edit your images.

  • To make these operations work without any problem, you need to pass 'browseContextDocumentId'.

    • For the image editing operation, you need to transform 'contextNodeId' to 'browseContextDocumentId' just before using 'open-image-browser-modal'. You need 2 transforms for this: respectively setDocumentIdToDocumentContainingContextNodeId and setRemoteDocumentIdFromDocumentId. After you add these transforms before 'open-image-browser-modal', it should look like:

      Operation to edit your image

      JSON

          "your-operation-to-open-image-browser-for-edit": {
              "steps": [
                  {
                      "type": "transform/setDocumentIdToDocumentContainingContextNodeId"
                  },
                  {
                      "type": "transform/setRemoteDocumentIdFromDocumentId"
                  },
                  {
                      "type": "operation/open-image-browser-modal",
                      "data": {
                          "browseContextDocumentId": "{{remoteDocumentId}}"
      					// your other data if exist
                      }
                  }
                  // your following operations
              ]
    • For image insertion operation, you need to transform the id of selected element to 'browseContextDocumentId' just before using 'open-image-browser-modal'. You need 3 transform for this: respectively setContextNodeIdToSelectedElement, setDocumentIdToDocumentContainingContextNodeId and setRemoteDocumentIdFromDocumentId. After you add these transforms before 'open-image-browser-modal'. It should look like:

      Operation to insert your image

      JSON

          "your-operation-to-open-image-browser-for-insert": {
              "steps": [
      			{
      				"type": "transform/setContextNodeIdToSelectedElement"
      			},
                  {
                      "type": "transform/setDocumentIdToDocumentContainingContextNodeId"
                  },
                  {
                      "type": "transform/setRemoteDocumentIdFromDocumentId"
                  },
                  {
                      "type": "operation/open-image-browser-modal",
                      "data": {
                          "browseContextDocumentId": "{{remoteDocumentId}}"
      					// your other data if exist
                      }
                  }
                  // your following operations
              ]

Fonto Review

If you are coming from a Fonto version prior to 7.8.2 and have not yet read the upgrade instructions for the upgrade to 7.8.2, read them here. Those upgrade instructions describe a required upgrade step.

Recommendations

Table performance

This release of Fonto Editor improves table performance, for this we have also made some changes in fontoxml-table-flow-cals, fontoxml-table-flow-tei and fontoxml-table-flow-xhtml. We advise you to update any forks you have of this.

New Find and Replace

The Find & Replace interface has been moved to a sidebar, which is automatically enabled if you use this add-on, where a better representation of search results and progress is given than before. The old Find & Replace dropdown still works, but it has been slimmed down to better suit screen estate restricted editors. We advise you to remove the old dropdown button from the masthead, if you do have the old Find and Replace and have no specific use case to still use the dropdown.

Initially collapsed outline levels

This release introduces a new structure-view-expand-items-until-level configuration value that allows controlling until what level the items of the structure view are expanded when opening the outline. We recommend implementing this feature for editors with large documents or with a deeply nested outline.

Font Awesome 5 (Pro)

We've upgraded from Font Awesome 4.7.0 to Font Awesome 5 (Pro) in this release. This means that almost every icon has changed visually. Eg. the save icon still looks like an icon to indicate a save operation but the shape of the floppy disk is different.

Some icons have also changed in name, eg. the save icon used to be called (fa- or icon-)floppy-disk-o, but now its called fa-save. Note, this does not mean you have to change the name yourself, the old name will resolve to the new name automatically.

Font Awesome 5 has also formally introduced a concept of icon styles, independent of icon name (shape / intended use case). Most icons can now be displayed in 3 different styles: light, regular or solid. This mostly influences the line-width of the icon shape or whether the icon shape is filled or not.We've chosen the regular style as the default style if you do not specify it explicitly (which is what happens if you just do the editor upgrade without making any manual changes).

More details can be found under the "Font Awesome" Concept guide. Make sure to read through that guide so you know how you can (optionally) change the style of an upgraded icon and how you could start to use some of the more advanced features of Font Awesome 5 (Pro) such as duo-tone and/or stacked icons.