Upgrade from 6.8 to 6.9

The 6.9.0 platform release has removed some deprecated features. Usage of these features must be removed to be able to run the instance again.

Starting with this release, make sure to upgrade any localization message bundles after upgrading the FontoXML platform. Please refer to the localization documentation for more details.

Upgrading XPath usage

Before upgrading, assure no XPath related warnings are printed in the console when using the instance. After upgrading, these warnings will be errors, triggering the operation failed modal when executed.

As noted in the Upgrading XPath usage upgrade instruction, the deprecated syntax has been removed. Following this upgrade instruction has also removed any usage of custom tests. The registration of any custom tests on the instance level can also be removed.

This means that any code using the Selectors#matches function should be rewritten to using evaluateXPathTo* functions. This will also simplify a lot of code because dom traversal is usually more readable in XPath, compared to doing it manually.

This upgrade instruction will resolve the error Error: Script error for "fontoxml-selectors/addXPathCustomTest", needed by: ...

  1. Locate all calls to addXPathCustomTest.

    These calls are usually found in configureSxModule.js files.

  2. Remove them, and remove the dependency on the filefontoxml-selectors/addXPathCustomTest.

  3. Load the instance, it should be able to load without any errors.

The instance does not show errors for not being able to find the file addXPathCustomTest.js.

Selectors as string

Besides the deprecated match* functions, the extensibility functions (require(Parent|Sibling|Descendant|...)) have also be removed. This has been done so that the whole Selector instance previously defining the 'matches' method can be internalized. The adaptNodeSpecToSelector function is now effectively a no-op, returning the inputted string if it was a valid XPath. Due to legacy reasons, the node-name shorthand is still available, though it is deprecated.

Because selectors are now always a string, the need for the fluent API is absent, it is now possible to build XPaths using string concatenation: adaptNodeSpecToSelector('self::abc').requireParent('name() = ("def")') should be rewritten to self::abc and parent::*[name() = 'def']. This is why the nodeName shorthand is deprecated starting from this release: to be able to build XPaths from strings from parameters, we should be able to assume they are valid XPaths. The NodeSpec 'abc' equaled to the XPath self::abc. Naively composing this NodeSpec into another selector, like `${selector}[@attr]`, we'd get abc[@attr], which is short for child::abc[@attr].

To prevent these kind of bugs in the future, and to improve predictability, nodespecs must be XPath selectors and will not be rewritten to use the self:: axis if they are just a nodeName. This release will use warnings to indicate where this happens but does not change any behavior.

Do note that this only affects the 'selectorOrNodeSpec' kind of parameters seen in for example SX configuration. The 'NodeSpec' kind of parameter seen in domQuery has not been affected, though it would be preferred to move to using XPath for querying the DOM.

  1. Find any usages for Selector#matches(Node: node, Blueprint: blueprint), Selector#getBucket or the Selector instance in general

  2. Replace them by calling the evaluateXPathToBoolean, passing the 'selector' as the first argument.

  3. Try to see if the dom traversal can rewritten to use more XPath

    Some code can be simplified to use other XPath related APIs, instead of manually traversing the DOM.

    JavaScript

    var ancestor = blueprintQuery.findClosestAncestor(blueprint, node, function (ancestorNode) {
    	return evaluateXPathToBoolean('self::someElement[@someAttribute="someValue"]', node, blueprint);
    });

    Can be rewritten to the following:

    JavaScript

    var ancestor = evaluateXPathToFirstNode('ancestor::someElement[@someAttribute="someValue"], node, blueprint);

    The instance should now be able to start, though it might warn about using nodeNames as selectors.

  4. Update SX config to use selectors instead of nodeNames

    Most code will look like this:

    JavaScript

    configureAsBlock(sxModule, 'paragraph', ...);

    This must be changed to look like the following:

    JavaScript

    configureAsBlock(sxModule, 'self::paragraph', ...);
  5. Update operations to use selectors instead of nodeNames

    There are two transforms supplied by the platform which accepted a nodeSpec: setContextNodeIdToSelectionAncestor and split-and-insert.

    Because upgrading the operations.json files in which they occur might mean they become very wide (over 140 characters), an extra parameter has been added to these two transforms. They can be used if the old nodeSpec was an array of nodeNames. These are called "selectionAncestorMatchesSomeOf" for setContextNodeIdToSelectionAncestor and "splitUntilAncestorThatMatchesOneOf" for split-and-insert.

    Affected operations may look like this:

    JavaScript

    ...
    	"steps": [
    		{
    			"type": "setContextNodeIdToSelectionAncestor",
    			"data": {
    				"selectionAncestorNodeSpec": "someElement"
    			}
    		}
    	]
    ...

    This can be rewritten to the following:

    JavaScript

    ...
    	"steps": [
    		{
    			"type": "setContextNodeIdToSelectionAncestor",
    			"data": {
    				"selectionAncestorNodeSpec": "self::someElement (: or name() = 'someElement' :)"
    			}
    		}
    	]
    ...

    The array notation ("selectionAncestorNodeSpec": ["someElement", "someOtherElement"]can be rewritten to "selectionAncestorMatchesSomeOf": ["self::someElement", "self::someOtherElement"].

  6. Update attribute configuration to use full selectors instead of nodeNames

    The attribute configuration JSON file may also contain nodeName selectors. They should be rewitten.

  7. Try to load the instance, open all the toolbar tabs and dropdowns, and assert that no warnings are logged on the console.

    If there are still errors, try to search for the mentioned nodeSpec. They may be passed as a value for 'titleSelectorOrNodeSpec' or 'ignoredForNavigationNextTo' in SX configuration.

The instance can be loaded and used without any errors on the console.

Upgrading single document hierarchy

This only affects instances using the single-document-hierarchy addon. This addon splits a single document into multiple sheets. Splitting a single document into a hierarchy enables viewport culling for improved perfomance.

The new single document hierarchy enables a recursive hierarchy, instead of a list. To support this, the hierarchy-node-selector configuration value has been replaced with an XPath query. By following these instructions, the old behaviour will be restored.

  1. Open the configuration and locate the configurationManager.set('hierarchy-node-selector', …);line

  2. Rename the configuration value from hierarchy-node-selector to hierarchy-node-query

  3. Port the selector to the equivalent XPath Query

    The XPath query configured here is executed relative to the document node, and then recursively to any node resulting from it.

    The single document hierarchy filters the result of the query to only contain the top level descendants. This does not have to happen in the configured query.

    The equivalent XPath for all divs in an HTML document (was self::div), becomes html/body/div.

    Do not use an absolute XPath expression (i.e., one starting with / or //). These expressions yield the same result regardless of the node relative to which they are executed, resulting in an infinite document hierarchy.

  4. Test the changes. Assert nothing is rendered twice.

The loaded document is split into multiple parts again.

Using simple types

FontoXML now allows validating most elements with simpletypes.

  1. Upgrade the schema, with strictMode = true, in the fonto.json file.

  2. Start the instance, with the developer console open.

  3. If the console contains warnings referring to simple types, the schema contains simple types which are not yet supported to be validated. They are always assumed to be correct (just like older versions of FontoXML).

    The warnings in the console are only shown in development mode. They are removed in production builds of the instance.

    An instance can safely be used with these warnings. Extra care should be taken when editing elements with unsupported simple types. Running the instance with strict mode off introduces more risks, because all validation of simple type content will be disabled.

  4. Check for disabled operations, which should be enabled.

    It is possible a mistake has been made on the instance level, making elements with simple types invalid. Because the platform now actively checks these elements, old bugs can be unsurfaced.

Check your .gitignore file

This instruction only applies to instances that use Git to manage their source code. If you have previously adapted the .gitignore file for a different source control system, make appropriate changes for that system.

This release of FontoXML introduces the Fonto Design System (FDS), a new library of reusable UI components designed to make it easier than ever to customize the UI of your FontoXML instance. Unfortunately, we have discovered during testing that some instances contain a misconfigured .gitignore file, which may cause important components of FDS to not be committed to git.

  1. Open .gitignore in the root folder of your FontoXML project.

    Note that the name of this file starts with a dot, causing it to be hidden on some systems. You may need to enable display of hidden files in your OS or editor for the file to appear.

  2. Check for and update lines that ignore entire folders

    Each line of the .gitignore file is a pattern matching filenames and/or paths. Instead of using, e.g., dist/ to ignore the dist folder, use /dist/ to only match the dist folder in the root of the project.

    A typical .gitignore file for a FontoXML instance is shown below. Note how every directory pattern starts with a “/”:

    Shell

    !.gitkeep
    
    
    # Development dependencies
    /node_modules/
    
    
    # Directories used for building the application
    /dist/
    /tmp/
    
    
    # Save directory for the development server
    /dev-cms/uploads/*
    
    
    # Shared packages
    /packages-shared/
  3. (Optional) re-download and unpack the upgrade to the 6.9.0 platform

    If you (or someone else) upgraded the platform without making these changes, important files may be missing from source control. Re-download the upgrade package to make sure no files are missing.