Publisher

Introduction

The publisher is an extension component running in the content repository server.

Its original goal was to retrieve in one remote call the information you need to display on a page. The result is returned as an XML document.

However, the information that can be requested from the publisher consists of more than just XML dumps of repository entities. The publisher provides all sorts of extra functionality, such as 'prepared documents' for publishing with support for document-dependent content aggregation, or performing diffs between document versions.

The publisher was developed to support the needs of the Daisy Wiki, but is useful for other applications as well. Suggestions for features (or patches) are of course welcomed.

pubreqoverview

The publisher request format

A publisher request is an XML document with as root element p:publisherRequest, and containing various instructions. This is the full list of available instructions:

Concepts

Two kinds of publisher requests

A publisher request takes the form of an XML document, describing the various stuff you want the publisher to return. The publisher request is send to the Publisher component, and the Publisher answers with a big XML response.

Next to the publisher requests that are sent to the Publisher, the Publisher can also execute additional publisher requests as part of the p:preparedDocuments instruction. These additional publisher requests are stored in a directory accessible by the Publisher, usually this is:

<repodata dir>/pubreqs/

The format of these publisher requests is exactly the same.

Context document stack

The p:document instruction in a a publisher request pushes a document on the context document stack. A good part of the publisher instructions need a context document based on which they will work.

In expressions or in queries (such as in p:performQuery), the context document stack can be accessed using the ContextDoc(expr[, level]) function. The optional level argument of the ContextDoc function describes how high to go up in the context doc stack. See the query language reference for details.

Expressions

The parameters of some publisher instructions, specified in attributes and child-elements, can contain expressions, rather than just a literal value.

To specify an expression, the attribute or element must start with ${ and end on }. For example:

<element attribute=”${some expr}”>${some expr}</element>

Using multiple expressions or having additional content around the expression is not supported.

The expressions are Daisy query-language expressions. The identifiers apply to the current context document. For example the expression ${id} would evaluate to the ID of the current context document.

Testing a publisher request

The Publisher can be easily called using the HTTP interface. Just create an XML file containing the publisher request, and submit it using a tool like wget, which is available on many Unix systems (there's a Windows version too).

For example, create a file called pubreq.xml containing something like this:

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

  <p:document id="1-DSY">
    <p:aclInfo/>
    <p:availableVariants/>
    <p:annotatedDocument/>
    <p:annotatedVersionList/>
  </p:document>

</p:publisherRequest>

The above example assumes a document with id 1-DSY exists. If not, just change the document id.

Now we can execute the publisher request:

wget --post-file=pubreq.xml --http-user=testuser@1
     --http-passwd=testuser http://localhost:9263/publisher/request

See the HTTP API documentation for more examples on using wget.

wget will save the response in a file, typically called request. You can open it in any text or XML editor, but to view it easily readable you can use:

xmllint --format request | less

About the instruction reference

In general, the reference of the publisher instructions only displays the request syntax, and not the format of the responses. Example responses can be easily obtained by executing a publisher request.

Comments (0)