Upgrade from 7.6 to 7.7

Required Changes

FDT

This release of Fonto Editor introduces an all new version of its build tools, which are used for running development builds and creating production builds. This version brings much-desired improvements such as faster editor reloads during development and support for modern JavaScript. The build tools are an integral part of the Fonto Development Tools (FDT), and as such, the latest version of FDT is required to work with version 7.7 of Fonto Editor. Please run npm i -g @fontoxml/fontoxml-development-tools to install it. This version of FDT is compatible with previous versions of Fonto Editor, albeit without the mentioned benefits.

Upgrading your Fonto Editor instance

Run fdt editor upgrade to upgrade your Fonto Editor instance to version 7.7. This command will automatically convert the configuration of your Fonto Editor instance to work with the latest version of Fonto Editor and its build tools. Most notably, this will convert all AMD modules to ES modules, and attempt to clean up all obsolete files and configuration. Before running fdt editor upgrade, please make sure all packages required for running your Fonto Editor instance are present in either the packages or the packages-shared folder.

Please take extra care if you have Fonto Editor configuration in a 'shared' package i.e. a package in the packages-shared directory, usually downloaded by a package manager like Bower. The latest version of FDT will not invoke npm install commands, which potentially prevents these packages from being downloaded automatically if that depends on running a defined in the root-level .

The fdt editor upgrade command may output warnings which are saved to a file on disk named convert-warnings.log, so you can review and fix any issues later on.

Syntax changes

After the upgrade, you'll be able to write ES modules and ES2015+ in all JavaScript files. In addition, there are a couple of subtle syntax changes:

  • Imports need to be explicit and have to include the src directory and a file extension, e.g. my-package/src/install.js.

  • The file loader syntax (text!, json!) is unsupported; loading is now fully based on file extensions.

  • The .xqm file extension is reserved for XQuery Modules, which do not require manual registration anymore. They are processed and registered automatically, similar to operation JSON files.

  • SVGs (for custom icons) do not require the text file loader (text!) for imports. They are processed based on their file extension.

  • JSX files are required to have .jsx as file extension instead of .jsx.js.

Code formatting

The configuration conversion mentioned above results in most configuration being formatted by Prettier. If you like to replicate the same code formatting in your set-up, you can either use Fonto's ESLint configuration for an ESLint-based set-up, or use Prettier directly using the following .prettierrc settings:

.prettierrc

JSON

{
    "printWidth": 100,
    "quoteProps": "consistent",
    "singleQuote": true,
    "tabWidth": 4,
    "useTabs": true
}

Known issues

  • There's a known issue with adding or deleting files while fdt editor run is running. It occurs when the addition or deletion causes a file override, e.g. when you add packages/my-package/src/install.js while packages-shared/my-package/src/install.js already existed before running fdt editor run. This issue prevents a cache from being invalidated for the file, meaning the build will still include the already existing (overridden) file and not the newly added file. Rerunning fdt editor run resolves this issue.

Converting code

If your workflow requires a manual configuration conversion, for instance because you used the SDK portal for upgrading your Fonto Editor instance instead of fdt editor upgrade, please refer to the following instructions.

Convert a Fonto Editor instance

To convert all configuration and make it compatible with Fonto Editor 7.7, you can perform the following steps:

  1. Make sure to install and use the latest FDT version (2.4.0 or greater).

  2. Open a CLI in the Fonto Editor instance directory.

  3. Run fdt editor convert-for-770 editor, check the paths and confirm to continue.

  4. Make sure the platform directory contains Fonto Editor 7.7.

  5. Check if the editor is working correctly by running fdt editor run (see --help for options).

Convert a configuration package

To convert the configuration of a single package and make it compatible with Fonto Editor 7.7, you can perform the following steps:

  1. Make sure to install and use the latest FDT version (2.4.0 or greater).

  2. Open a CLI in the configuration package directory.

  3. Run fdt editor convert-for-770 package, check the paths and confirm to continue.

  4. Check if the configuration is working correctly by using it in a Fonto Editor 7.7 instance.

When you already upgraded (and converted) an editor or package, and have open changes you want to integrate which are based on unconverted code, you can use the commands mentioned above to ease the integration.

SDK portal deprecation

Fonto's SDK portal is deprecated and will be removed in the future. Please use FDT instead, if you're not already doing so.

Update references in example documents

For historical reasons, any (document) references in example documents served by the build tools were automatically postfixed with the file extension if it was omitted. This behaviour has now been removed for clarity, which might result in incorrect references in example documents, which in turn prevents documents from being loaded in the editor. This can be resolved by updating these references to include file extensions.

Remove duplicate operations

Fonto Editor 7.7 defines a number of operations which can be extended if required. The following operations were previously often manually configured, and likely cause issues because they're now duplicate:

To resolve this, please remove the manually configured operations. Instead, use the new addAlternativeOperation API to add custom behaviour to shortcuts such as tab and shift+tab. Indenting or outdenting list items, navigating in tab navigation contexts and inserting new rows at the end of a table should work by default.

Remove FadeIn component usage

The component of FDS has been removed and should be replaced with a Flex component. If you were already rendering a component inside the component, you can just remove the surrounding component. Make sure to remove the

For example:

JavaScript

<FadeIn>
	{({ onRef }) => (
		<Flex alignItems="center" flex="1" flexDirection="column" onRef={onRef}>
			My content
		</Flex>
	)}
</FadeIn>

Should become:

JavaScript

<Flex alignItems="center" flex="1" flexDirection="column">
	My content
</Flex>