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.
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.
How is a Plugin Installed?
If a site requires one or more plugins then the site designer will have named them in the project.required.plugins property in the projects forrest.properties file. When Forrest builds the site it will automatically discover the plugin and install it. In otherwords, the user need do nothing. For example,
project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org, org.apache.forrest.plugin.input.simplifiedDocbook
(note that that is all in one line with no spaces) will cause Forrest to load the plugins called "org.apache.forrest.plugin.input.OpenOffice.org" and "org.apache.forrest.plugin.input.simplifiedDocbook".
In the absence of a version number for the plugin (as is the case in the examples 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 shuld 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 avialable. 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.
By default a new forrest project includes plugins to generate PDF output from your source documents.
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 top 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.