forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgard...@apache.org
Subject svn commit: rev 65602 - forrest/trunk/docs-author/content/xdocs/plugins
Date Sun, 14 Nov 2004 16:31:24 GMT
Author: rgardler
Date: Sun Nov 14 08:31:23 2004
New Revision: 65602

Added:
   forrest/trunk/docs-author/content/xdocs/plugins/pluginInfrastructure.xml   (contents, props
changed)
Log:
split plugin documentation between user and developer topics

Added: forrest/trunk/docs-author/content/xdocs/plugins/pluginInfrastructure.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/docs-author/content/xdocs/plugins/pluginInfrastructure.xml	Sun Nov 14 08:31:23
2004
@@ -0,0 +1,192 @@
+<?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>Plugin Infrastructure</title>
+  </header>
+
+  <body>
+    <section id="overview">
+      <title>Overview</title>
+      <p>Forrest can be extending with the addition of plugins. This document
+      describes what a plugin is and outlines the plugin infrastructure so
+      that you can start building your own Forrest extenstions.</p>
+    </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 Forrest's 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 Forrest's 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/sitemap.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
+      FORREST_INSTALL_DIR/plugins/sitemap.xmap file. This file is mounted
+      by the 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>

Mime
View raw message