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.

  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 send the Outline pane configuration through the outlineConfigurationProvider loading option. This function that has a callback that receives the JSON configuration as a parameter. 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 the title (name) for any given element. For advanced use-cases, it is possible to configure the location of the element title presented in the Outline pane.

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="section1" location="title"/>  
  </tocMode> 
</outline>

Each element titleLocator specifies which elements are to be presented in the Outline pane in the Contents mode with the @element attribute.

For each element presented in Contents mode, you can control the rendered text in the outline tree with the @location attribute that is a simplified XPath syntax that supports a comma-separated list of the following:
  • Element names (e.g. "title,h1,h2")
  • Element path ("elementName1/elementName2/.../elementNameN")
  • Descendent element using ".//" (e.g. ".//title").
  • Attribute names prefixed with "@" (e.g. "@title").
  • Any before or after pseudo-elements.
    For example, before(1030) selects the text from the before pseudo-element on level 1030. This works on the DITA map in conjunction with a CSS rule that sets the title of the topic on the before pseudo-element using the oxy_link-text() custom CSS function. For reference, see the following resources:

The first element in the list returned by the XPath is used. If no <titleLocator> element is present, or if no match is found in the document, the default algorithm is used to retrieve the text for the given element.

How to Configure Which Side of the UI 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 or right.