Confluence 1.4 and later
- For more information about plugins in general, read Confluence Plugin Guide.
- To learn how to install and configure plugins (including macros), read Installing Add-ons.
- For an introduction to writing your own plugins, read Writing Confluence Plugins.
On this page:
The XWork Plugin Module
Each XWork module is deployed as a plugin module of type xwork and contains one of more XWork
Here is an example
atlassian-plugin.xml file containing a single XWork module:
- The xwork element has no class attribute.
- You can specify multiple package elements within the xwork element. These are standard XWork package elements, just as you would specify in xwork.xml.
- Ensure the
<result>entry appears on a single line with no spaces.
Writing an Action
For information on how to write a WebWork action, please consult the WebWork documentation.
WebWork actions must implement
com.opensymphony.xwork.Action. However, we recommend you make your action extend ConfluenceActionSupport, which provides a number of helper methods and components that are useful when writing an Action that works within Confluence.
Other action base-classes can be found within Confluence, but we recommend you don't use them - the hierarchy of action classes in Confluence is over-complicated, and likely to be simplified in the future in a way that will break your plugins.
Accessing Your Actions
Actions are added to the XWork core configuration within Confluence, which means they are accessed like any other action!
For example, given the above
livesearch action would be accessed at http://yourserver/confluence/plugins/livesearch/livesearch.action.
Creating a Velocity Template for Output
Your Velocity template must be specified with a leading slash (/) in the plugin XML configuration, and the path must correspond to the path inside the plugin JAR file.
In the above example, the Velocity template must be found in
/templates/extra/livesearch/livesearchaction.vm inside the plugin JAR file. In the example plugin's source code, this would mean the Velocity template should be created in
Inside your Velocity template, you can use
$action to refer to your action, and many other variables to access Confluence functionality. See Confluence Objects Accessible From Velocity for more information.
Some issues to be aware of when developing or configuring an XWork plugin:
- Your packages should always extend the
defaultConfluence package. It is useful to be aware of what this provides to you in the way of interceptors and result types. Extending any other package will modify that package's configuration across the entire application, which is not supported or desirable.
- You can give your packages any namespace you like, but we recommend using
/plugins/unique/value- that is prefixing plugin packages with
/pluginsand then adding a string globally unique to your plugin. The only name you can't use is
/plugins/servletURL pattern is reserved for Servlet Module.
- Views must be bundled in the JAR file in order to be used by your actions. This almost always means using Velocity views.
- It is useful to be aware of the actions and features already bundled with Confluence, for example your actions will all be auto-wired by Spring (see Accessing Confluence Components from Plugin Modules) and your actions can use useful interfaces like PageAware and SpaceAware to reduce the amount of work they need to do.
- Currently only WebWork Modules are protected by the temporary secure administrator sessions. Other plugin types, such as REST services or servlets are not checked for an administrator session.
All webwork modules mounted under
/adminwill automatically be protected by secure administrator sessions. To opt out of this protection you can mark your class or webwork action method with the WebSudoNotRequired annotation. Conversely, all webwork actions mounted outside the
/adminnamespace are not protected and can be opted in by adding the WebSudoRequired annotation.
Both of these annotations work on the class or the action method. If you mark a method with the annotation, only action invocations invoking that method will be affected by the annotations. If you annotate the class, any invocation to that class will be affected. Sub-classes inherit these annotations.
Important Security Note
If you are writing an XWork plugin, it is very important that you read this security information: XWork Plugin Complex Parameters and Security
The LiveSearch example is a neat example of an Ajax-style Confluence plugin which uses a bundled XWork module to do it's work:
Find this example in the
/plugins/macros/livesearch directory within your Confluence distribution.