forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject [RT] Forrest Plugins
Date Fri, 24 Sep 2004 13:50:44 GMT
===============
Forrest Plugins
===============

The ability to have extension sitemaps within projects has got me 
thinking about a plugin capability for Forrest. I've knocked together a 
quick implementation of this and it works a treat. In this document you 
will find a description of how I imagine this working. It describes an 
example plugin that I have manually created and installed on my local 
version of Forrest. However, I don't want to commit to SVN just yet as I 
would like feedback on my approach first. If anyone would like to see 
this simple extension mechanism in action I can put patches on JIRA.

What is a Forrest Plugin?
=========================

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.

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.

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.

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.

An Example Plugin
-----------------

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/).

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.

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.

What Does a Forrest Plugin Look Like?
=====================================

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

[plugin_name]
   |
   |-- config files (xmap, skinconf etc.)
   |
   |-- resources
       |
       |-- schema
       |   |
       |   |-- catalog.xcat
       |   |
       |   |--DTD (dtd's etc.)
       |
       |-- stylesheets (xsl's etc.)


The IMS Manifest Plugin
-----------------------

If we consider the IMS Manifest Plugin described above we will need the 
following files and directory structure:

IMSManifest
   |
   |-- sitemap.xmap
   |
   |-- resources
       |
       |-- stylesheets
                     |
                     |- imsmanifest2site.xsl
                     |- imsmanifest2tabs.xsl
                     |- pathutils.xsl
                     |- repositoryUtils.xsl

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

<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>

Note that this matcher will default to the behaviour provided by Forrest 
if there is no imsmanifest.xml file present in the project.

***********************************************************************
FIXME
Is there anyway of having the plugins sitemap just default to Forrests 
sitemap behaviour if imsmanifest.xml is not present without the need to 
duplicate code from the original sitemap.xmap file. In other words can 
we have <map:match pattern="abs-menulinks"> that only gets processed if 
the imsmanifest.xml file is present?
***********************************************************************


How is a Plugin Installed?
==========================

Installed plugins are managed by the file src/plugings/sitemap.xmap 
(FIXME: should this be src/context/plugins/sitemap.xmap?). This file is 
mounted by main Forrest sitemap with the following code:

       <map:pipeline internal-only="false">
          <map:mount uri-prefix=""
                     src="{forrest:plugins}/sitemap.xmap"
                     check-reload="yes"
                     pass-through="true"/>
       </map:pipeline>

The plugin sitemap.xmap file is autmatically managed by Forrest, the end 
user need never edit this file.

To install a plugin the user will run the command 'forrest 
install-plugin'. This will ask the user for the name of the plugin they 
wish to install and search known plugin repositories for the plugin 
package. If found the plugin package will be downloaded and extracted 
into the src/plugins directory of Forrest and an entry will be made in 
src/plugins/stitemap.xmap. For example, installing the IMSManifest 
plugin described above will result in the following entry being added to 
the plugin sitemap:


     <map:pipeline internal-only="false">
        <map:mount uri-prefix=""
                   src="{forrest:plugins}/IMSManifest/sitemap.xmap"
                   check-reload="yes"
                   pass-through="true"/>
     </map:pipeline>

--------------

Comments?

Ross



Mime
View raw message