Rate this page:
Available: | Confluence 8.5.3 and later |
This module was previously defined as xwork in Confluence versions prior to 8.5.3. The xwork module will continue to be supported for backward compatibility.
Struts plugin modules enable you to deploy Struts actions and views as a part of your plugins.
Additionally, the Struts module should also be used to define multipart request parsing rules. Ordinarily, multipart requests will only be parsed if the request is authorized according to the enforceSiteAccess
method in ConfluencePermissionEnforcer:
For endpoints that are intended to parse multipart requests outside the above access criteria, they can be allowlisted using the multipart-upload-allowlist
element within a Struts module.
The root element for the Struts plugin module is struts
. It does not accept a class attribute. It accepts the following child elements for configuration:
package
- standard Struts package definition, multiple permitted per module
namespace
attribute is subject to the following RegEx validation: [a-zA-Z0-9/\-]*
)action
- standard Struts action definition
name
attribute is subject to the following RegEx validation: [a-zA-Z0-9\-]*
)method
attribute is subject to the following RegEx validation: [a-zA-Z_]*[0-9]*
)multipart-upload-allowlist
- only 1 multipart-upload-allowlist element is permitted per Struts module
regex
- A RegEx pattern to match against the request URI (excluding the context path). It will parse multipart requests for any matching requests irrespective of the request's authorisation state.1 2<struts name="livesearchaction" key="livesearchaction"> <package name="livesearch" extends="default" namespace="/plugins/livesearch"> <default-interceptor-ref name="defaultStack" /> <action name="livesearch" class="com.atlassian.confluence.extra.livesearch.LiveSearchAction" method="doDefault"> <result name="success" type="velocity">/templates/extra/livesearch/livesearchaction.vm</result> </action> </package> <multipart-upload-allowlist> <regex>/admin/test\.action.*</regex> <regex>/plugins/livesearch/livesearch\.action.*</regex> </multipart-upload-allowlist> </struts>
Struts actions should 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.
Actions are added to the Struts core configuration within Confluence, which means they are accessed like any other action.
For example, given the above atlassian-plugin.xml
, the livesearch
action would be accessed at <host>/<context-path>/plugins/livesearch/livesearch.action
.
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 src/main/resources/template/extra/livesearch/
.
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.
If you are writing a Struts action, it is very important that you read this: Struts Complex Parameters and Security.
Some issues to be aware of when developing or configuring a Struts plugin:
default
Confluence 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./plugins/unique/value
- that is prefixing plugin packages with /plugins
and then adding a string globally unique to your plugin. The only name you can't use is servlet
as the /plugins/servlet
URL pattern is reserved for the Servlet Module./admin
will automatically be protected by secure administrator sessions. To opt out of this protection you can mark your class or Struts action method with the WebSudoNotRequired annotation./admin
namespace are not protected and can be opted in by adding the WebSudoRequired annotation.Rate this page: