fontoxml-structure-view

Structure view

The structure view, located in the sidebar, provides a high-level overview of the structure of your documents. It can be configured using the Structure Visualization Kit (SVK), similar to how the content view is configured using the CVK.

The sidebar tab is configured with the id 'structure', and a priority of 100. It usually is the first sidebar tab.

The SVK currently defines one structure view family: configureAsStructureViewItem. This family can be used to define which parts should be visible, which parts should be hidden and how a structure view item should be visualized.

This family should be assigned to the structural element itself, not its title. The options for this family can be used to determine which of the descendants of these structural elements, if any, is the title. This title will then be used to determine the contents of the entry in the structure view.

Example configuration: single document

Given a simplification of the HTML schema (nested <div> and <section> elements with <title> elements functioning as titles. <section>s should be hidden). Only the title at the root should be rendered as a separate structure view item.

The structure view can be configured as such:

Configure the document root in the structure view

configureAsStructureViewItem(sxModule, 'self::* and parent::document-node()', {
	// Let's make the document title static for now. This XPath is a string literal.
    titleQuery: '"The root of the document"',
    icon: 'folder-o',
    recursionQuery: './div | ./section | ./title'
});

Configure the <div> elements

configureAsStructureViewItem(sxModule, 'self::div', {
	// Use the contents of the title element as a title. If there is none, build a placeholder string.
    titleQuery: 'if (title) then title else ("Untitled " || fonto:markup-label(.))',
    icon: 'item-o',
	// The div elements may be nested. They may also contain sections
	// But do not recurse into the title element.
    recursionQuery: './div | ./section'
});

Configure <section> elements

configureAsStructureViewItem(sxModule, 'self::section', {
	// Sections should be hidden from view.
    isHiddenFromView: true,
	// But they may contain divs. They should be recursed into.
	// But do not recurse into the title element.
    recursionQuery: './div | ./section'
});

Configure the <title> element

configureAsStructureViewItem(sxModule, 'self::title, {
    titleQuery: 'string(.)',
	// A title does not have to recurse.
    recursionQuery: '()'
});

Configure contextual operations

ContextualOperations may be configured using the configureProperties function.

configureProperties(sxModule, 'self::div', {
    contextualOperations: [
        { name: 'div-move-up' },
		// This operation is only shown in the structure view.
        { name: 'remove-div', hideIn: ['context-menu', 'element-menu', 'breadcrumbs-menu']}
    ]
});

Example configuration of a multi-document editor (like DITA)

The document hierarchy is used in conjunction with the recursionQuery option in [@link configureAsStructureViewItem}. Child items from the hierarchy are shown separate from the children originating from the recursionQuery.

Currently, only DITA editors support resolving these hierarchies from DITA maps.

The basic configuration does not differ from the single document approach.

configureAsStructureViewItem(sxModule, 'self::topic', {
    icon: 'file-text-o'
});

Make sure to define operations for the structure view on the element that they modify. The structure view shows both the operations for the topicref as well as those for the element targeted by it. For example, the DITA map mutation operations should be configured as follows:

// A map by itself can not be moved or removed, only allow insertion of topicrefs using an application-defined operation
configureContextualOperations(sxModule, 'fonto:dita-class(., "map/map")', [
        { name: 'my-topicref-insert-operation' }
]);

// Topicrefs allow insertion as well as movement and removal
configureContextualOperations(sxModule, 'fonto:dita-class(., "map/topicref")', [
        { name: 'my-topicref-insert-operation' },
        { name: 'contextual-topicref-move-up' },
        { name: 'contextual-topicref-move-down' },
        { name: 'contextual-topicref-indent' },
        { name: 'contextual-topicref-outdent' },
        { name: 'contextual-topicref-move-to-top' },
        { name: 'contextual-topicref-move-to-bottom' },
        { name: 'contextual-topicref-remove' }
]);

// It is not possible to insert under a mapref, nested topicrefs should be inserted under the target map instead
// Therefore, only allow movement and removal operations for mapref
configureContextualOperations(sxModule, 'fonto:dita-class(., "map/mapref")', [
        { name: 'contextual-topicref-move-up' },
        { name: 'contextual-topicref-move-down' },
        { name: 'contextual-topicref-indent' },
        { name: 'contextual-topicref-outdent' },
        { name: 'contextual-topicref-move-to-top' },
        { name: 'contextual-topicref-move-to-bottom' },
        { name: 'contextual-topicref-remove' }
]);

Drag and drop

This add-on contains experimental support for using drag and drop to move items. To use this functionality, ensure enable-experiment/drag-and-drop-in-structure-view-sidebar is set to true. By default, the platform provides support for simple single-document operations as well as DITA maps (if the fontoxml-dita add-on is used). See addDragAndDropOperation and {@link http://documentation.fontoxml.com/editor/latest/configure-drag-drop-in-the-structure-view-16323060.html our guide} for information on configuring custom drag & drop operations.


APIs in fontoxml-structure-view