4.12.24 p:preparedDocuments (& p:prepareDocument)

p:preparedDocuments is the most powerful of all publisher requests. It returns the content of the document prepared for publishing. The preparation consists of all sorts of things such as:

• inlining the content of Daisy-HTML parts in the document XML.
• executing queries and query-includes embedded inside documents
• annotating images with the name of target document and the file name of the ImageData part.
• annotating "daisy:" links with the name of the target document and the path in the navigation tree (if navigation tree details have been supplied)
• processing includes

A very important point of p:preparedDocuments is that is able to use secondary publisher requests for the requested document and each included document. The publisher requests to use are determined based on a mapping file and allow to aggregate additional information withoccu the document based on e.g. its document type.

4.12.24.1 Request

Syntax:

<p:preparedDocuments publisherRequestSet="..."
                     displayContext="free string"
                     applyDocumentTypeStyling="true|false">
  <p:navigationDocument id="..." branch="..." language="..."/>
</p:preparedDocuments>

The applyDocumentTypeStyling and displayContext attributes are not used by the publisher, but are simply replicated in the result.

In the Daisy Wiki, their purpose are:

• applyDocumentTypeStyling: indicates if document styling should be automatically applied on preparedDocuments occurring in a publisher response (the "Type" in the attributes name is because historically the document styling is dependent on the type of document)
• displayContext: a freely choosen string indicating in which context the document is displayed. This string is made available to the document-styling XSLT. It allows to alter the styling depending on whether the document is displayed standalone or aggregated with some other document (or as part of a feed, or whatever).

The publisherRequestSet attribute: see below.

The p:navigationDocument element is optional. If supplied, it enables to annotate "daisy:" links with the path where they occur in the navigation tree.

4.12.24.1.1 How it works

p:preparedDocuments looks up a new publisher request to be performed on the context document. The publisher request to be used can be determined dynamically (described further on), but by default it is this one:

<p:publisherRequest xmlns:p="http://outerx.org/daisy/1.0#publisher">
  <p:prepareDocument/>
  <p:aclInfo/>
  <p:subscriptionInfo/>
</p:publisherRequest>

This publisher request should (usually) contain a <p:prepareDocument/> element. The p:prepareDocument will be replaced by the Daisy document as XML (d:document), in which the HTML content is inlined and processed (i.e. the things mentioned in the enumeration above). If the content contains an include of another document, then for this included document the publisher will again determine a publisher request to be performed upon it, and execute it. The same happens for each include (recursively). The results of all these publisher requests are inserted in the publisher response in a structure like this:

<p:preparedDocuments applyDocumentTypeSpecificStyling="true|false">

  <p:preparedDocument id="1">
    <p:publisherResponse>
      <d:document ...
    </p:publisherResponse>
  </p:preparedDocument>

  <p:preparedDocument id="2">
    <p:publisherResponse>
      <d:document ...
    </p:publisherResponse>
  </p:preparedDocument>

</p:preparedDocuments>

The publisher response of the context document will always end up in the p:preparedDocument element with attribute id="1".  If the document includes no other documents, this will be the only p:preparedDocument. Otherwise, for each included document (directly or indirectly), an additional p:preparedDocument element will be present.

So the included documents are not returned in a nested structure, but as a flat list. This allows to perform custom styling on each separate document before nesting them.

On the actual location of an include, a p:daisyPreparedInclude element is inserted, with an id attribute referencing the related p:preparedDocument element.

The content of a p:preparedDocument element is thus a single p:publisherResponse element, which in turns contains a single d:document element (as result of the p:prepareDocument in the publisher request). This d:document element follows the standard form of XML as is otherwise retrieved via the HTTP interface or by using the getXml() method on a document object, but with lots of additions such as inlined content for Daisy-HTML parts and non-string attribute values formatted according to the specified locale.

If you requested the live version of the document, but the document does not have a live version, there will simply be no p:preparedDocuments element in the response.

4.12.24.1.2 Determination of the publisher request to be performed

If instead of the default publisher request mentioned above, you want to execute some custom publisher request (which can be used to retrieve information related to the document being published), then this is possible by defining a publisher request set.

In the data directory of the repository server, you will find a subdirectory called 'pubreqs'. In this directory, each subdirectory specifies a publisher request set. Each such subdirectory should contain a file called mapping.xml and one or more other files containing publisher requests.

The mapping.xml file looks like this:

<m:publisherMapping xmlns:m="http://outerx.org/daisy/1.0#publishermapping">
  <m:when test="documentType = 'mydoctype'" use="myrequest.xml"/>
  <m:when test="true" use="default.xml"/>
</m:publisherMapping>

The publisher will run over each of the when rules, and if the expression in the test attribute matches, it will use the publisher request specified in the use attribute. The expressions are the same as used in the query language, and thus also the same as used in the ACL definition.

To make use of such a specific set of publisher requests, you use the publisherRequestSet attribute on the p:preparedDocuments element. The value of this attribute should correspond to the name of subdirectory of the pubreqs directory.

In the Daisy Wiki, the publisher request set to be used can be specified in the siteconf.xml

4.12.24.1.3 p:prepareDocument

<p:preparedDocument inlineParts="...">
  <p:linkAnnotation>
    <p:element name="my_element" attribute="my_attr" navigationPath="true" imageAnnotation="false"/>
    <p:element xmlns:n="myns" name="n:link" attribute="n:target"/>
  </p:linkAnnotation>
</p:preparedDocument>

4.12.24.1.3.1 inlineParts

The p:prepareDocument can have an optional attribute called inlineParts. This attribute specifies a comma-separated list of part type names (or IDs) for which the content should be inlined. By default this only happens for parts for which the Daisy-HTML flag is set to true.

The inlining will only happen if the actual part has a mime-type that starts with "text/" or if the mime-type is recognized as an XML mime-type. Recognized XML mime-types are currently text/xml, application/xml or any mime type ending with "+xml".

If it is an XML mime-type, then the content will be parsed and inserted as XML. Otherwise, it will be inserted as character data (assuming UTF-8 encoding of the part text data). If the inlining actually happened, an attribute inlined="true" is added to the d:part element in question.

4.12.24.1.3.2 linkAnnotation

In prepared documents, links are annotated with information about the target document they link to. This is done for "daisy:" links, the annotation consists of a p:linkInfo element which is added as first child of the link element.

By default, the publisher does this for the following attributes:

• a/@href
• img/@src
• d:link/@target (= the out-of-line links)

If you want link annotation to happen for other elements, you can configure this through the optional p:linkAnnotation element. This lists a number of element-attribute pairs which might contain "daisy:" links. Note that for each element, there can be only one link attribute. The "name" and "attribute" attributes can contain qualified names, thus names including a namespace prefix, the prefix should of course be valid.

The custom configuration takes precedence over the built-in configuration.

The optional attribute navigationPath (default: false) indicates whether the path in the navigation tree for the linked-to document should be added.

The optional attribute imageAnnotation (default: false) indicates whether image-specific annotations should be added. Currently, these are the value of the ImageWidth and ImageHeight fields.