Getting started

Creating your first extension

Here we show how to create a very simple and mostly useless "hello world" extension, just to illustrate some basics. We will create a Cocoon pipeline which generates a blurb of HTML showing "Hello world" and then show how to include that in a Daisy document.

Create a directory for your extension

We will create a cross-site extension. By default, Daisy already includes some extension samples in the cross-site extension directory:

<DAISY_HOME>/daisywiki/webapp/daisy/sites/cocoon

Create a new subdirectory over there for your extension, lets say we call it mytest:

<DAISY_HOME>/daisywiki/webapp/daisy/sites/cocoon/mytest

The sites/cocoon directory should already exist and contain a sitemap.xmap file, otherwise this will not work. On a default Daisy install, this should be no problem.

Create a sitemap

In the above created directory, create a file called sitemap.xmap with the following content:

<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

  <map:components>
  </map:components>

  <map:views>
  </map:views>

  <map:resources>
  </map:resources>

  <map:pipelines>

   <map:pipeline type="noncaching">
     <map:parameter name="outputBufferSize" value="8192"/>

     <map:match pattern="hello">
       <map:generate src="hello.xml"/>
       <map:transform src="hello.xsl"/>
       <map:serialize type="xml"/>
     </map:match>

   </map:pipeline>

 </map:pipelines>
</map:sitemap>

The sitemap.xmap file is used by Cocoon to decide how to handle a request. This sitemap specifies that if the path matches "hello" (at least, the part of the path stripped from the part leading to this extension), then an XML-producing pipeline is executed which starts by reading and parsing the file hello.xml, transforming the parsed XML using the hello.xsl XSLT, and then finally serializing the result back to an XML document in the form of a byte stream (which is sent to the browser, or whoever made the HTTP request)

Create the file hello.xml

Still in the same directory, create a file called hello.xml with the following content:

<?xml version="1.0"?>
<hello>
  <helloText>Hello world!</helloText>
</hello>

Create the file hello.xsl

Also in the same directory, create a file called hello.xsl with the following content:

<?xml version="1.0"?>
<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  version="1.0">

  <xsl:template match="hello">
    <div style="border: 1px solid blue;">
      <xsl:value-of select="helloText"/>
    </div>
  </xsl:template>

</xsl:stylesheet>

For those unfamiliar with XSLT, this stylesheet defines a template which is executed when a hello element is encountered in the input. In that case, a div element is outputted with as content the value of the helloText element that is a child of the current hello element.

Try it out in your browser

Surf to the following URL (or equivalent), substituting <sitename> with the name of your Daisy Wiki site:

http://localhost:8888/daisy/<sitename>/ext/mytest/hello

If your browser shows XML (such as Firefox or IE), you will see this:

<div style="border: 1px solid blue;">Hello world!</div>

Include this in a Daisy document

To include this piece of HTML in a Daisy document:

• create or edit a document
• in the block-style dropdown, choose Include
• the paragraph switches to an include-style paragraph
• enter cocoon:/ext/mytest/hello for the content of the paragraph
  

  Background detail: "cocoon:" URLs allow to make internal Cocoon requests, thus these requests don't go over HTTP, nor is the result of the called pipeline serialized in between (Cocoon pipelines are SAX-based, thus are not based on byte streams but rather XML-representing events).

• save the document, you should see the text "Hello world!" in a blue box in your document

Further pointers

You can now explore the various samples for further inspiration.

You'll see that many samples make use of Cocoon flowscript, which is basically Javascript with some Cocoon-specific APIs included (which also includes an advanced flow-control feature called continuations, but see the Cocoon documentation for that).

Daisy provides some additional functions for usage in flowscript, see the daisy-util.js reference.

In the sitemap, a line like this calls a function defined in a .js file:

<map:call function="minimalRss"/>

The function can then do some work (such as gattering data) and finally calls the sitemap again to show a page, using the sendPage function.

Many examples also make use of the Publisher, which is an extension component running inside the repository server. Its purpose and request format is described on its own page.