<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

<document>
  <header>
    <title>Extending Forrest with Plugins</title>
  </header>

  <body>
    <section id="overview">
      <title>Overview</title>
      <p>Forrest provides the core functionality for generating documentation
      in various output formats from a range of input formats. However, it
      does not end there. Forrest can be extended through the addition of
      plugins. This document serves as an introduction to the Forrest
      plugin mechanism.</p>
  
      <section>
        <title>What plugins are available?</title>
        <p>You can run the command <code>forrest available-plugins</code> to get
        a list of the known plugins for Forrest.</p>
        
        <p>If you would like to have your own plugin added to this list then
        contact the <a href="site:mail-lists">developer mailing list</a>.</p>
      </section>
        
        
      <section>
        <title>How is a Plugin Installed?</title>
    
        <p>If a site requires a plugin then it will be named in the 
        <code>project.required.plugins</code> property in the projects
        <code>forrest.properties</code> file. When Forrest builds the site
        it will automatically discover the plugin and install it. In otherwords,
        the user need do nothing.</p>
          
    </section>
  </section>
    
    <section>
      <title>What is a Forrest Plugin?</title>

      <p>A Forrest plugin is a set of resources and configuration files that 
      extend the functionality of Forrest. They will typically consist of a 
      sitemap, zero or more stylesheets and zero or more schema's.</p>

      <p>The plugins sitemap is mounted by Forrests sitemap after the project 
      specific sitemap but before the Forrest default matchers. This allows 
      individual projects to override/extend functionality provided in either 
      a plugin or Forrest whilst plugins are only able to override/extend the 
      default Forrest behaviour.</p>

      <p>Forrest is easily extensible through the existing sitemap.xmap files, 
      however the more features we add the more complex the sitemap becomes. It 
      is already quite difficult to understand the default sitemap.xmap files, 
      and this will only get worse as new features find their way into the 
      core.</p>

      <p>By adopting a plugin model we can keep the core of Forrest tightly 
      focused on the basic functionality whilst still facilitating extensions 
      to suit individual projects needs.</p>
    
      <section>
        <title>An Example Plugin</title>
  
        <p>In order to fully understand the applicability of Forrest Plugins we 
        will consider an extension to the way in which Forrest defines the 
        structure of the site. By default Forrest uses a site.xml file to 
        define navigation through the site and a tabs.xml file to define the 
        tabs across the top of the page. But what if we want to use a different
        file to describe site structure? For example, what if we want to use an
        IMS Manifest file from the SCORM content package standards 
        (http://www.adlnet.org/).</p>
  
        <p>An IMS Manifest file describes the structure of a site. It is also 
        possible to define a set of rules for extracting tab information from 
        such a file. Consequently, it is possible to use an IMSManifest file to 
        create Forrests site.xml and tabs.xml files. The advantage would be that
        we can then use SCORM compliant content objects within Forrest.</p>
  
        <p>Unfortunately, IMS Manifests are much more complex than site.xml and 
        tabs.xml files. Therefore, not all users will want to use them. Adding 
        the functionality as an optional plugin seems to be the ideal 
        solution.</p>
      </section>
    </section>

    <section>
      <title>What Does a Forrest Plugin Look Like?</title>

      <p>Plugins will need to conform to a specified directory structure. 
      This mirrors the default forrest directory structure:</p>

<source>
[plugin_name]
  |
  |-- config files (xmap, skinconf etc.)
  |
  |-- resources
      |
      |-- schema
      |   |
      |   |-- catalog.xcat
      |   |
      |   |--DTD (dtd's etc.)
      |
      |-- stylesheets (xsl's etc.)
</source>
  
    <section>
      <title>The IMS Manifest Plugin</title>

      <p>If we consider the IMS Manifest Plugin described above we see that we
      will need the following files and directory structure:</p>

     
<source>
IMSManifest
  |
  |-- sitemap.xmap
  |
  |-- resources
      |
      |-- stylesheets
                    |
                    |- imsmanifest2site.xsl
                    |- imsmanifest2tabs.xsl
                    |- pathutils.xsl
                    |- repositoryUtils.xsl
</source>

      <p>The sitemap.xmap file will override the default behaviour for the 
      navigation generation matchers in Forrest, for example, it contains 
      a matcher as follows:</p>

<source><![CDATA[
<map:match pattern="abs-menulinks">
  <map:select type="exists">
    <map:when test="{project:content.xdocs}imsmanifest.xml">
       <map:generate src="{project:content.xdocs}imsmanifest.xml" />
       <map:transform src="{forrest:plugins}/IMSManifest/resources/stylesheets/imsmanifest2site.xsl"/>
       <map:transform src="{forrest:stylesheets}/absolutize-linkmap.xsl" />
       <map:transform src="{forrest:stylesheets}/site2site-normalizetabs.xsl" />
     <map:serialize type="xml"/>
   </map:when>
   <map:when test="{project:content.xdocs}site.xml">
      <map:generate src="{project:content.xdocs}site.xml" />
      <map:transform src="{forrest:stylesheets}/absolutize-linkmap.xsl" />
      <map:transform src="{forrest:stylesheets}/site2site-normalizetabs.xsl" />
      <map:transform src="{forrest:stylesheets}/normalizehrefs.xsl"/>
    <map:serialize type="xml"/>
  </map:when>
  </map:select>
</map:match>
]]></source>

      <note>Note that this matcher will default to the behaviour provided by 
      Forrest if there is no imsmanifest.xml file present in the project.
      At present it is necessary to copy this default behaviour from the original
      Forrest *.xmap files. We hope to improve on this in the future.</note>
    </section>
  </section>

  <section>
    <title>How does Installation work?</title>
    <p>When Forrest installs a plugin it downloads a zip of the plugin code and 
    extracts it into the <code>plugins</code> directory of Forrest and an entry is made 
    in <code>src/plugins/stitemap.xmap</code>. For example, installing the 
    IMSManifest plugin described above will result in the following entry 
    being added to the plugin sitemap:</p>

  <source><![CDATA[
<map:select type="exists">
  <map:when test="{forrest:plugins}/IMSManifest/sitemap.xmap">
    <map:mount uri-prefix="" 
      src="{forrest:plugins}/IMSManifest/sitemap.xmap" 
      check-reload="yes" 
      pass-through="true"/>
  </map:when>
</map:select>
  ]]></source>
  
      <p>Installed plugins are managed by the file 
      FORREST_INSTALL_DIR/plugings/sitemap.xmap. This file is mounted by main 
      Forrest sitemap with the following code:</p>
  
  <source><![CDATA[
        <map:pipeline internal-only="false">
           <map:mount uri-prefix=""
                      src="{forrest:plugins}/sitemap.xmap"
                      check-reload="yes"
                      pass-through="true"/>
        </map:pipeline>
  ]]></source>
      
      <note>The plugin sitemap.xmap file is automatically managed by Forrest, the 
      end user need never edit this file.</note>
    </section>
  </body>
</document>
