Apache Struts 2 Documentation > Home > Guides > Plugin Guide |

Apache Struts 2 Documentation
Plugin Guide
Edit Page Browse Space Add Page Add News
Added by Patrick Lightbody, last edited by Don Brown on Dec 29, 2006 (view change)

| Struts 1 provided a plugin class that provided listener-like capabilities. The Struts 2 plugins are like Eclipse or FireFox plugins, and not at all like Struts 1 "plugins".

A Struts 2 plugin is a single JAR that class and/or configuration that extend, replace, or add to existing Struts framework functionality. A plugin can be installed by adding a JAR file to the application's class path. To configure the plugin, the JAR may contain a
`struts-plugin.xml`, which follows the same format as an ordinary `struts.xml` file.

Since a plugin can contain the `struts-plugin.xml` file, it has the ability to:

- Define new packages with results, interceptors, and/or actions
- Override framework constants
- Introduce new extension point implementation classes

Many popular but optional features of the framework are distributed as plugins. An application can retain all the plugins provided with the distribution, or just include the ones it uses. Plugins can be used to organize application code or to distribute code to third-parties.

| Plugins are not loaded in any particular order. Plugins should not have dependencies on each other. A plugins may depend on classes provided by Struts Core, but it should not depend on classes loaded by another plugin.

The framework loads its default configuration first, then any plugin configuration files found in others JARs on the classpath, and finally the "bootstrap" `struts.xml`.

1. `struts-default.xml` (bundled in the Core JAR)
2. `struts-plugin.xml` (as many as can be found in other JARs)
3. `struts.xml` (provided by the application)

Since the `struts.xml` file is always loaded last, it can make use of any resources provided by the plugins bundled with the distribution, or any other plugins available to an application.

## Extension Points

Extension points allow a plugin to override a key class in the Struts framework with an alternate implemention. For example, a plugin could provide a new class to create Action classes or map requests to Actions.

The following extension points are available in Struts 2:

Type | Property | Scope | Description
--- | --- | --- | ---
com.opensymphony.xwork2.ObjectFactory | struts.objectFactory | singleton | Creates actions, results, and interceptors
com.opensymphony.xwork2.ActionProxyFactory | struts.actionProxyFactory | singleton | Creates the ActionProxy
com.opensymphony.xwork2.util.ObjectTypeDeterminer | struts.objectTypeDeterminer | singleton | Determines what the key and and element class of a Map or Collection should be
org.apache.struts2.dispatcher.mapper.ActionMapper | struts.mapper.class | singleton | Determines the ActionMapping from a request and a URI from an ActionMapping
org.apache.struts2.dispatcher.multipart.MultiPartRequest | struts.multipart.parser | per request | Parses a multipart request (file upload)
org.apache.struts2.views.freemarker.FreemarkerManager | struts.freemarker.manager.classname | singleton | Loads and processes Freemarker templates
org.apache.struts2.views.velocity.VelocityManager | struts.velocity.manager.classname | singleton | Loads and processes Velocity templates

## Plugin Examples

Let's look at two similar but different plugins bundled with the core distribution.

### Sitemesh plugin

SiteMesh is a popular alternative to Tiles. SiteMesh provides a common look-and-feel to an application's pages by automatically wrapping a plain page with common elements like headers and menubars.

The `sitemesh-plugin.jar` contains several classes, a standard JAR manifest, and a plugin configuration file.

    + META-INF/
       + manifest.mf
     + org
       + apache
         + struts2
           + sitemesh
             + FreeMarkerPageFilter.class
             + TemplatePageFilter.class
             + VelocityPageFilter.class
     + struts-plugin.xml

While the SiteMesh Plugin doesn't provide any new results, interceptors, or actions, or even extend any Struts integration points, it does need to know what settings have been enabled in the Struts framework. Therefore, its `struts-plugin.xml` looks like this:

    <?xml version="1.0" encoding="UTF-8" ?>

    <!DOCTYPE struts PUBLIC
        "-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
        "http://struts.apache.org/dtds/struts-2.0.dtd">

    <struts>
        <bean class="org.apache.struts2.sitemesh.FreeMarkerPageFilter" static="true" optional="true"/>
        <bean class="org.apache.struts2.sitemesh.VelocityPageFilter" static="true" optional="true"/>
    </struts>

The two bean elements, with the "static" flag enabled, tell Struts to inject the current settings and framework objects into static property setters on startup. This allows, for example, the FreeMarkerPageFilter class to get an instance of the Struts FreemarkerManager and the current encoding setting.

### Tiles plugin

Tiles is a popular alternative to SiteMesh. Tiles provides a common look-and-feel to an application's pages by breaking the page down into common fragments or "tiles".

The `tiles-plugin.jar` contains several classes, a standard JAR manifest, and a configuration file.

    + META-INF/
       + manifest.mf
     + org
       + apache
         + struts2
           + tiles
             + StrutsTilesListener.class
             + StrutsTileUtilImpl.class
           + views
             + tiles
               + TilesResult.class
       + struts-plugin.xml

Since the Tiles Plugin does need to register configuration elements, a result class, it provides a `struts-plugin.xml` file.

## Bundled Plugins

Several plugins are available that extend the framework's capabilities.

Codebehind Plugin Config Browser JasperReports Plugin JFreechart Plugin JSF QuickStart | SiteGraph SiteMesh Plugin Struts1 Plugin Tiles Plugin Pell-multipart Plugin Plexus Plugin

### IDE Plugins

- Eclipse
- IntelliJ (whiteboard)

## Back to Home

Children Show Children Hide Children
JavaServer Faces (Apache Struts 2 Documentation)
Tiles (Apache Struts 2 Documentation)
Pico (Apache Struts 2 Documentation)
SiteMesh Plugin (Apache Struts 2 Documentation)
JFreeChart Plugin (Apache Struts 2 Documentation)
Codebehind Plugin (Apache Struts 2 Documentation)