Upgrade from 7.6 to 7.7
Required Changes
F DT
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 addpackages/my-package/src/install.js
whilepackages-shared/my-package/src/install.js
already existed before runningfdt 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. Rerunningfdt 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:
-
Make sure to install and use the latest FDT version (2.4.0 or greater).
-
Open a CLI in the Fonto Editor instance directory.
-
Run
fdt editor convert-for-770 editor
, check the paths and confirm to continue. -
Make sure the
platform
directory contains Fonto Editor 7.7. -
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:
-
Make sure to install and use the latest FDT version (2.4.0 or greater).
-
Open a CLI in the configuration package directory.
-
Run
fdt editor convert-for-770 package
, check the paths and confirm to continue. -
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.
S DK 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 add
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 Fade In
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>