4.2.1.  Outline Configuration

Orangevolt EclipseXSLT provides a configurable outline depending on your document type/structure.

The outline configuration defines labels and images for all document elements which should be outlined. Labels can be defined using XPath expression placeholders to allow label creation based on the real document content.

An The dynamic label creation facility allows you to label an <chapter> element with attribute title as Chapter ${@title}. Alternative label expressions are possible by separator |. All <chapter> elements will now be labeled with Chapter [content of title attribute].

Elements not defined in the configuration will be hidden in the outline.

Outline configurations are read when at first use. The default outline configuration provides 3 configurations : the xml document type which is the source of this documentation , XSLT stylesheet outline and Docbook outline.

Outline configurations are done by Eclipse extension points. The best way for defining an outline is to create a new Eclipse fragment (see the Docbook fragment source as an example. It is located in [eclipse]/plugins/com.orangevolt.eclipse.xslt.docbook/). The outline icons can also be located in your fragment.

Format specification

Below is the outline configuration for Docbook files:

outline configuration fragment for docbook (com.orangevolt.eclipse.xslt.docbook/fragment.xml)
1	<?xml version="1.0" encoding="UTF-8"?>
2	<?eclipse version="3.0"?>
3	<fragment>
4	<extension point="com.orangevolt.eclipse.xslt.outlineconfiguration">
5	<grammar
6	id="com.orangevolt.eclipse.xslt.editor.outline.configuration.docbook"
7	name="Orangevolt DocBook Outline Configuration"
8	rootelement="book|part|article">
9	<element name="book" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-docbook-book-16.png"/>
10	<element name="part" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-docbook-book-16.png"/>
11	<element name="article" label="${title}|${articleinfo/title}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-docbook-article-16.png"/>
12	<element name="preface" label="${title}|${@xreflabel}|${@id}|Preface" icon="icons/outline/docbook/cong-subsection-16.png"/>
13	<element name="chapter" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
14	<element name="appendix" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-summary-16.png"/>
15	<element name="glossary" label="${title}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-summary-16.png"/>
16	<element name="section" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
17	<element name="simplesect" label="${title}|${@xreflabel}|@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
18	<element name="sect1" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
19	<element name="sect2" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
20	<element name="sect3" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
21	<element name="sect4" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
22	<element name="sect5" label="${title}|${@label}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
23	<element name="index" label="${title}|${@xreflabel}|${@id}" icon="icons/outline/docbook/cong-subsection-16.png"/>
24	</grammar>
25	</extension>
26	</fragment>

As you can see in the configuration an outline is defined as an extension to EclipseXSLT extension point com.orangevolt.eclipse.xslt.outlineconfiguration.

You can define multiple outline configurations within the extension point. I suggest to create one single fragment (for you or your company) containing all custom outline configurations.

For big outline definitions which are common used (like the Docbook outline configuration) i suggest its own fragment named by the format spec.

An outline configuration starts with the grammar element. grammar accepts the following attributes:

• id

  A unique id for the grammar (its up to you how to name the id).

• name

  A human readable name for the grammar to identify its origin and use.

• rootelement

  A list of possible root element names separated by |.

  In general a xml format specifies exact one single root element. But some formats allow different kinds of root elements (Docbook for example). Therefore a list of possible root elements is possible.

  The rootelement attribute is used by the outline to decide which rules for the document outline to use.

Inside the grammar element are element tags defined. Each element is used to describe one single xml element from the customized xml outline. element takes the following attributes:

• name

  The name of the xml tag to label.

  Since version 1.0.5 element names may contain wildcards (* and ? to be concrete :-). This is a huge step forwarding because it eases the outline configuration for the lazy guys very much.

  The example below shows the simple xul outline configuration using a wildcard.
  (This configuration matches every xul element and displays either its element name, title or label).

  ...

  <extension point="com.orangevolt.eclipse.xslt.outlineconfiguration">

  <grammar

  id="com.orangevolt.eclipse.xslt.editor.outline.configuration.xul"

  name="Orangevolt XUL Outline Configuration"

  rootelement="window|overlay|dialog|page|wizard">

  <element name="*" label="${(local-name)} [${@id}]|${(local-name)} '${@title}'|${(local-name)} '${@label}'|${(namespace)}:${(local-name)}|${(local-name)}" icon="icons/outline/xul/element.gif"/>

  </grammar>

  </extension>

  ...

• label

  The label template list for the xml tag. The label list may contain multiple label templates for different representations separated by |.

  A single template consists of static text and XPath placeholders. Everything between ${ and } will be interpreted as XPath expression and be replaced by its result.

  The first matching representation will be used for labeling. A representation matches when all attributes of the representation are found in the xml tag.

  An example:

  The label definition of element book (see line 9 in the fragment source above) is ${title}|${articleinfo/title}|${@label}|${@xreflabel}|${@id}.
  The label rendering for book works as following:

  1. If book has a child element title then its text content is rendered as label.

  2. Else if book has a child articleinfo having a child title then the text content of sub element title is rendered as label

  3. Else if book has attribute label then the label attribute value is rendered as label

  4. Else if book has attribute xreflabel then the xreflabel attribute value is rendered as label

  5. Else if book has attribute id then the id attribute value is rendered as label

  6. Otherwise (if none of the representations matches) the default label <book> :: no attribute matched label ${title}|${@label}|${@xreflabel}|${@id} will be displayed.

  You can also use complex templates containing multiple XPath placeholders and static text.

  An XPath placeholder is what its name implies - an real xpath expression. therefore you can use real xpath syntax inside ${ and }.

  The current element is used as XPath expression context.

• tooltip

  (optional). The tooltip is an optional attribute defining the tooltip text for the element. the tooltip attribute

• icon

  (optional). The icon is an optional attribute defining the plugin/fragment relative path to fetch the xml tag icon. If no icon was defined the default element icon of the Eclipse WTP outline is used.