Publisher

Introduction

The publisher is an optional component that runs inside the repository server. Its goal is to retrieve in one remote call the information you want to display on a page. The result is returned as an XML document. The requestable information consists of more then just XML dumps of repository entities, the publisher provides all sorts of extra functionality, such as 'prepared documents' for publishing and diffs between document versions.

A publisher-request takes the form of an XML document which describes the various stuff you want the publisher to return. The remainder of this document describes the format of these XML requests.

The publisher was developed to support the needs of the Daisy Wiki, but can be useful for other applications as well.

The publisher request format

This section describes the format of the publisher requests. The responses are not described in much detail, they are easily viewable by trying the requests out on a live Daisy instance. This can, for example, be done by creating a file containing a publisher request and using a tool like wget to send it to the HTTP interface of the publisher.

p:publisherRequest

A basic, empty publisher request is structured as follows:

<p:publisherRequest
    xmlns:p="http://outerx.org/daisy/1.0#publisher"
    locale="en-US"
    exceptions="throw">

 [... various publisher requests ...]

</p:publisherRequest>

The reponse of a publisher request is structured as follows:

<p:publisherResponse
    xmlns:p="http://outerx.org/daisy/1.0#publisher">

 [... responses to the various requests ...]

</p:publisherResponse>

About the attributes on the p:publisherRequest element:

The locale attribute is optional, by default the en-US locale will be used.

The exceptions attribute is also optional, throw is its default value. Basically this means that if an exception occurs during the processing of the publisher request, it will be thrown. It is also possible to specify inline, in which case the error description will be embedded in the p:publisherResponse element, but no exception will be thrown.

p:document

A p:document request is used to retrieve various information about a document. The information to be retrieved is specified by adding child elements to the p:document element.

The p:document element can take the following attributes: id, branch, language and version.

Usually id, branch and language are required, except when the p:document element is embedded in a p:forEach element (see further on). The branch and language can be specified either by name or by their numeric id.

The version attribute is optional, by default the live version will be used. The version attribute can contain an explicit version number, or the symbolic values live and last.

The following sub-sections describe the various elements that can appear inside a p:document element.

p:aclInfo

Evaluates the document against the ACL and returns the result. This request requires no attributes.

p:subscriptionInfo

Returns whether the user is subscribed for email notifications for this document, the result is a tag like this:

<p:subscriptionInfo subscribed="true|false"/>

This request requires no attributes.

p:comments

Returns the comments for the current document. Newlines in the comments are replaced with <br/> tags. This request requires no attributes.

p:availableVariants

Returns the available variants for this document. This request requires no attributes.

p:preparedDocuments

Returns the content of the document prepared for publishing. The preparation consists of such things 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

The full format of the request is:

<p:preparedDocuments applyDocumentTypeStyling="true|false">
  <p:context branch="..." language="..."/>
  <p:navigationDocument id="..." branch="..." language="..."/>
</p:preparedDocuments>

The applyDocumentTypeStyling attribute isn't used by the publisher, but is simply replicated in the result. In the Daisy Wiki, its purpose is to indicate whether document type specific styling should be automatically applied.

The p:context element is required and indicates what the default branch and language is in the context in which the document is displayed. For example, in the Daisy Wiki, this would be the site branch and language.

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

The result structure of a p:preparedDocuments request is as follows:

<p:preparedDocuments applyDocumentTypeSpecificStyling="true|false">
  <p:preparedDocument id="1">
    <d:document ...
  </p:preparedDocument>
  <p:preparedDocument id="2">
    <d:document ...
  </p:preparedDocument>
</p:preparedDocuments>

This needs some explanation. The requested document will be returned in the p:preparedDocument element with 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 document type specific styling on each separate documents 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 a single d:document element. This 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.

p:shallowAnnotatedVersion

Returns the shallow version XML (this the version XML without field and part information in it), thus a "d:version" element. This request requires no attributes.

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

p:annotatedDocument

Returns the document XML with some slight annotations, thus a d:document element. This request requires no attributes.

In contrast with most other elements, if you request the live version of the document but the document doesn't have a live version, this element will automatically fallback to the last version, so there will always be a d:document element in the response.

p:annotatedVersionList

Returns a list of all versions of the document (as a d:versions element). This request requires no attributes.

p:diff

Returns a diff of the document version with an other version of this document or another document.

The full form of this request is:

<p:diff>
  <p:otherDocument id="..."  branch="..." language="..." version="..."/>
</p:diff>

If no p:otherDocument element is specified, the diff will automatically be taken with the previous version of the document. If there is no such version (because the document has only one version yet), there will be no diff response.

If a p:otherDocument element is supplied, any combination of attributes is allowed, in other words all attributes are optional.

p:navigationTree

Returns a navigation tree. The full form of this request is:

<p:navigationTree>
  <p:navigationDocument id="..." branch="..." language="..."/>
  <p:activeDocument id="..." branch="..." language="..."/>
  <p:activePath>...</p:activePath>
  <p:contextualized>true|false</p:contexutalized>
</p:navigationTree>

The activeDocument and activePath elements are optional.

p:myComments

Returns a list of all private comments of the user.

p:performQuery

Returns the result of executing a query. The full form of this request is:

<p:performQuery>
  <p:query>...</p:query>
  <p:extraConditions>...</p:extraConditions>
</p:performQuery>

The p:extraConditions element is optional.

The result of a query is a d:searchResult element.

p:forEach

The p:forEach element allows to perform a p:document request for each document (actually, document variant) returned by query. The full form of this request is:

<p:forEach useLastVersion="true|false">
  <p:query>...</p:query>
  <p:document .... />
</p:forEach>

If the useLastVersion attribute is false or not specified, the live version of each document will be used, otherwise the last version.

p:group

The p:group element performs no function by itself, except to act as a container for other requets. It needs an id attribute:

<p:group id="...">

 [... other requests here ...]

</p:group>

It allows to distinguish between different queries or navigation tree results if you would have more then one of them.