Plugin Infrastructure

Delivered-To: mailing list svn@forrest.apache.org Received: (qmail 15300 invoked by uid 99); 10 Apr 2007 03:50:32 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 20:50:32 -0700 X-ASF-Spam-Status: No, hits=-99.5 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 09 Apr 2007 20:50:22 -0700 Received: by eris.apache.org (Postfix, from userid 65534) id 275E41A9885; Mon, 9 Apr 2007 20:49:06 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r527010 [22/26] - in /forrest/trunk/site-author/content: ./ skins/ xdocs/ xdocs/docs_0_70/ xdocs/docs_0_70/howto/ xdocs/docs_0_70/howto/bugzilla-patch/ xdocs/docs_0_70/howto/cvs-ssh/ xdocs/docs_0_70/howto/multi/ xdocs/docs_0_80/ xdocs/docs_... Date: Tue, 10 Apr 2007 03:48:57 -0000 To: svn@forrest.apache.org From: crossley@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20070410034906.275E41A9885@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml (original) +++ forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/pluginInfrastructure.xml Mon Apr 9 20:48:52 2007 @@ -16,41 +16,42 @@ limitations under the License. --> -

Overview -

Forrest can be extended 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 extensions.

+ Forrest can be extended 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 extensions. +

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

- -

The plugins sitemap is mounted by Forrest's sitemap after the project - specific sitemap but before the Forrest default matchers. This allows - a plugin to override/extend default Forrest behaviour. 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.

- +

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

+ The plugins sitemap is mounted by Forrest's sitemap after the project + specific sitemap but before the Forrest default matchers. This allows a + plugin to override/extend default Forrest behaviour. 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. +

Types of Plugin -

There are three types of plugin, input, - output and internal. Each plugin has a - specific role to play and extends a different part of Forrest:

- - +

+ There are three types of plugin, input, + output and internal. Each plugin has a + specific role to play and extends a different part of Forrest: +

+ internal plugins (site.xml, abs-linkmap etc.) | @@ -63,116 +64,124 @@ input plugin output plugin (**.xml) (**.html, **.pdf etc.) -

Input Plugins -

Input plugins provide a new source format. For example, the - OpenOffice.org plugin extends Forrest to allow the use of - OpenOffice.org Application file formats.

- -

An input plugin provides an input.xmap file. - This provides the source matchers (i.e. **.xml), it is - mounted in forrest.xmap before the default forrest **.xml behaviour - and therefore can override that default behaviour but it will not - interfere with any internal Forrest infrastructure matches, or any - other plugins infrastructure matches.

- -

An input plugin may also provide a resources.xmap - file. This can be used to match additional resources that are not - stored in XML files, for example, javascript files.

+ Input plugins provide a new source format. For example, the + OpenOffice.org plugin extends Forrest to allow the use of + OpenOffice.org Application file formats. +

+ An input plugin provides an input.xmap file. This + provides the source matchers (i.e. **.xml), it is mounted in + forrest.xmap before the default forrest **.xml behaviour and + therefore can override that default behaviour but it will not + interfere with any internal Forrest infrastructure matches, or any + other plugins infrastructure matches. +

+ An input plugin may also provide a resources.xmap file. + This can be used to match additional resources that are not stored + in XML files, for example, javascript files. +

Output Plugins - -

Output plugins provide a new output format. For example, the - s5 plugin extends Forrest to produce HTML slides from Forrest - documents.

- -

An output plugin provides an output.xmap file. - This provides the relevant output matchers (i.e. - **.html, **.pdf, **.slides), it is mounted before any of the default - matchers for Forrest and so can override this default behaviour.

+ Output plugins provide a new output format. For example, the s5 + plugin extends Forrest to produce HTML slides from Forrest + documents. +

+ An output plugin provides an output.xmap file. This + provides the relevant output matchers (i.e. **.html, **.pdf, + **.slides), it is mounted before any of the default matchers for + Forrest and so can override this default behaviour. +

Internal Plugins - -

Internal plugins are for advanced use only. They provide ways - of extending or overriding Forrest's - internal operations. For example, the IMSManifest plugin - allows Forrest projects to use an IMS Manifest file instead of - a site.xml and tabs.xml configuration files.

- -

Internal plugins provide an internal.xmap file. - This provides the infrastructure matchers (i.e. - site.xml, faq.xml, issues.xml), and will be mounted before - *any* of the Forrest matches. This sitemap can override any behaviour - within Forrest and so developers of these plugins must be especially - careful with the construction of their matchers, since they will be - processed before any other matchers and consequently can easily break - existing functionality. You must only do a <map:generate ...> - if you are certain you are going to process the full result.

+ Internal plugins are for advanced use only. They provide ways of + extending or overriding Forrest's internal operations. For example, + the IMSManifest plugin allows Forrest projects to use an IMS + Manifest file instead of a site.xml and tabs.xml configuration + files. +

+ Internal plugins provide an internal.xmap file. This + provides the infrastructure matchers (i.e. site.xml, faq.xml, + issues.xml), and will be mounted before *any* of the Forrest + matches. This sitemap can override any behaviour within Forrest and + so developers of these plugins must be especially careful with the + construction of their matchers, since they will be processed before + any other matchers and consequently can easily break existing + functionality. You must only do a <map:generate ...> if you + are certain you are going to process the full result. +

Naming Conventions -

Technically you can name a plugin anything you like with one - small restriction (see below). However, we - do have some naming conventions that we recomend you follow. This is - to minimise the chances of collision between plugins from different - developers.

- -

The name should be structured like a java package name, and should - include a relevant reverse domain name. For example:

- +

+ Technically you can name a plugin anything you like with one small + restriction (see below). However, we do have some naming conventions + that we recomend you follow. This is to minimise the chances of + collision between plugins from different developers. +

+ The name should be structured like a java package name, and should + include a relevant reverse domain name. For example: +

org.apache.forrest.plugin.PLUGIN_TYPE.PLUGIN_NAME net.sf.forrestPlugins.PLUGIN_TYPE.PLUGIN_NAME - -

Where PLUGIN_TYPE is either "internal", "input" or - "output" and PLUGIN_NAME" is a suitable name chosen by - yourself.

- - Plugin names cannot have a '-' character in them. This character - is used to indicate the start of a version number when defining a plugin - to be used. See Using Plugins for more - information. - +

+ Where PLUGIN_TYPE is either "internal", "input" or + "output" and PLUGIN_NAME" is a suitable name chosen by + yourself. +

+ + Plugin names cannot have a '-' character in them. This character is + used to indicate the start of a version number when defining a plugin + to be used. See Using Plugins for + more information. +

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 Forrest's 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.

+ 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 Forrest's 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:

- - +

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

+ [plugin_name] | |-- plugin control files (xmap etc.) @@ -191,15 +200,13 @@ | `-- stylesheets (XSLs etc.) - -

- The IMS Manifest Plugin - -

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

- - - +

+ The IMS Manifest Plugin +

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

+ org.apache.forrest.plugin.internal.IMSManifest | |-- sitemap.xmap @@ -213,12 +220,13 @@ |- 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:

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

+ + @@ -237,32 +245,34 @@ -]]> - - 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 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. + +

- -

- How does Installation work? -

- See the - Using Plugins - for an overview of how the plugin installation system works and the places and order - that will be searched. -

- -

When Forrest installs a plugin it downloads a zip of the plugin code and - extracts it into the plugins directory of Forrest and an entry is made - in a temporary sitemap that manages plugins for your content object. - For example, installing the - IMSManifest plugin described above will result in the following entry - being added to the this temporary sitemap:

- - + How does Installation work? +

+ See the Using Plugins for an overview + of how the plugin installation system works and the places and order + that will be searched. +

+ When Forrest installs a plugin it downloads a zip of the plugin code and + extracts it into the plugins directory of Forrest and an + entry is made in a temporary sitemap that manages plugins for your + content object. For example, installing the IMSManifest plugin described + above will result in the following entry being added to the this + temporary sitemap: +

+ + - ]]> - -

To be more accurate, the entries are made in one of three temporary - sitemaps, input.xmap, output.xmap and resources.xmap. These temporary - sitemaps are rebuilt each time the content object is built or run, thus - we are always guarenteed of having the right plugins installed.

- + ]]> + +

+ To be more accurate, the entries are made in one of three temporary + sitemaps, input.xmap, output.xmap and resources.xmap. These temporary + sitemaps are rebuilt each time the content object is built or run, thus + we are always guarenteed of having the right plugins installed. +

+ Further Reading +

+ If you want to build a plugin you might like to start with our + HowTo on Building Plugins. +

- -

- Further Reading -

If you want to build a plugin you might like to start with our - HowTo on Building Plugins.

Modified: forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml (original) +++ forrest/trunk/site-author/content/xdocs/pluginDocs/plugins_0_80/usingPlugins.xml Mon Apr 9 20:48:52 2007 @@ -16,118 +16,160 @@ limitations under the License. --> -

Extending Forrest with Plugins

Overview -

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.

- +

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

What plugins are available? -

You can run the command forrest available-plugins to get - a list of the known plugins for Forrest.

- -

If you would like to have your own plugin added to this list then - contact the developer mailing list.

+ You can run the command forrest available-plugins to get + a list of the known plugins for Forrest. +

+ If you would like to have your own plugin added to this list then + contact the developer mailing list. +

How is a Plugin Installed? -

- List of Plugins Needed by the Project -

If a site requires one or more plugins then the site designer will - have to list them in the project.required.plugins property - in the projects forrest.properties file. When Forrest - builds the site it will automatically discover the plugins and install - them. In otherwords, the user needs do nothing.

For example,

- project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook -

- will cause Forrest to load the plugins called "org.apache.forrest.plugin.input.OpenOffice.org" and - "org.apache.forrest.plugin.input.simplifiedDocbook".

- By default a new forrest project has that property configured - to include some plugins. Currently there is only one to generate - PDF output from your source documents. -

- What Version of Plugins will be used ? -

In the absence of a version number for the plugin (as is the case in the example above) - the most recent version that is applicabe to your release of Forrest will be used. This - may result in unexpected behaviour if a new version of the plugin has been released that - is incompatible with your current site. To force Forrest into using a specific version of - a plugin you should add "-VERSION_NUMBER" to the end of the plugin name. For example, - to force forrest to use the 1.0 version of the OpenOffice.org plugin you would use - org.apache.forrest.plugin.input.OpenOffice.org-1.0. If you define a version of the - plugin that does not exist then it will fall back to using the most recent version available. - This feature is useful when - developing a new site as you can quickly force a plugin upgrade by deleting all installed - plugins (use the command 'ant cleanPlugins'). However, this might result in the installation - of an in-development plugin, therefore in a production environment you should always specify - a known working version.

+ List of Plugins Needed by the Project +

+ If a site requires one or more plugins then the site designer will + have to list them in the project.required.plugins + property in the projects forrest.properties file. When + Forrest builds the site it will automatically discover the plugins and + install them. In otherwords, the user needs do nothing. +

+ For example, +

+ project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook +

+ will cause Forrest to load the plugins called + "org.apache.forrest.plugin.input.OpenOffice.org" and + "org.apache.forrest.plugin.input.simplifiedDocbook". +

+ + By default a new forrest project has that property configured to + include some plugins. Currently there is only one to generate PDF + output from your source documents. + +

+ What Version of Plugins will be used ? +

+ In the absence of a version number for the plugin (as is the case in + the example above) the most recent version that is applicabe to your + release of Forrest will be used. This may result in unexpected + behaviour if a new version of the plugin has been released that is + incompatible with your current site. To force Forrest into using a + specific version of a plugin you should add "-VERSION_NUMBER" to the + end of the plugin name. For example, to force forrest to use the 1.0 + version of the OpenOffice.org plugin you would use + org.apache.forrest.plugin.input.OpenOffice.org-1.0. If + you define a version of the plugin that does not exist then it will + fall back to using the most recent version available. This feature is + useful when developing a new site as you can quickly force a plugin + upgrade by deleting all installed plugins (use the command 'ant + cleanPlugins'). However, this might result in the installation of an + in-development plugin, therefore in a production environment you + should always specify a known working version. +

+ Where does Forrest look for Plugins sources? +

+ Overview +

+ This is fairly complex, so here is a simple overview. If you want to + know the details you need to read the rest of this section. For most + people this overview will be sufficient. +

+ Forrest will try and retrieve a plugin from local source files + first, if that fails it will look on a remote distribution server. + Once it finds a copy of the plugin it will deploy it to the local + Forrest instance and use it from there. +

+ The local directories that will be searched are defined in the + project.required.plugins.src property, which is defined + in the forrest.properties file. By default this is set + to + ${forrest.home}/plugins,${forrest.home}/whiteboard/plugins, + which means that these two directories will be searched for plugins. +

+ If you have a collection of local plugins you would like Forrest to + use then you need to add the directory to this property. For + example: + project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins +

+ You can add this line to your projects + forrest.properties file. However, it may be more + convenient to add it to a forrest.properties file in + your users home directory. +

- Where does Forrest look for Plugins sources? - -

- Overview - -

This is fairly complex, so here is a simple overview. If you want to know the - details you need to read the rest of this section. For most people this overview - will be sufficient.

- -

Forrest will try and retrieve a plugin from local source files first, if that - fails it will look on a remote distribution server. Once it finds a copy of the - plugin it will deploy it to the local Forrest instance and use it from there.

- -

The local directories that will be searched are defined in the project.required.plugins.src - property, which is defined in the forrest.properties file. By default - this is set to ${forrest.home}/plugins,${forrest.home}/whiteboard/plugins, - which means that these two directories will be searched for plugins.

- -

If you have a collection of local plugins you would like Forrest to use then you - need to add the directory to this property. For example: - project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins

- -

You can add this line to your projects forrest.properties file. However, - it may be more convenient to add it to a forrest.properties file - in your users home directory.

- -

Forrest uses a fall back mecanism to find the plugins to install for a project.

For an unversionned plugin, Forrest tries to get it from :

different local sources directories (project.required.plugins.src property)
if not found : the remote site in the forrest version directory
if not found : the remote site (with no forrest version directory)

For a versionned plugin, Forrest tries to get :

the versionned plugin from different local sources directories (project.required.plugins.src property)
if not found : the versionned plugin from the remote site in the forrest version directory
if not found : the unversionned plugin in different local sources directory (project.required.plugins.src property again)
if not found : the unversionned plugin from the remote site in the forrest version directory
if not found : the remote site (with no forrest version directory)

By default, forrest looks into the two following directories to find plugins sources : ${forrest.home}/plugins and ${forrest.home}/whiteboard/plugins. - It is possible to add other sources locations by specifying the project.required.plugins.src property - in the projects forrest.properties file.

For example,

- project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins -

- will add the project specific directory ${project.home}/plugins to the list of directories to search in.

If sources are not found, forrest will try to get them from the Web. Forrest knows the plugins description with plugins descriptors files - in which plugins are described as follows :

- + Forrest uses a fall back mecanism to find the plugins to install for a + project. +

+ For an unversionned plugin, Forrest tries to get it from : +

different local sources directories (project.required.plugins.src property)
if not found : the remote site in the forrest version directory
if not found : the remote site (with no forrest version directory)

+ For a versionned plugin, Forrest tries to get : +

the versionned plugin from different local sources directories (project.required.plugins.src property)
if not found : the versionned plugin from the remote site in the forrest version directory
if not found : the unversionned plugin in different local sources directory (project.required.plugins.src property again)
if not found : the unversionned plugin from the remote site in the forrest version directory
if not found : the remote site (with no forrest version directory)

+ By default, forrest looks into the two following directories to find + plugins sources : ${forrest.home}/plugins and + ${forrest.home}/whiteboard/plugins. It is possible to add + other sources locations by specifying the + project.required.plugins.src property in the projects + forrest.properties file. +

+ For example, +

+ project.required.plugins.src=${forrest.home}/plugins,${forrest.home}/whiteboard/plugins,/export/forrest_plugins +

+ will add the project specific directory + ${project.home}/plugins to the list of directories to + search in. +

+ If sources are not found, forrest will try to get them from the Web. + Forrest knows the plugins description with plugins + descriptors files in which plugins are described as follows : +

+ + 0.8 -]]> -

The url to download the different plugins is indicated in this file.

By default, forrest gets the two following plugins descriptors files : http://forrest.apache.org/plugins/plugins.xml and http://forrest.apache.org/plugins/whiteboard-plugins.xml. - It is possible to add other plugins descriptors files by specifying the forrest.plugins.descriptors property - in the projects forrest.properties file.

For example,

- forrest.plugins.descriptors=http://forrest.apache.org/plugins/plugins.xml,http://forrest.apache.org/plugins/whiteboard-plugins.xml,file:///${project.home}/plugins/plugins.xml -

- will add the project specific plugins descriptors file file:///${project.home}/plugins/plugins.xml to the list of descriptors.

+]]> + +

+ The url to download the different plugins is indicated in this file. +

+ By default, forrest gets the two following plugins descriptors files : + http://forrest.apache.org/plugins/plugins.xml and + http://forrest.apache.org/plugins/whiteboard-plugins.xml. + It is possible to add other plugins descriptors files by specifying + the forrest.plugins.descriptors property in the projects + forrest.properties file. +

+ For example, +

+ forrest.plugins.descriptors=http://forrest.apache.org/plugins/plugins.xml,http://forrest.apache.org/plugins/whiteboard-plugins.xml,file:///${project.home}/plugins/plugins.xml +

+ will add the project specific plugins descriptors file + file:///${project.home}/plugins/plugins.xml to the list + of descriptors. +

Editing plugins sources to enhance functionality - - Until issue FOR-388 is fixed to - enable the use of plugins in-place, any change to sources requires you to either - restart forrest or to manually deploy the plugin locally with "ant local-deploy". - See Further reading for "How to build a Plugin". It is worth noting that if your - changes are to Java files you will always have to restart Forrest to ensure the - class loader loads your new classes. - -

If you need to add specific behaviour to an existing plugin, you should first consider - whether your changes will be of use to all users of the plugin or not. If they are of - general use then you can edit the plugin source files in their original location (i.e. - not in the build directory). Once you have completed your changes please - prepare a patch - and submit it for inclusion in code base.

- -

If your changes are specific to your own use of the plugin you can create a local - copy of the plugin for this. However, we strongly advise against this - since you will need to manually update your plugin each time a new release of the original - is made. In the vast majority of cases local enhancements to a plugin wil be of use - to the wider communtiy. Please donate back to the project and help keep it vibrant and - useful. See the Further Reading section at the end of this document for links to - documents with more information.

+ + Until issue + FOR-388 is + fixed to enable the use of plugins in-place, any change to sources + requires you to either restart forrest or to manually deploy the plugin + locally with "ant local-deploy". See Further reading for "How to build a + Plugin". It is worth noting that if your changes are to Java files you + will always have to restart Forrest to ensure the class loader loads + your new classes. + +

+ If you need to add specific behaviour to an existing plugin, you should + first consider whether your changes will be of use to all users of the + plugin or not. If they are of general use then you can edit the plugin + source files in their original location (i.e. not in the build + directory). Once you have completed your changes please + prepare a patch and submit it for + inclusion in code base. +

+ If your changes are specific to your own use of the plugin you can + create a local copy of the plugin for this. However, we strongly advise + against this since you will need to manually update your plugin each + time a new release of the original is made. In the vast majority of + cases local enhancements to a plugin wil be of use to the wider + communtiy. Please donate back to the project and help keep it vibrant + and useful. See the Further Reading section at the end of this document + for links to documents with more information. +

Upgrading from a Version of Forrest Without Plugins -

The plugin functionality was introduced in version 0.7 of Forrest. - At this time some of the functionality previously in Forrest was - extracted into a plugin. However, we have not broken backward - compatability with earlier versions. In the absence of a - project.required.plugins property in the projects - forrest.properties file all plugins that contain - functionality previously part of Forrest itself will be loaded - automatically. Unless you intend to use new functionality provided - by a plugin you will not need to make any changes to your project.

- -

If you do require additional plugin functionality, be sure to - include all required plugins in the - project.required.plugins property in the project's - forrest.properties. You can view - main/webapp/default-forrest.properties - to see the names of plugins that provide previously core - functionality.

- -

It is also worth noting that there is a small performance - improvement if you remove plugins that are not in use. Therefore, - if you do not use one or more of the plugins named in the - project.required.plugins property of - main/webapp/default-forrest.properties - it is recomended that you override this value in your project's - forrest.properties file.

+ The plugin functionality was introduced in version 0.7 of Forrest. At + this time some of the functionality previously in Forrest was extracted + into a plugin. However, we have not broken backward compatability with + earlier versions. In the absence of a + project.required.plugins property in the projects + forrest.properties file all plugins that contain + functionality previously part of Forrest itself will be loaded + automatically. Unless you intend to use new functionality provided by a + plugin you will not need to make any changes to your project. +

+ If you do require additional plugin functionality, be sure to include + all required plugins in the project.required.plugins + property in the project's forrest.properties. You can view + main/webapp/default-forrest.properties to see the names of + plugins that provide previously core functionality. +

+ It is also worth noting that there is a small performance improvement if + you remove plugins that are not in use. Therefore, if you do not use one + or more of the plugins named in the + project.required.plugins property of + main/webapp/default-forrest.properties it is recomended + that you override this value in your project's + forrest.properties file. +

Avoiding Plugin Conflicts -

Clashes between plugins can occur. For example, the simplified-docbook - and full docbook plugins may try and process the same files. In this - instance the one that is mounted first will take precedence. Plugins - are mounted in the order they appear in the - project.required.plugins property, therefore the mounting - order and therefore processing precedence is under user control.

+ Clashes between plugins can occur. For example, the simplified-docbook + and full docbook plugins may try and process the same files. In this + instance the one that is mounted first will take precedence. Plugins are + mounted in the order they appear in the + project.required.plugins property, therefore the mounting + order and therefore processing precedence is under user control. +