How to add and configure a document outline

This guide helps you to add and configure the Structure View add-on for your editor. This add-on adds an outline sidebar to Fonto Editor. The outline sidebar shows elements which are configured to be shown there and allows authors to easily navigate to those elements.

What you need

Prerequisite guides:

1

Add the add-on

Refer to the add-ons page to learn more about adding Structure View add-on to your editor. Make sure to select fontoxml-structure-view in FDT. Refer to FDT's NPM page for more information on how to use FDT.

2

Pick an element

Fonto Editor does not know which element(s) should be shown in the outline sidebar. This information can't be derived from the CVK (Content Visualization Kit) configuration. Elements that should be shown in the outline sidebar need an additional SVK (Structure Visualization Kit) configuration. This configuration does not replace or influence the CVK configuration of an element.

There is no limitation on which elements can be shown in the outline sidebar. However, showing too many elements won't help your authors. You need to determine which elements authors want to quickly navigate to using the outline sidebar.

Elements representing documents are commonly shown in the sidebar. These elements are usually the <map> and <topic> in a DITA schema or the <section>-like elements in a single-document hierarchy. These elements are usually configured as a sheet frame. Refer back to the guide configuring elements to read which elements should be configured as a sheet frame.

In addition to showing elements which define the structure of a document, you might consider showing elements which in some publications are listed in a separate index. Examples of these are elements representing figures, tables, and equations.

3

Create a package

Create a new package for your editor's outline sidebar configuration. You can do this by creating a directory called editor-outline in your packages/ directory.

Create a configureSxModule.js file in packages/editor-outline/src directory.

This package needs to be a dependency of another package. If you only have a single package with CVK configuration, this new package can be added as a dependency of that one. To do so, find the fonto-manifest.json in the root of the package with the CVK configuration and add the following line to the dependencies:

JSON

{
	"dependencies": {
		"editor-outline": "packages/editor-outline"
	}
}

If there is no such font-manifest.json file yet, create it and fill it with the same contents.

4

Configure a structure view item

Use the configureAsStructureViewItem function to configure elements which need to show up in the outline sidebar. configureAsStructureViewItem will not affect the behavior or visualization in the content view.

configureAsStructureViewItem requires the same arguments as any other CVK configuration function. It expects an SxModule as its first argument, then a selector for the element to be configured and then an options object.

One important option to pass to configureAsStructureViewItem is the titleQuery. The title query is an XPath query which is used to determine what to show in places that use the title query, for example the outline sidebar.

Configuration with title query

JavaScript

configureAsStructureViewItem(sxModule, 'self::topic', {
	titleQuery: 'import module namespace fonto = "http://www.fontoxml.com/functions"; fonto:curated-text-in-node(./title)'
});

This example shows the outline sidebar configuration for a topic element with a title query.

The result of the title query should be a string or something that can be cast to a string. The XPath, in this case, returns the curated text representation of the topic element's title element. The curated text representation of the title element is returned by the curated-text-in-node XPath function.

The curated-text-in-node XPath function is used in this example because it has some tricks up its sleeve. For example, it resolves included content and returns the string representation of that content. It can also handle all kinds of XML structures, such as child elements.

5

Adding icons

Each item in the outline sidebar can have its own icon. Adding an icon to outline items is considered a best practice as it informs the user of your editor what type of document or element they are looking at.

An icon can be added in the options object passed to the configureAsStructureViewItem. Refer to the concept page on Font Awsome for more information on using icons in Fonto Editor.

Configuration with title query and icon

JavaScript

configureAsStructureViewItem(sxModule, 'self::topic', {
	titleQuery: 'import module namespace fonto = "http://www.fontoxml.com/functions"; fonto:curated-text-in-node(./title)',
	icon: 'file-text-o'
});

This example shows the outline sidebar configuration for a topic element with a title query and its icon set to Font Awsome's file-text-o icon.

6

Hide the top level document

This step is optional, but considered a best practice for editors which always open a map-like document.

Configuration for title query and hidden element

JavaScript

configureAsStructureViewItem(sxModule, 'self::map', {
	titleQuery: 'import module namespace fonto = "http://www.fontoxml.com/functions"; fonto:curated-text-in-node(./title)',
	isHiddenFromView: true
});

This example shows the outline sidebar configuration for a map element which will be hidden from the outline sidebar.