5.10.3 Link transformation
This section is about the transformation of links in the Daisy Wiki from "daisy:" to the public URL space.
18.104.22.168 Format of the links
It might be good to review the format of the links first. The structure of a Daisy link is:
The branch, language and version are all optional. Branch and language can be specified either by name or ID. The version is typically a version ID, or the string "live" (default) or "last" (to link to the last version). The fragment identifier is of course also optional.
A fragment identifier is used to point to a specific element in the target document.
If the branch and language are not mentioned, they are defaulted to be the branch and language of the document containing the link (and thus not to the default branch and language of the Daisy Wiki site).
A link can also consist of only a fragment identifier, to link to an element within the current document:
The document addressed by a link is called the target document.
22.214.171.124 When and what links are transformed
The link transformation happens after the document styling XSLT has been applied.
The transformation applies to links in the following places:
- the href attribute of the <a> element
- the src attribute of the <img> element
- the content of <span class="crossref"> elements
126.96.36.199 Input for the document styling XSLT
Since the link transformation happens after the document styling, the
document styling XSLT can influence the linking process (see "Linking directly
to parts" below). For this, it is useful to know that the
<a href="daisy:123" p:navigationPath="/info/123"> <p:linkInfo documentName="..." documentType="..." access="..."> <p:linkPartInfo id="..." name="..." fileName="..."/> </p:linkInfo> see this </a>
The whitespace and indenting is added here for readability, in reality no new whitespace is introduced (since the whitespace inside inline elements is significant).
The p:navigationPath attribute gives the path in the navigation tree where the document occurs. This attribute is only added if such a path exists, and if the navigation tree is known (i.e. if it is specified to the publisher, which in the Daisy Wiki is always the case). You should usually leave the p:navigationPath attribute alone, the link transformation process will use it to make the link directly point to the 'good' navigation location (afterwards, it will remove the p:navigationPath attribute).
The access attribute describes the what permissions the user has on the
linked-to document. For more details on this attribute, see
The p:linkInfo element is only added if the target document exists and is accessible (i.e. the user has read permissions on it). It specifies the name of the target document and the name of its document type. Also, for each part in the document, a p:linkPartInfo element is added. Its id and name attribute specify the part type ID and part type name of the part. The fileName attribute is only added if the part has a file name.
It is the responsibility of the document styling XSLT to remove the p:linkInfo element. This is very simple with an empty template that matches on this element (as is the case in the default document-to-html.xsl).
188.8.131.52 Linking directly to parts
By default, the links will be transformed to links that point to the target document. This seems obvious, but sometimes it is desirable to link directly to the data of a part of the target document, for example for images. The link transformation process can be instructed to do so by leaving special attributes on the link element (<a> or <img>) in its namespace:
which is typically associated with the prefix lt.
The attributes are:
- lt:partLink: specifies the name of the part to link to, e.g. ImageData
- lt:fileName: optionally specifies a filename to append at the end of the URL path (otherwise the file name is always 'data')
Examples of how to put this to use can be found in the document-to-html.xsl, more specifically look at how images and attachments are handled there.
184.108.40.206 Branch and language handling
If the branch and language differ from those specified in the site configuration, branch and language request parameters will be added.
220.127.116.11 Fragment ID handling
Fragment identifiers are prefixed with a string identifying the target document. This is needed because it is possible to publish multiple Daisy documents in one HTML page (e.g. using document includes), and the same element ID might be used in multiple documents, giving conflicts.
The format of the prefix is dsy<docid>_, an example prefixed fragment identifier looks like this:
in which "123" is the ID of the target document, and "hello" the original fragment identifier target.
To make this work, the actual element IDs in Daisy documents are also prefixed with dsy<docid>_.
18.104.22.168 Disabling link transformation
If you want the link transformer to leave a certain link alone, add an attribute lt:ignore="true" on the link element.