15. linkType
Prev | Chapter 7. Configuration elements | Next

## 15. linkType

    <linkType
      name = NMTOKEN : "default"
    >
      Content: [ class ]? |
               [ link | anchor ]*
    </linkType>

    <class>
      Content: Java class name
    </class>

    <link
        match = XPath pattern
        ref = XPath expression
        refs = XPath expression
        href = XPath expression
        excludePath = Regular expression
        includePath = Regular expression
    />

    <anchor
        match = XPath pattern
        name = XPath expression
    />

A `linkType` configuration element allows to define a generalization of the `ID`/`IDREF`/`IDREFS` mechanism for use in modular documents. Some modular documents examples are:

- A DocBook `book` including (by the means of XInclude) `chapter` documents, each `chapter` element being found in its own file.

- A DITA map referencing a number of topic files.

- A set of XHTML pages (e.g. `.html` and `.shtml` files) found in the same directory.

Defining a linkType allows to follow a link even when this link points inside another file. See Section 15.1, “Using `linkType` to implement link navigation”.

Defining a linkType allows to check links even when some of the links point outside the file containing these links. See Section 15.2, “Using `linkType` to implement link validation”.

A `linkType` configuration element has a single optional attribute: `name`. The default value of attribute name is `default`. Giving a meaningful name to a linkType is useful in 3 cases:

1. When your configuration file contains several `linkType` elements. This is rarely needed, but it may happen. See example below.

2. The name of the `linkType` is `xml:id`. This special name means that the anchors defined by this link type are true XML IDs and thus, there is no need to create proprietary XPointers to implement link navigation. These proprietary XPointers are described in Section 15.1, “Using `linkType` to implement link navigation”.

3. When you want to allow removing this `linkType` from the configuration. This is possible because a `linkType` configuration element without any child element may be used to remove from a configuration a previously defined `linkType` having the same `name`.

A `linkType` configuration element contains either a single `class` child element or an number of `anchor` and `link` child elements:

`class`

  This element contains the fully qualified name of a class which implements interface `com.xmlmind.xmleditapp.linktype.LinkType`.

  An example of such class is `com.xmlmind.xmleditapp.IDLinkType`, which leverages the standard `ID`/`IDREF`/`IDREFS` mechanism to implement a link type. When no `linkType` element is found in a configuration file, XXE will behave as if the following one was defined:

      <linkType>
        <class>com.xmlmind.xmleditapp.linktype.IDLinkType</class>
      </linkType>

`anchor`

  The `anchor` element is used to detect in a document all the elements which may be used as link targets. This kind of elements is called link target, or more simply anchor. XHTML 1.0 example:

      <anchor match="*[@id]" name="@id" />
      <anchor match="html:a[@name]" name="@name" />

  For a given link type and in a given document, an anchor is uniquely identified by its name. That is, for a given link type and in a given document, it is an error to find several anchors having the same name.

`link`

  The `link` element is used to detect in a document all elements acting as links pointing to targets. This kind of elements is called link source, or more simply link. XHTML example:

      <link match="html:a[@href]" href="@href" />

  A link must reference the name of an existing anchor and optionally, depending on the link type, the file containing this existing anchor. That is, it is an error to find a link pointing to an unknown anchor and/or pointing to a non-existent file.

For a given link type, the same element may be at the same time an anchor and also one or more links.

It is also possible to define several link types in the same configuration. Fictitious example:

    <linkType>
      <link match="*[@ref]" ref="@ref" />
      <anchor match="*[@id]" name="@id" />
    </linkType>

    <linkType name="bug">
      <link match="supportTicket[@bug]" href="@bug" />
      <anchor match="bugReport[@number]" name="@number" />
    </linkType>

| The first `linkType` corresponds to general purpose ID/IDREF cross-references.
| The second `linkType` corresponds to specialized cross-references.

Attributes of the `anchor` child element:

`match`

  Specifies an XPath pattern which is used to detect an element which may be used as a link target.

`name`

  The XPath expression is evaluated in the context of the element matched by attribute `match`. It returns a string which is the name of the detected anchor.

  The name of a anchor is any non-empty string which does not contain whitespace. Special value "`-`" may be used to ignore the element matched by attribute `match`.

Attributes of the `link` child element:

`match`

  Specifies an XPath pattern which is used to detect an element which acts as a link source.

`ref`, `refs`, `href`

  One of the `ref`, `refs`, `href` attributes must be specified. The XPath expression is evaluated in the context of the element matched by attribute `match`. It returns a string which specifies the target of the link. This string cannot be empty. Special value "`-`" may be used to ignore the element matched by attribute `match`.

  The string returned by the `ref` XPath expression is expected to be an anchor name.

  The string returned by the `ref`s XPath expression is expected to be one or more anchor names separated by whitespace.

  The string returned by the `href` XPath expression is expected to conform to the following syntax:

      [ absolute_or_relative_URI ]? [ '#' anchor_name ]?

  A relative URI is relative to the base URI of the element matched by attribute `match`.

`excludePath`, `includePath`

  These attributes are ignored unless the `href` attribute has been specified. They allow to make a difference between a link to an external resource and a link to some content found in a peer XML document. Of course, a `linkType` is about links pointing inside the local document or inside peer XML documents, and not about links to external resources.

  The value of these attributes is a regular expression which must match the `absolute_or_relative_URI` part of the string returned by the `href` XPath expression.

  An `href` returning an `absolute_or_relative_URI` which matches the `excludePath` regular expression is considered to be a link to an external resource and as such, is ignored. Example: ignore all absolute URIs:

      excludePath="^[a-zA-Z][a-zA-Z0-9.+-]*:"

  An `href` returning an `absolute_or_relative_URI` which does not match the `includePath` regular expression is considered to be a link to an external resource and as such, is ignored. Example: ignore URIs not ending with the `.xml`, `.dbk` and `.db5` suffixes.

      includePath="\.(xml|dbk|db5)$"

  The `excludePath` and `includePath` attributes are rarely used because they are implicitly defined by XXE as:

  - Ignore absolute URIs which cannot be made relative to the URI of the document containing the element matched by `match`. For example, an "`http://`" URI cannot be made relative to a "`file:/`" URI, so ignore it.

  - Ignore URIs which do not have the same file extension as the document containing the element matched by `match`. For example, a link contained in `packaging.dita` and pointing to `samples/manifest.xml` is ignored.

An actual, commented, `linkType` for DocBook 5:

    <linkType>
      <!-- link, xref, biblioref -->
      <link match="*[@linkend]" ref="@linkend" />
      <link match="*[@endterm]" ref="@endterm" />

      <!-- area, co -->
      <link match="*[@linkends]" refs="@linkends" />

      <!-- callout -->
      <link match="*[@arearefs]" refs="@arearefs" />

      <!-- glosssee, glossseealso -->
      <link match="*[@otherterm]" ref="@otherterm" />

      <!-- indexterm -->
      <link match="*[@startref]" ref="@startref" />
      <link match="*[@zone]" refs="@zone" />

      <!-- th, td -->
      <link match="*[@headers]" refs="@headers" />

      <!-- We'll assume that "*[@xlink:href]" is a replacement for
           ulink and not an alternative to link and xref. -->

      <!-- Allows to use xi:include as a link when the transclusion
           has been turned off. -->
      <link match="xi:include" href="xincl:toHref(.)"
            xmlns:xincl="java:com.xmlmind.xml.xinclude.XInclude" />

      <anchor match="*[@xml:id]" name="@xml:id" />
    </linkType>

Prev | Up | Next
14. inclusionScheme | Home | 15.1. Using `linkType` to implement link navigation