Upgrade from 6.4 to 6.5

The 6.5.0 platform release contains new features that require some care when upgrading your instance. The sections below describe the steps to follow to integrate these new features.

Clipboard configuration

The 6.5.0 release changes the clipboard configuration to be more simple for the majority of cases. The configuration only needs the name of the paragraph in the schema instead of a full paste-import-stream (which was usually the default).

Only the configuration for pasting plain text has been changed, this can be used for automated recognition of structures like lists and titles. The most used implementation only outputs paragraphs.

The application will not load without these needed changed.

See Pasting plain text for more information.

  1. Open config/configuration.js.

  2. Determine if the simple configuration is used

    • Most DITA instances use the default defined in fontoxml-platform-dita. If the paste-import-stream configuration option does not occur anywhere in the instance, there is no need for further action.

    • If the instance does configure the paste import stream, it will most likely look something like this:

      JavaScript

      define([
      	...
      	'fontoxml-configuration/configurationManager',
      	'fontoxml-clipboard/createParagraphImportStream',
      ...], function (
      	...
      	configurationManager,
      	createParagraphImportStream,
      	...
      	) {
      	...
      	configurationManager.set('paste-import-stream', createParagraphPasteImportStream('p'));
      	...
      });

      If the configuration looks like this, continue to step 3.

    • If the configuration uses an other pasteImportStream, the instance has a more customized approach to pasting plain text, continue to step 4.

  3. This is only needed for a simple configuration

    Simple configuration

    1. Remove the include of fontoxml-clipboard

    2. Remove the configuration variable paste-import-stream

    3. Add the configuration variable paragraph-node-name-for-pasting, set it to the nodeName of the paragraph (or equivalent). This is usually p. But could be different depending on the schema.

    4. Test the configuration by pasting some text, from a source that only supplies plain text (a terminal or notepad for instance).

      The configuration should end up looking like this:

      JavaScript

      define([
      	...
      	'fontoxml-configuration/configurationManager',
      	...
      ], function (
      	...
      	configurationManager,
      	...
      	) {
      	...
      	configurationManager.set('paragraph-node-name-for-pasting', 'p');
      	...
      });
  4. This is only needed for fine-tuned configuration

    More fine-tuned configuration

    The old way of providing configuration can not be used anymore but a slightly different approach needs to be used.

    1. Create a package containing thepasteImportStream.js and associated files.

      This is an add-on, and should be integrated as such. Meaning it should be added to the array of add-ons in the config/SchemaExperienceResolver.js file. Also, a dependency should be added to the manifest (config/fonto-manifest.json)

    2. Create an install.js file and import fontoxml-clipboard/pasteImportStreamManager.

    3. CallpasteImportStreamManager.setPasteImportStreamwith the custom pasteImportStream.

      JavaScript

      define([
      	'fontoxml-clipboard/pasteImportStreamManager',
      
      
      	'./api/pasteImportStream'
      ], function (
      	pasteImportStreamManager,
      
      	pasteImportStream
      	) {
      	'use strict';
      
      
      	return function () {
      		pasteImportStreamManager.setPasteImportStream( pasteImportStream);
      	};
      });
    4. Remove the old configuration variable for paste-import-stream.

    5. Test the new configuration by pasting some text, from a source that only supplies plain text (a terminal or notepad for instance). Use a JavaScript breakpoint to verify the pasteImportStream is used.

The application can load again. Also, pasting plain text is possible again.

MathML

MathML has been made generic, instead of DITA only. Follow these steps to upgrade your configuration.

  1. Rename all references of fontoxml-dita-architecture-mathml to fontoxml-mathml . They will occur in configureSxModule.js files and fonto-manifest.json files. The internal directory structure of the dita version and the generic version is identical.

  2. For all operations referencing {{mathMlPart}}, add the DITA mathml wrapper element for the {{mathMlPart}}. This is needed because not every schema enforces this wrapping element for mathml.

    JavaScript

    [
    	"equation",
    	"{{mathMlPart}}"
    ]
    // should become
    [
    	"equation",
    	[
    		"mathml",
    		"{{mathMlPart}}"
    	]
    ]
  3. Test the changes by inserting a block of MathML, and editing it.

Upgrade Node / NPM

The Fonto developer tooling had to adapt for a path resolving bug in NPM. This bug has been fixed in NPM version 3.9.0 and up. The developer tools has been fixed to support NPM 3.9.0 and up. This causes a certain path to be resolved wrongly in NPM versions up to 3.9.0.

NPM 3.9.0 is available for Node 5, and will automatically be installed when upgrading to Node 6.

  1. Upgrade Node to version 6 or higher, or run npm install npm --global.

    Or use Node Version Manager to easily switch between NodeJS installations (available for Linux and Mac OSX).

Obsolete experiments

In 6.5.0, a couple of experiments changed from being off by default to being on by default. Also, one experiment has been fully integrated.

Experimental features are features integrated in a way that allows it to be deactivated without needing a new platform release.

  1. Remove obsolete flags for experiments which have been integrated

    1. Remove any configuration setting the enable-experiment/buffered-input option.

  2. Remove obsolete flags for experiments that have been turned on by default.

    1. Remove the enable-experiment/altgr-supportconfiguration setting if it was set to true.

      Enabling it will allow Microsoft Window's alt-keys to insert special characters.

    2. Remove the enable-experiment/render-all-whitespace configuration setting if it was set to true.

      Enabling it will allow non-breaking spaces and normal spaces being rendered as they should, not influencing wrapping when they should not.

  3. Turn on new experiments that have been defaulted to being off, if possible.

    1. Add a configuration setting turing the enable-experiment/remove-default-text-container-after-exit experiment to true.

      This experiment influences removing nodes after inserting a structure, for instance pasting a list into an empty paragraph.

      This experiment will be turned on by default on the next release.

After enabling the experiments, do provide feedback on whether the experiments should be integrated.