[RT] Forrest Plugins

[Ross Gardler <rg...@apache.org>]

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

Re: [RT] Forrest Plugins

[Nicola Ken Barozzi <ni...@apache.org>]

Ross Gardler wrote:
...
> Furthermore, we can use the branch to strip the core of Forrest down to 
> its basic functionality by moving stuff like the Open Office integration 
> into a plugin.

+1

Right now I'm really fulla stuff to do so unfortunately I can't help, 
but I will look at it with interest as soon as I find dome time :-)

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: [RT] Forrest Plugins

[Ross Gardler <rg...@apache.org>]

Ross Gardler wrote:
> I will shortly commit a test site that shows the IMS Manifest file in 
> use. Right now I need to reboot my machine it seems to be dying on me.

I haven't committed a test site to SVN as I do not have the time to 
create one right now and realised I can't upload the one I had in mind 
because of licensing issues.

So, I've uploaded a demo site to my apache web space so people can play 
with. To have a look at the plugin capability:

svn switch https://svn.apache.org/repos/asf/forrest/branches/sitemap-plugins

[optional] forrest available-plugins

forrest install-plugin

enter 'IMSManifest' at the prompt

(forrest downloads the plugin and installs it)

download the demo site that uses an IMS Manifest instead of site.xml and 
tabs.xml from 
http://www.apache.org/~rgardler/testingGround/forrestPlugins/demoIMSSite.zip

Then run forrest as normal.

WARNING
=======

forrest will not run until you have installed the plugin since the last 
stage of the install process is not yet automated. This stage inserts 
the necessary sitemap mounting instructions in plugins.xmap, the 
required snippet is in the file you get from CVS so if you try and run 
before installing the plugin it will complain about not being able to 
find it.

Ross

Re: [RT] Forrest Plugins

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:
> Ross Gardler wrote:

<snip what="does this plugins idea work?"/>

 >
> Make a sitemap-plugins branch from current trunk and commit there.
> 

Well the changes are really pretty trivial, just a couple of sitemap 
additions and a modified version of the skin install files. 
Nevertheless, I have created a branch so as not to interfere with the 
0.6 release. I don't think that this feature should be included until 
after 0.6 is out the door.

Furthermore, we can use the branch to strip the core of Forrest down to 
its basic functionality by moving stuff like the Open Office integration 
into a plugin.

The current status of the branch is that everything works except the 
final stage of installation, which is the adding of the necessary 
matcher to the plugins.xmap file. For now the there is only one plugin, 
the IMS Manifest plugin. The required matcher for this is already in 
plugins.xmap.

I will shortly commit a test site that shows the IMS Manifest file in 
use. Right now I need to reboot my machine it seems to be dying on me.

> ...
> 
>> ***********************************************************************
>> 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?
>> ***********************************************************************
> 
> 
> It's possible, but I would have to try it on a real case, as I'm not 
> sure OTOMH what approach will work. If all simple things fail, we can 
> make a ResourceExistsMatcher.

Now we have the branch we can look at this in good time.

(I never worked with Branches before, so I hope I have done everything 
correctly.)

> 
>> 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?).
> 
> 
> I would prefer not put anything in the src directory.
> 
> Maybe simply forrest/plugins?

Yes, I agree. I was thinking that since the plugins will have src files 
they should be in source, but this is about where they are installed, 
not where they are developed. I have gone with forrest/plugins.

Ross

Re: [RT] Forrest Plugins

[Nicola Ken Barozzi <ni...@apache.org>]

Ross Gardler wrote:
> ===============
> Forrest Plugins
> ===============

I was very excited about this when I read it because it explaines in 
detail what I was still musing about at an early stage... but I had to 
shut down the computer and could not reply earlier.  :-(

+1 all the way, it totally rocks! :-)

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

Make a sitemap-plugins branch from current trunk and commit there.

...
> ***********************************************************************
> 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?
> ***********************************************************************

It's possible, but I would have to try it on a real case, as I'm not 
sure OTOMH what approach will work. If all simple things fail, we can 
make a ResourceExistsMatcher.

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

I would prefer not put anything in the src directory.

Maybe simply forrest/plugins?

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------