Available Plugins Our available plugins page lists all the plugins that currently ship with blojsom.

Plugin API

Plugins allow developers to add to the capabilities of blojsom in a well-defined way. Plugins can be responsible for changing how an entry is displayed, adding or removing information to an entry, making information or objects available to the templates, etc. You are not limited to what you can do with plugins. In fact, the web-based administration console was developed as a series of plugins.

The blojsom plugin API was designed to be very straightforward. A developer that wants to write a plugin for blojsom will implement the BlojsomPlugin interface. This interface defines 4 methods that must be overridden:

• init(ServletConfig servletConfig, BlojsomConfiguration blojsomConfiguration): This method is called once when the plugin class is instantiated by blojsom. As a developer, you can retrieve any initialization parameters from web.xml.
• process(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse, BlogUser user, Map context, BlogEntry[] entries): After retrieving the blog entries for a request, blojsom will execute the plugins (their order is defined in the blojsom-plugin-chain property of the plugin.properties file). The process() method is where the plugin can manipulate the individual blog entries.
• cleanup(): The cleanup() method is called directly after the process method and is provided so that developers can perform any cleanup after processing a plugin request.
• destroy(): The destroy() method is called for each plugin when BlojsomServlet is taken out of service by the servlet container.

As a developer, you must ensure that any access to class member variables is thread-safe.

Also, if you are going to be adding any configuration parameters for your plugin to the web.xml file, then we ask that you use the "plugin-<plugin-name>" prefix. For example, the configuration parameter in web.xml for the macro expansion plugin to point to its configuration file is called plugin-macros-expansion.

If you are considering writing a plugin, take a look at the source code for any of the individual plugins.

Using blojsom plugins

General blojsom plugin configuration

The general blojsom plugin configuration file is stored in /WEB-INF/plugin.properties.

One of the initialization parameters defined in the web.xml for blojsom is called plugin-configuration and points to the plugin properties file for the application. Typically, this does not need to change from its value of plugin.properties. Looking at /WEB-INF/plugin.properties, you will see something like:

href-hyperlinks=org.blojsom.plugin.hyperlink.HyperlinkURLPlugin
macro-expansion=org.blojsom.plugin.macro.MacroExpansionPlugin
simple-search=org.blojsom.plugin.search.SimpleSearchPlugin

Each line in this file will follow the plugin-short-name=plugin.class.name convention. After blojsom starts up, it will try to instantiate each plugin defined in this file. After blojsom loads the plugin class, it will call its init() method and add it to the valid plugins. If there is an error loading a particular plugin, blojsom will log this and will make the plugin inactive, even if it is defined in the <flavor>.blojsom-plugin-chain.

Individual user plugin configuration

An individual blog's plugin configuration file is stored in /WEB-INF/(blog-id)/plugin.properties. The blog-id will change as appropriate.

In the individual blog directories, the plugin.properties file will only contain blojsom-plugin-chain references. The syntax for the value of the <flavor>.blojsom-plugin-chain property is a comma-separated list of the plugin-short-names in the order in which they should be executed for the particular flavor. So, if we wanted to execute the macro expansion plugin before the href hyperlinks plugin for the HTML flavor, we would set the value of this property to:

html.blojsom-plugin-chain=macro-expansion, href-hyperlinks

blojsom plugin execution

blojsom will still execute the plugins even if there are no blog entries retrieved for a given request. You do not need to explicitly test for entries == null at the beginning of the process method as this method is passed a BlogEntry[] array of length 0 if there were no blog entries retrieved for a particular request.

blojsom plugins override

You may override the plugins that get executed on a given request. The following table describes the URL parameters that affect the blojsom plugin chain.