Edit online

Enabling the Outline Pane for DITA and Other Frameworks

Oxygen XML Web Author includes an Outline side-pane that displays a general tag overview of the current document. It is enabled and available, by default, for DITA Map, DocBook, TEI, and XHTML documents. However, it is possible to configure other frameworks (such as DITA topics) to display the pane.

To enable the Outline pane for a custom framework, follow these steps:
  1. Create a configuration file named webAuthorOutlineConfig.xml. The following is an example of what this configuration file looks like for DocBook:
    <outline> 
  <structureMode editable="yes" default="no">
    <preferredAttributes names="id xml:id"/> 
  </structureMode> 
  <tocMode editable="yes" default="yes">
    <elements names="section sect1 sect2 sect3 sect4 sect5 simplesect article book"/> 
  </tocMode> 
</outline>

    Notice that there are two elements that define the two modes: <structureMode> (for the Structure mode that displays the information in the pane as a general tag overview of the current XML document) and <tocMode> (for the Contents mode that displays the information in the pane like a table of contents).

    By using editable="yes", the document structure can be edited from the Outline view using drag-and-drop or contextual menu actions.

    The <structureMode> element includes an optional <preferredAttributes> child element. This element allows you to specify a list of space separated attribute names (using the @names attribute) that are prioritized for display in the Outline pane. For example, in the DocBook sample configuration the value of the id attribute (or xml:id, if id is not present) is rendered in the Outline pane, making it easier to identify and manage elements based on these attributes.

  2. The configuration file must be stored in a folder included in the framework's classpath. To add the folder to the classpath:
    1. In Oxygen XML Editor/Author, go to Options > Preferences > Document Type Association and edit the document type configuration for your custom framework.
    2. In the Classpath tab, add a link to the folder where you stored the configuration file.
      Note:
      It is important to reference the exact folder that contains the configuration file (it cannot be located in a subfolder within the referenced folder).
  3. Create an archive that only contains your custom framework folder and upload the changes to your framework to Web Author.
Tip:
It is also possible to set the Outline pane configuration as part of a Javascript plugin, using the outlineConfigurationProvider loading option. It can be set like this:
goog.events.listen(workspace,sync.api.Workspace.EventType.BEFORE_EDITOR_LOADED,function(e)
 {
    e.options.outlineConfigurationProvider = function(callback) {
        callback("{\n" + 
    "    \"structureMode\": {\n" + 
    "        \"editable\": \"yes\",\n" + 
    "        \"defaultMode\": \"no\",\n" + 
    "        \"preferredAttributes\": {\"names\": \"id xml:id\"}\n" + 
    "    },\n" + 
    "    \"tocMode\": {\n" + 
    "        \"editable\": \"yes\",\n" + 
    "        \"defaultMode\": \"yes\",\n" + 
    "        \"elements\": {\"names\": \"topic\"}\n" + 
    "    }\n" + 
    "}");
    }
 });

How to Configure the Displayed Names of Elements in the Outline Pane

The Contents mode (table of contents mode) uses a heuristic algorithm to present a title for any element that appears in the Outline. For advanced use-cases, it is possible to specify how the title for an element can be found.

Here is a DocBook example of what the <tocMode> element would look like for this type of configuration:
<outline> 
  <tocMode editable="no">
    <elements names="section sect1 sect2 sect3 sect4 sect5 simplesect article book"/> 
    <titleLocator element="section" location="title, @spectitle"/>  
    <titleLocator element="sect1" location="title"/>  
  </tocMode> 
</outline>

The <elements> element specifies which elements are to be presented in the Outline pane in the Contents mode, using a space-separated list of element local names in the @names attribute.

Each element titleLocator specifies how to determine the title for an element that is presented in the Outline pane in the Contents mode.

For each element presented in Contents mode, you can control the rendered text in the outline tree with the @location attribute of the <titleLocator> element. That is a comma-separated list of the following simplified XPath-like expressions:
  • Element name (e.g. title or h1)
  • Element path (e.g.elementName1/elementName2/.../elementNameN)
  • Descendent element prefixed with ".//" (e.g. .//title)
  • Attribute name prefixed with "@" (e.g. @title)
  • Any before, before(n), after, or after(n) pseudo-element
    For example, "before(1030)" selects the static content from the before pseudo-element on level 1030. This works in conjunction with a CSS rule that sets static content on the before(1030) pseudo-element. For reference, see the following resources:

The first XPath-like expression that returns content will be used, and the title will be its first value, in case multiple values are returned. If no <titleLocator> element is present, or if no values are obtained by evaluating the XPath-like expressions, the default algorithm is used to retrieve the title for that element.

How to Configure Which Side of the Editor the Outline Pane Appears

You can configure which side the Outline pane is displayed on by setting either of the following:

In both cases, the accepted values are: left (default) and right.