Upgrade from 6.9 to 6.10

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.

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.

   JavaScript

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

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.

   JavaScript

   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.

      JavaScript

      configureAsSheetFrame(sxModule, 'self::sheetframe', undefined, {
      	titleQuery: './titleNode'
      });

   2. (Optional) Use the new API to allow better fallback labels.

      JavaScript

      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.

   JavaScript

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

   Replace it with isIgnoredForNavigationNextToSelector.

   JavaScript

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

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.

      JavaScript

      // 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.

      JavaScript

      // 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.

      XML

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

      Becomes the following:

      XML

      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.

      JavaScript

      "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.

      JavaScript

      "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"
      		}
      	}
      }

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:

The API of the following components has been extended:

Additionally, the following system utilities have been updated:

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.

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%")

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.