Upcoming removals 7.18

This page contains more information on APIs that have been deprecated, and will be removed in 7.18.

Remote document state permanent save error properties

With the changes made to Remote document states in 7.13.0, we also made some changes to the object returned from useRemoteDocumentState to reflect the new states. Unfortunately, this inadvertently broke the hasPermanentSaveError and permanentSaveErrorMessage properties. As the use of these properties is no longer recommended, we are now formally deprecating their use.

  1. Remove all usages of hasPermanentSaveError. Consider checking whether outOfSyncReason is either ACCESS_FORBIDDEN or NOT_FOUND as a replacement, but make sure to look at the remote document state flowchart and consider redesigning the logic / UX to match.

  2. Remove all usages of permanentSaveErrorMessage. This error information is no longer accessible other than by registering a non-fatal error callback with the errorManager. Consider following the remote document state flowchart instead to provide an appropriate user experience for cases where the document has become inaccessible.

Find and Replace configuration

We're deprecating the current enableReplaceAll attribute from FindAndReplaceConfiguration in favor of a new one named enableReplace, which provides more control when configuring Find and Replace replacing options. enableReplace accepts three string values that determine which replace options will be available. The supported values are:

  1. all: Default value. Enables replace and replace all.

  2. single: Enables replace, disables replace all.

  3. none: Disables replace and replace all.

If you have configured find-and-replace-configuration configuration using the enableReplaceAll attribute, you can replace it by the enableReplace attribute as follows:

JavaScript

// Deprecated configuration.
configurationManager.set('find-and-replace-configuration', {
	enableReplaceAll: true,
	...
});

// New configuration.
configurationManager.set('find-and-replace-configuration', {
	enableReplace: 'all',
	...
});

Upgrading configuration when enableReplaceAll is set to true.

JavaScript

// Deprecated configuration.
configurationManager.set('find-and-replace-configuration', {
	enableReplaceAll: false,
	...
});

// New configuration.
configurationManager.set('find-and-replace-configuration', {
	enableReplace: 'single',
	...
});

Upgrading configuration when enableReplaceAll is set to false.

To disable replace and replace all options in the editor, configure enableReplace as follows:

JavaScript

configurationManager.setDefault('find-and-replace-configuration', {
	enableReplace: 'none',
	...
});

By default, enableReplace is set to 'all', enabling both replace and replace all options.

Removing the GET /asset endpoint

Because the GET /asset endpoint is not used anymore, we'll be removing it in the release of 7.18.

Replace XPath-based transforms with inline XPath

We're deprecating a few of the lesser-used transforms. Most of these had already been marked as deprecated in our documentation, as inline XPath often provides a more convenient and flexible way to achieve the same goals.

Please look for any occurrences of the following transforms in your configuration and replace them with an equivalent inline XPath expression. The replacement inline XPath expressions can be specified on the data for the first operation step that needs the result, which is usually the one directly following the transform step:

JSON

// Instead of using a separate transform step:
"some-operation": {
	"steps": [
		{
			"type": "transform/setContextNodeIdToParentNodeOfContextNode"
		},
		{
			"type": "operation/append-structure",
			"data": {
				"childNodeStructure": [ "some-element" ]
			}
		}
	]
}

// Use the equivalent inline XPath expression on the next step:
"some-operation": {
	"steps": [
		{
			"type": "operation/append-structure",
			"data": {
				"contextNodeId": "x__$data?contextNode/parent::node()",
				"childNodeStructure": [ "some-element" ]
			}
		}
	]
}

Please refer to the following table, or to the documentation page for each of the deprecated transforms, for replacements.

Transform

Example - old input

Example - replacement

setContextNodeIdToParentNodeOfContextNode

(only takes the contextNodeId)

"contextNodeId": "x__$data?contextNode/parent::node()"

getModelUsingStencil

"contextStencil": [ null, { "someAttribute": {"bindTo": "some-value"} }, {"multiple": true} ]

"some-value": "x__$data('contextNode')/@someAttribute"

setContextNodeIdToSelectionCommonAncestorContainer

(no input)

"contextNodeId": "x__fonto:selection-common-ancestor()"

setContextNodeIdToSelectionCommonAncestorElement

(no input)

"contextNodeId": "x__fonto:selection-common-ancestor()/(self::*, parent::*)[1]"

setContextNodeIdToAncestorMatchingStencil

"selectionAncestorStencil": [ "p", { "class": "matchingAncestor" } ]

"contextNodeId": "x__fonto:selection-common-ancestor()/ancestor-or-self::p[@class='matchingAncestor'][1]"

setContextNodeIdToChildOfContextNodeIdMatchingDitaClass

"childDitaTypes": ["task/taskbody"]

"contextNodeId": "x__$data?contextNode/*[fonto:dita-class(., 'task/taskbody')][1]"

setContextNodeIdToSelectionAncestorMatchingDitaClass

"parentDitaTypes": ["topic/p"]

"contextNodeId": "x__fonto:selection-common-ancestor()/ancestor-or-self::*[fonto:dita-class(., 'topic/p')][1]"

setContextNodeIdToFirstMatchingNodeFromContextNode

"xPathQuery": "./title"

"contextNodeId": "x__$data?contextNode/title[1]"

Note that the [1] suffix is only required if the possibility exists that the path returns more than a single node.

It is possible to combine expressions in cases where multiple transforms update the contextNodeId in order. For example, a step for the transform setContextNodeIdToSelectionCommonAncestorContainer followed by one for setContextNodeIdToFirstMatchingNodeFromContextNode with "xPathQuery": "descendant-or-self::title" can be re-written as the single expression "contextNodeId": "x__fonto:selection-common-ancestor()/descendant-or-self::title.

Remove all-remote-document-ids-are-absolute configuration

For backwards-compatibility reasons, Fonto Editor releases prior to 7.16.0 would send separate /document GET requests for each unique combination of a given (remote) document ID and referrer ID. However, it is not allowed for the CMS to respond with different documents for the same document ID, based on a different referrer value. The all-remote-document-ids-are-absolute configuration value was used to opt-in to omitting these unnecessary requests, which has now been made the default behavior. Any code to set this configuration value can therefore be removed.

If you find that your application depends on this configuration value being set to false, please contact us and describe your use case. Returning a different document based on the referrer ID is not supported and may cause errors and/or other unexpected behavior in the editor.

The new table selection API

After introducing the new table selection feature in 7.16, we needed to make some name changes in the API as well. So we renamed some APIs:

Deprecated operations row-delete & column-delete

Previously, operations for removing columns and rows allowed us to remove a single column or a single row at once. We have improved those operations so we are able now to remove not one but multiple columns or rows at the same time. Therefore, we have renamed the operations: column-delete and row-delete .

Please look for any occurrences of those operations and replace them with columns-delete and rows-delete.

Starting from 7.18.0 on, you can use only the new APIs.