Welcome to the org.apache.forrest.plugin.input.Daisy Plugin

This plugin retrieves documents from a Daisy repository.

Perhaps the most important thing to realise about this plugin is that there is no relationship between the Forrest URL space and the URL space defined in the Daisy repository. That is the path to and the name of each document within Forrest needs not be the same as the path to and the name of the document within the Daisy repository.

This enables the repository to be structured in a way that is appropriate for it's editors and the Forrest document collection can be structured in a way that is appropriate for the target audience. In fact, it is possible to use the same document from a Daisy repository in multiple Forrest collections each using a completely different URL space that is custom designed for the end user of the document collection.

Locationmap

In order to tell Forrest which document to retrieve from the repository you need to make use of the locationmap in Forrest. Your project must therefore provide a locationmap similar to the one that follows.

<locationmap xmlns="http://apache.org/forrest/locationmap/1.0">

  <components>
    <matchers default="lm">
      <matcher 
        name="lm" 
        src="org.apache.forrest.locationmap.WildcardLocationMapHintMatcher"/>
    </matchers>
  </components>
  
  <locator>
   
     <match pattern="index.xml">
         <location src="cocoon://908.daisy.xml" />
     </match>
   
     <match pattern="*.daisy.source">
         <location src="http://username:password@repository.domain.com:9263/publisher/documentPage?documentId={1}&amp;includeNavigation=false&amp;locale=en_US&amp;version=live" />
     </match>
   
     <match pattern="*.daisy.img">
         <location src="http://username:password@repository.domain.com:9263/publisher/blob?documentId={1}&amp;version=live&amp;partType=3" />
     </match>
   
     <match pattern="*.daisy.navigation">
         <location src="http://username:password@repository.domain.com:9263/publisher/blob?documentId={1}&amp;version=live&amp;partType=1" />
     </match>
 
  </locator>
</locationmap>
        

The first match (pattern="index.xml") will redirect the request for index.xml to a named document in the daisy repository. If you provide your index.xml file locally then omit this matcher.

The next match (pattern="*.daisy.source") is used by the plugin to resolve requests for daisy documents.

The next match (pattern="*.daisy.img") is used by the plugin to resolve requests for images stored in the daisy repository.

The next match (pattern="*.daisy.navigation") is used by the plugin to resolve requests for daisy navigation documents.

Using Daisy Navigation Documents

It is possible to use a daisy navigation document in place of a local site.xml file. However, in order to allow other content to be added to the forrest publication without requiring write access to the Daisy repository your project still requries a site.xml file.

A minimal site.xml file for your project would be:

<site label="MyProj" href="" 
  xmlns="http://apache.org/forrest/linkmap/1.0" 
  xmlns:xi="http://www.w3.org/2001/XInclude" 
  tab="">
  <xi:include href="cocoon://1208.daisy.navigation"/>
</site>
        

Note that we use xi:include to include a navigation document in the site.xml file, in this case the document retrieved has id 1208. By using include in this way the site editor is free to use site.xml to reference content from other sources.

Retrieving RAW content

If you want to retrieve the raw, unprocessed XML from Daisy simply request the file with a .daisy.source extenstion.

You may not have full control of the content in the repository, or you may wish to supress the presentation of some of the parts, for example, the fields within the repository. There are two points at which you can filter the content, at the point of retrieval (called a pre-filter) and once the file has been converted to the internal Forrest format (called a post-filter).

Pre-Filters

Pre-Filters are applied to the XML retrieved from the Daisy repository. To achieve this you can provide an XSL file called daisy/preFilter.xsl in your projects stylesheet directory (default location is PROJECT_HOME/src/documentation/resources/stylesheets).

Post-Filters

Post-Filters are applied to the XDoc generated by Forrest. To achieve this you can provide an XSL file called daisy/postFilter.xsl in your projects stylesheet directory (default location is PROJECT_HOME/src/documentation/resources/stylesheets).

The postFilter XSL file operates on the XDoc generated by Forrest. If you wish to look at this format of the document simply request the page with an .xml extension.