In this tutorial we'll show how it is possible to associate documents with a main document through a link field, and have these associated documents published along with the main document, rendered as "side boxes" (see the screenshot at the end of this article). As an added bonus, these side boxes will have edit links for users that have write access to them.

All this can be done by only defining some document types, defining a custom publisher request, and a custom XSL.

This tutorial is quite "cookbook" style, for more background on the concepts used here, see the main Daisy documentation.

This tutorial requires Daisy 1.5.

Define schema types

We'll start by creating the schema types we need: a document type called "WebPage" which has a field type called "sideboxes" to refer to documents of type "SideBox".

So, create the following types now through the Administration pages of the Daisy Wiki. If you don't know how to do this, see some of the other tutorials.

Create a field type:

• name: sideboxes
• type: link
• check the multivalue checkbox
• (optional) selection list: choose "Query based selection list for link type fields". In Query box enter:
  

  documentType = 'SideBox'

Create a document type:

• name: WebPage
• add the part type SimpleDocumentContent
• add the field type sideboxes

Create another document type

• name: SideBox
• add the part type SimpleDocumentContent

Create some content

Create two (or more) documents of type "SideBox", enter some (not too long) content in them.

Then create a document of type "WebPage". Enter some content. Go to the fields tab, select the created SideBox documents for the sideboxes field.

Create a publisher request set

We'll now create a custom publisher request and request set. If you are already using a custom publisher request set for the site in which you are trying this out, you can of course use your existing publisher request set.

In the repository data directory, in the pubreqs subdirectory, create a new subdirectory, for example called "foobar":

<daisy data dir>/pubreqs/foobar

In this directory, create a file called mapping.xml with the following content:

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

This mapping file tells that for documents of type WebPage, a custom publisher request defined in the file webpage.xml should be used. For all other documents, the publisher request in the file default.xml will be used. We will now create these two files.

So, in the same directory, create a file called webpage.xml with the following content:

<?xml version="1.0"?>
<p:publisherRequest xmlns:p="http://outerx.org/daisy/1.0#publisher" styleHint="WebPage.xsl">
  <p:prepareDocument/>
  <p:aclInfo/>
  <p:subscriptionInfo/>

  <p:group id="sideboxes">
    <p:document field="sideboxes">
      <p:aclInfo/>
      <p:preparedDocuments applyDocumentTypeStyling="true" publisherRequestSet="default"/>
    </p:document>
  </p:group>
</p:publisherRequest>

This custom publisher request specifies that for all documents linked to in the field "sideboxes", we want to execute a "preparedDocuments" request for them. The "p:group" element serves no purpose other than to distinguish these sidebox documents from the rest.

And a file called default.xml with this in it:

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

Now we need to instruct the Daisy Wiki to make use of this "foobar" publisher request set we just created. For this, open the siteconf.xml file of your Wiki site:

<wikidata dir>/sites/<yoursite>/siteconf.xml

And make sure the following is in there (if there is already a publisherRequestSet element, update its content, otherwise add it as child of the root element):

<publisherRequestSet>foobar</publisherRequestSet>

After doing this, have a look at the document of type WebPage you created (in the Wiki) and refresh it, to see everything is still working (it will still look the same as before).

Styling

The only remaining thing to do is to create an XSL to display our sideboxes.

For this, create a file called WebPage.xsl in the directory (which you might need to create)

<wikidata dir>/resources/skins/default/document-styling/html

(assuming you're using the default skin, otherwise adjust the "default" in this path)

and put the following in it:

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://outerx.org/daisy/1.0"
  xmlns:p="http://outerx.org/daisy/1.0#publisher">

  <xsl:import href="daisyskin:xslt/document-to-html.xsl"/>
  <xsl:import href="daisyskin:xslt/util.xsl"/>

  <xsl:template match="d:document">
    <div style="float: left; width: 65%">
      <h1 class="daisy-document-name"><xsl:value-of select="@name"/></h1>
      <xsl:apply-templates select="d:parts/d:part"/>
      <xsl:apply-templates select="d:links"/>
      <!-- Hide the fields
      <xsl:apply-templates select="d:fields"/>
      -->
      <xsl:call-template name="insertFootnotes">
        <xsl:with-param name="root" select="."/>
      </xsl:call-template>
    </div>

    <div style="float: right; width: 20em;">
      <xsl:for-each select="../p:group[@id='sideboxes']/p:document">
        <div style="border: 1px solid black; background-color: #ddd; margin: 1em; padding: 1em;">
          <insertStyledDocument styledResultsId="{p:preparedDocuments/@styledResultsId}"/>
          <xsl:if test="d:aclResult/d:permissions/d:permission[@type='write' and @action='grant']">
            <xsl:call-template name="generatePostLink">
              <xsl:with-param name="action" select="concat($documentBasePath, @documentId, '/edit')"/>
              <xsl:with-param name="label">Edit</xsl:with-param>
              <xsl:with-param name="id" select="generate-id(.)"/>
            </xsl:call-template>
          </xsl:if>
        </div>
      </xsl:for-each>
    </div>

    <div style="clear:both;"/>
  </xsl:template>

</xsl:stylesheet>

The end result

Click to enlarge

Summary & notes

• After editing a sidebox, the sidebox document is displayed, while we would prefer to go back to the main document. At the time of this writing this was not possible, but we'll look into adding a "returnTo URL" feature to the document editor.

Fields