Upcoming removals 7.16

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

External Data Manager

The ExternalDataManager is being deprecated in favor of addExternalValue API for managing external data. The ExternalDataManager can only be used in views and has an issue of unexpected behavior when updating external data while views are being rendered. The addExternalValue API is exempt from these issues and can be used anywhere where you can write XPath/XQuery.

Refactoring ExternalDataManager to addExternalValue API

The ExternalDataManager can be thought of as a map of external values. The new addExternalValue API behaves similarly. It can be used anywhere where you can use XPath and XQuery.

Setting Data

Setting external data was previously done via externalDataManager.setExternalData. This will be replaced by the setter function returned by the new addExternalValue API. This setter can then be exported and used wherever externalDataManager.setExternalData was used. Consider the example:

JavaScript

// Registering a custom-xpath-function (getter) and saving the setter
export const setDocumentsData = addExternalValue(
	'http://app',
	'get-document-data',
	'xs:string',
	'xs:integer',
	0
);

export default configureSxModule(sxModule) {
	documentsHierarchy.hierarchyChangedNotifier.addCallback(() => {
		// Find all loaded documents in the hierarchy
		const loaded = documentsHierarchy.findAll(hierarchyNode =>
	  	 	 hierarchyNode.documentReference ? hierarchyNode.documentReference.isLoaded() : false
		);

		// Before
		// externalDataManager.setExternalData('loaded-documents', loaded.length)

		// After
		// This set returns a promise which resolves when the value has been updated.
		// After the promise resolves, we can safely get the new value.
		// In this example we can just fire and forget.
		setDocumentsData('loaded-documents', loaded.length);
	});
}

The setter returned by addExternalValue is asynchronous and returns a promise which resolves when the value has been updated.

Retrieving Data

Retrieving external data used to be done via a NodeProxy in JavaScript context. This will now be in XPath context as the only way to get the data is using the registered XPath function. To retrieve data, you can simply evaluate the custom XPath function that was provided as part of the argument to the addExternalValue call. This can then be used wherever nodeProxy.getExternalValue was used. Consider the follow-up example:

JavaScript

function renderCustomWidget(sourceNode, renderer) {
	// Before
	// let externalValue = sourceNode.getExternalValue('loaded-documents');

	// After
	// get-document-data custom-xpath-function name was passed as the 2nd argument to addExternalValue
	const externalValue = evaluateXPathToNumber(
		'Q{http://app}get-document-data("loaded-documents")',
		null,
		readOnlyBlueprint
	);

	return ['span', externalValue];
}

If your widget is only responsible for displaying external data or some value derived from it, consider using createLabelQueryWidget instead of a custom widget.

It is important to note that since the getter is now evaluated in XPath context, the key/value used in the setter must be of the types (argumentType and returnType) specified in the addExternalValue arguments. For this reason, you must register a new setter/getter with the addExternalValue API for different types of external data.

Refer to the addExternalValue documentation to learn more about how to use the new API.

Inline link family

The configureAsInlineLink family implicitly assumed that the Fonto Editor instance it was configured for, was configured to resolve references using the reference CMS endpoint. In practice, a nullish value would often be provided for its referencePermanentIdAttributeName argument to turn off reference resolving, even though doing so was undocumented.

The referencePermanentIdAttributeName argument is now deprecated in favor of the more explicit CvkOptions referenceQuery and isPermanentId. This is in line with recent changes to the API of image-type families. Following are two current usage examples and their equivalents using these new options:

JavaScript

// Before (with reference resolving enabled):
configureAsInlineLink(sxModule, 'self::xref', 'link', 'href', { … });

// After (with reference resolving enabled):
configureAsInlineLink(sxModule, 'self::xref', 'link', { referenceQuery: '@href', isPermanentId: true, … });

// Before (without reference resolving):
configureAsInlineLink(sxModule, 'self::xref', 'link', undefined, { … });

// After (without reference resolving):
configureAsInlineLink(sxModule, 'self::xref', 'link', { referenceQuery: '@href', … });

CvkOptions.visualization

The visualization property on CvkOptions has been optional since the 7.0 release. All of its properties can be placed directly on the CvkOptions object.

JavaScript

// Before
configureAsBlock(
	sxModule,
	'self::simpara',
	{
		visualization: {
			blockBefore: [createLabelQueryWidget('"Para"')]
		}
	}
);

// After
configureAsBlock(
	sxModule,
	'self::simpara',
	{
		blockBefore: [createLabelQueryWidget('"Para"')]
	}
);

Fix occurrences of the deprecated visualization property like this.

Table widget menu operation lists

Some properties in TableDefinitionProperties are deprecated and they will be removed in 7.16.

  • horizontalAlignmentOperationNames

  • verticalAlignmentOperationNames

  • columnBorderOperationNames

  • rowBorderOperationNames

  • tableBorderOperationNames

Instead of them, two new properties are introduced and the previous operation names in the old API are moved to the new API:

  • columnWidgetMenuOperations

  • rowWidgetMenuOperations

If you have your own fork of fontoxml-table-flow-basic, fontoxml-table-flow-cals, fontoxml-table-flow-tei or fontoxml-table-flow-xhtml, then please rebase it to use new properties.

The deprecation, the new properties and the new configuration options in configureAs*TableElements functions allow you to be able to configure your own table widget menu operations.

Table highlighting button

The Fonto 7.13 release introduced a way to select multiple cells at once. It did this by introducing a button which allowed an author to chose a first cell, a second cell, and so on.

Fonto 7.14 removes the use of that button. Editors that used the old CellsHighlightButton should now use the new CellHighlightModeSwitch. This new switch will also introduce the new behavior to select multiple cells.

The cell highlight mode is still only usable for certain specific operations. For more information on working with the cell highlight mode, see the documentation on the setCellNodeIdsToHighlightedCells and the setBordersByCellNodeIdToHighlightedCells transforms. More operations will support the cell highlight mode in the future.

Removing any custom document save modal

The 7.13 release removed the possibility to remove a custom document save modal. Any code related to a custom save error modal is therefore dead. The 7.16 release will force the dead code of a custom save modal to be removed.

To remove the code related to this modal, find out whether the configuration property document-save-warning-modal-component-name is being set. If so, remove it and remove all code that uses it.

BlockBanner widget area

The blockBanner widget area that only applied to the sheetFrame family is deprecated and will be removed in the 7.16 release. Remove its usage. Any information that was displayed in this widget area can be placed in the SheetFrameHeader.