Quick start

In this chapter you will learn how to install and use Patchwork within Apache Cocoon. Please make sure that you have installed the Logabit WebTools as described in the installation section before you start.

Step 1: Create your Patchwork configuration

At first you need to create your Patchwork configuration file within the directory defined by the parameter patchwork-config as configured in cocoon.xconf. Let's assume you want to define a Patchwork layout for the Header-Navi-Main layout as shown in the introduction example. You could add the following lines to your Patchwork config file:

<patchwork version="1.0">
  <layout name="index" template="templates/index.html">
    <include name="left" template="templates/left.html"/>
    <include name="header" template="templates/header.html"/>
    <include name="main" template="templates/main.html"/>
  </layout>
</patchwork>

This Patchwork configuration defines a very simple layout called index that includes the layouts left, header and main. Note that all template paths are interpreted relatively according to the currently used sitemap.

Step 2: Define the master template

The master template templates/index.html could for example look like the listing below shows:

<html xmlns:pw="http://logabit/webtools/patchwork/1.0">
  <body>
  <table width="100%">
    <tr>
      <td colspan="2"><pw:include name="left"/></td>
    </tr>
    <tr>
      <td width="200"><pw:include name="header"/></td>
      <td><pw:include name="main"/></td>
    </tr>
  </table>
  </body>
</html>

Please consider the elements <pw:include name="left"/>, <pw:include name="header"/> and <pw:include name="main"/> within this master template. They define where to place the content of the includes left, header and main. These elements are bound to the namespace http://logabit/webtools/patchwork/1.0 using the prefix pw. This procedure is necessary if you want to use the PatchworkGenerator for merging the layout with its includes. This is the default case but is is also possible to use JXTemplate and its import element in conjunction with Patchwork and without any PatchworkGenerator if you want. How to do that is documented here.

Step 3: Create the Patchwork pipeline

The last step is to create a pipeline that is able produce and return the merged layout. At first you have to register the PatchworkGenerator within your sitemap as the example below shows:

<map:generators>
  <map:generator name="patchwork" src="com.logabit.webtools.patchwork.generation.PatchworkGenerator"/>
</map:generators>

After that you can define a pipeline like this:

<map:match pattern="index">
  <map:generate type="patchwork"/>
  <map:serialize type="html"/>
</map:match>

That's it! If the uri /index is called, the PatchworkGenerator will be started. Depending on the current sitemap uri index, Patchwork will search for a layout definintion with id index within its configuration and then merging everything together for you.