Upgrade from 6.9 to 6.10

The new platform release removed some deprecated features. Usage of these features must be removed to be able to run the instance again. Also, some other features have been deprecated.

As with all releases, make sure to upgrade any localization message bundles after upgrading the FontoXML platform. Please refer to the localization documentation for more details.

Upgrading to the React router

The index.html page is styled slightly differently to better accomodate FDS React components. We also took this opportunity to streamline the masthead. The FontoXML logo has been moved to the left side of the masthead so the right side can be used for user widgets, which will be enabled in a future release. This means that including client logos in the masthead is no longer possible. These changes have allowed us to simplify the pageIndex mixin API.

  1. Open your config/index-page.jade file.
  2. Change the first line include fontoxml-ui-page-index/pageIndex to include fontoxml-editor/renderIndexPage.
  3. Change the call to the pageIndex mixin to a call to the new renderIndexPage mixin.
    1. Change +pageIndex to +renderIndexPage.
    2. Remove the "logo" property, this is no longer supported.
    3. renderPageIndex accepts two parameters instead of the single parameter of pageIndex. The first parameter is for the old "title" property. The second parameter is for the old "favicon" property. Replace this accordingly.

      +pageIndex({ "title": "Example", "favicon": "assets/example.ico" })

      becomes

      +renderIndexPage("Example", "assets/example.ico")

You should be able to run your application again.

If you integrated the index.html in your CMS or have made other changes to it, make sure to update the file with the index.html created when building the 6.10.0 version. Using an older index.html together with the code for this version of FontoXML will not work.

adaptNodeSpecToSelector

The adaptNodeSpecToSelector function has deprecated in a previous release. In this release, it has been removed.

  1. Find all usages of fontoxml-selectors/adaptNodeSpecToSelector.
  2. Remove the include, and remove the function call

    This function has been reduced to an identity function in the 6.9.0 release. It can safely be removed.

    function (selectorOrNodeSpec) {
    	var selector = adaptNodeSpecToSelector(selectorOrNodeSpec);
    
    
    	doSomething(selector)
    	...
    }
    // Becomes
    function (selector) {
    	doSomething(selector)
    	...
    }

NodeSpec API deprecation

A number of APIs accept an option called selectorOrNodespec, or a variant thereof such as containerSelectorOrNodeSpec or titleSelectorOrNodeSpec. The previous release deprecated the old NodeSpec syntax in favor of XPath, and this release fully removes NodeSpec support from these APIs. To reflect this, we are renaming or replacing a number of these APIs in the 6.10 release. Using the old APIs will trigger warnings explaining the replacement API to use.

  1. Refactor all occurences of titleSelectorOrNodeSpec in CVK-context.

    configureAsSheetFrame(sxModule, 'self::sheetframe', undefined, {
    	titleSelectorOrNodeSpec: 'self::titleNode'
    });
    1. Replace this titleSelectorOrNodeSpec with titleQuery, a new API which aligns better with the structure view API.

      configureAsSheetFrame(sxModule, 'self::sheetframe', undefined, {
      	titleQuery: './titleNode'
      });
    2. (Optional) Use the new API to allow better fallback labels.

      configureAsSheetFrame(sxModule, 'self::sheetframe', undefined, {
      	titleQuery: 'if (./titleNode != "") then ./titleNode else "Untitled sheetframe"'
      });
    3. Test the changes. This titleQuery is mainly used in the project browser and in references.
  2. Refactor all occurences of isIgnoredForNavigationSelectorOrNodeSpec in CVK context.

    configureAsSheetFrame(sxModule, 'self::sheetframe', undefined, {
    	isIgnoredForNavigationNextToSelectorOrNodeSpec: 'self::titleNode'
    });

    Replace it with isIgnoredForNavigationNextToSelector.

    configureAsSheetFrame(sxModule, 'self::sheetframe', undefined, {
    	isIgnoredForNavigationNextToSelector: 'self::titleNode'
    });

Upgrade to fontoxml-list-flow

This release brings a better API to standardize list behaviour without the need for extra customization. This replaces the APIs defined in fontoxml-dita-architecture-list-flow and replaces any contributions our partners made regarding list-flow. The APIs defined in dita-architecture-list-flow and the ones defined by our partners have been used as inspiration for this new feature.

This needs some upgrading to fully be used.

  1. Use the new configureAsList API
    1. Find where the family configuration of lists and related elements are located currently.

      // ol
      configureAsGroup(sxModule, 'self::ol', 'numbered list', {
      	contextualOperations: [
      		{ name: 'ul-convert' }
      	],
      	defaultTextContainer: 'li',
      	visualization: {
      		expression: 'compact'
      	}
      });
      // li in ol
      configureAsGroup(sxModule, 'self::li[parent::ol]', 'item', {
      	defaultTextContainer: 'p',
      	isIgnoredForNavigation: true,
      	visualization: {
      		blockBefore: [
      			createHierarchicalNumberingWidget( self::li[parent::ol]', { containerSelectorOrNodeSpec: 'self::ol', numberingStyles: ['decimal', 'lowerAlpha', 'lowerRoman'] })
      		]
      	}
      });
      // p in li
      configureAsLine(sxModule, 'self::p[parent::li]', 'paragraph');
    2. Replace it with the new configuration, which uses the correct families for the list, the list item and (optionally) the paragraph.

      // ol
      // li in ol
      // p in li in ol
      configureMarkupLabel(sxModule, 'self::ol', 'numbered list');
      configureMarkupLabel(sxModule, 'self::li', 'item');
      configureContextualOperations(sxModule, 'self::ol', ['ul-convert']);
      
      
      configureAsListElements(sxModule, {
      	list: {
      		selector: 'self::ol',
      		style: configureAsListElements.NUMBERED_LIST_STYLE
      	},
      	item: {
      		nodeName: 'li'
      	},
      	paragraph: {
      		nodeName: 'p'
      	}
      });
  2. Use the new operations for indenting lists

    See documentation for these operations at indent-list-item and outdent-list-item.

    1. If the instance uses platform-dita, the toolbar might contain two list indention operations calledindent an outdent. These have been renamed toindent-list-item and outdent-list-itemto be more descriptive. Change the references in the toolbar accordingly.

      ui-button(label="")
      	fonto-operation(name="indent")
      ui-button(label="")
      	fonto-operation(name="outdent")


      Becomes the following:

      ui-button(label="")
      	fonto-operation(name="indent-list-item")
      ui-button(label="")
      	fonto-operation(name="outdent-list-item")
    2. If the instance does not use platform-dita, but does include a list indent operation, replace its references with the new indent-list-item and outdent-list-item operations.
    3. Find all references to the indent and outdent operations and replace them with indent-list-item and outdent-list-item.
  3. Use the new list conversion operations

    There are two list creation / conversion operations available; list-convert to convert lists to and from paragraphs and convert lists between each other. The other operation can solely convert different kinds of lists, this is convert-element.

    1. Create or replace the current conversion operations with convert-element.

      This conversion operation is usually references as a contextual operation.

      "ul-convert": {
      	"label": "t__Change to bulleted list",
      	"description": "t__Change this numbered list to a bulleted list.",
      	"icon": "list-ol",
      	"steps": [
      		{
      			"type": "operation/convert-element",
      			"data": {
      				"nodeNames": ["ul"],
      				"contextNodeId": "{{contextNodeId}}"
      			}
      		}
      	]
      }
    2. Replace the list creation operation with the new operation.

      "ul-insert": {
      	"label": "t__Bulleted list",
      	"description": "t__Insert a bulleted list.",
      	"icon": "list-ul",
      	"steps": {
      		"type": "operation/convert-list",
      		"data": {
      			"listNodeName": "ul",
      			"listItemNodeName": "li",
      			"paragraphSelector": "self::p"
      		}
      	}
      }

Upgrading FDS usage

This release brings some API changes in components and system utilities provided by FDS (Fonto Design System). The API for the following components have been changed, causing them to potentially break when using props which are now removed, replaced or updated:

Component Changes
CalendarInput Removed showClearButton prop.
Checkbox Made onChange prop required.
CheckboxGroup Made onChange prop required.
CollapsibleInlay Removed collapsedLabel and label props. Added headerContent prop.
DateSelect Component is deprecated, use CalendarInput instead.
MultipleAutocomplete Made onChange prop required.
NumberInput Removed isBorderless, isWidthEqual and paddingSize props.
Popover Removed paddingSize prop and has no more padding by default. Requires newly introduced PopoverBody, and optionally PopoverFooter, to be used as children.
SingleAutocomplete Made onChange prop required.
Switch Now prevents click event from bubbling down.
TextArea Removed isBorderless and paddingSize props.
TextInput Removed isBorderless and paddingSize props.
VirtualList

Removed itemMarginInPx and renderScrollContainer props.

Added paddingSize, scrollContainerRendererName, scrollContainerRendererPositionSpec and spaceVerticalSize props.

The API of the following components has been extended:

Component Changes
all form components Now support isDisabled, validate and tooltipContent props.
PopoverAnchor Now passes togglePopover callback to the registered popover factory.
TextLink Now supports isHovered prop.

Additionally, the following system utilities have been updated:

Utility Changes
color() The color palette has been updated to follow a consistent naming convention. This affects every place where the color utility has been directly used or a colorName prop has been set to a component. The color utility will show a warning in your console when using a color name which is not present in the palette. Do mind that this warning is triggered at runtime, if you’re using a color which toggles based on a prop this warning will only show when the color is actually set.
flex() Added default ‘min-width’ and ‘min-height’ with a value of 0 to work around known Firefox issues using overflow scroll.

We've also added 4 new components; PopoverBody, PopoverFooter, UnorderedList and UnorderedListItem.

The full API reference for all components and system utilities has been updated as well.

Upgrading content view zoom operations

In moving from Angular to FDS, the zoom feature has been reworked for stability and now works better for different combinations of text size and document width. The names of the operations used for this feature have changed as a result.

  1. Determine whether you require separate control over document width and text size, or combined zooming.
  2. Replace the operations in the config/toolbar-template.jade file.

    For individual control over text size and document width, use the set-content-view-document-width-to-* and set-content-view-text-size-to-* operations. For combined zooming, use the zoom-content-view-to-*-* operations. The wide-canvas-content-view-to-150%-text-size-not-150% operation provides a way to add a “wide canvas” option when using the zoom operations.

The following snippet shows the recommended way to expose these operations in the FontoXML toolbar:

ui-drop(
	icon="search"
	label="Zoom")
	ui-menu
		ui-menu-item
			fonto-operation(name="zoom-content-view-to-75%-75%")


		ui-menu-item
			fonto-operation(name="zoom-content-view-to-100%-100%")


		ui-menu-item
			fonto-operation(name="zoom-content-view-to-125%-125%")


		ui-menu-item
			fonto-operation(name="zoom-content-view-to-150%-150%")


		ui-menu-item
			fonto-operation(name="zoom-content-view-to-200%-200%")

Customizing the load screen text

In previous versions, you would use the configuration setting called loadScreenText to set the message being displayed when loading documents before the editor is visible.

This configuration variable has been replaced with a translatable message. This message supports plural formatting just like every translatable message in FontoXML.