An Atlassian plugin can specify one or more plugin modules to affect the underlying Atlassian applications. Plugin modules are elements you can add to your plugin and which will be translated by the SDK and the application architecture to something Confluence understands.
We already used the xhtml-macro and web-resource modules in our first plugin, but there are many more.
These are module types that are available in every application, not just Confluence. If you are building a plugin for multiple applications, stick to only these types.
Each Atlassian application has it own modules, as does Confluence. The following are the module types supported by Confluence:
|
Module type |
Description |
|---|---|
|
Adds new code languages to the | |
|
Adds a color scheme to a theme. | |
|
Adds a decorator (layout) to your add-on for usage without a theme. | |
|
Adds a renderer for a specified (mobile) device type. | |
|
Allows you to extract data and put this in the Confluence indexer. | |
|
Adds a repeatable job, like a scheduled service to Confluence. | |
|
Defines a new keyboard shortcut within Confluence. | |
|
Provides a new language translation to Confluence. | |
|
Adds a layout (decorator) to your add-on for usage with a theme. | |
|
Can be used to schedule tasks during application startup and shutdown. | |
|
A special component that will respond to certain events in Confluence. | |
|
Adds a new macro to the WYSIWYG editor. Should output HTML that can be embedded in a page. | |
|
Adds a SOAP service to Confluence. | |
|
Adds an XML-RPC service to Confluence. | |
|
Creates a new theme (look and feel) for Confluence or a single space. | |
|
Adds new actions and views to an add-on, enabling user interaction. |
The preceding list is pretty comprehensive and there is so much to choose from. In this section, I will explain in detail some plugin module types that you will almost certainly use in most of your plugins.
If you want to add an action or screen to Confluence, like a configuration screen, there are two options. The first is building a standard Java servlet, the second is making use of XWork/WebWork.
The syntax of an XWork module is as follows
<xwork name="plugin-actions" key="plugin-actions">
<package name="configure" extends="default"
namespace="/plugins/config">
<default-interceptor-ref name="defaultStack" />
<action name="alpha"
class="com.example.action.AlphaConfigAction"
method="view">
<result name="success"type="velocity">
/templates/alpha-config-action.vm
</result>
</action>
</package>
</xwork>
Let's go quickly over the XML to explain what we just defined:
<xwork name="plugin-actions" key="plugin-actions">
defines the XWork module, both the name and key attributes are for identification only.
<package name="configure" extends="default" namespace="/plugins/config">
Packages are used to group actions, and your XWork module can have more than one. name is the only required attribute and identifies the package. extends specifies if the package inherits behavior from other packages; in this case we use the Confluence default. With namespace, you can define under which URL the actions are available.
<action name="alpha" class="com.example.action.AlphaConfigAction" method="view">
The action element is the basic unit of work and defines an action, which in most cases is a URL. The name attribute completes the URL, as the preceding action is available at /plugins/config/alpha.action. An action always has a class, which will extend ConfluenceActionSupport. With method, it is possible to specify the method in the class responsible for this action.
<result name="success"type="velocity"> /templates/alpha-config-action.vm </result>
The result element will map the result of an action to a template. In the preceding example, the velocity template alpha-config-action.vm will be rendered if our AlphaConfigAction returns success.
Every action should have an implementation that extends the ConfluenceActionSupport class. Actions can use the same implementation if that makes sense for your plugin.
Our AlphaConfigAction class should look something like this:
public class AlphaConfigAction extends ConfluenceActionSupport {
public String view() {
if (condition == true) return SUCCESS;
return ERROR;
}
public String getViewMessage() {
return "Don't forget a towel";
}
}
Based on our action configuration, the method view() is called and based upon the return the success or error template is rendered.
This is of course a simple example, but you can do much more in this action class. The action class is also available in your template, so if you want to render certain information via that template, make sure there is a get method available, just like #getViewMessage().
Web Sections allows your plugin to add new sections to existing menus; each section can contain one or more links, which are defined as Web Items. We can use Web Sections to add a new section to the Confluence administration for our plugin configuration.
The syntax of a Web Section is as follows:
<web-section key="plugin-admin-section" location="system.admin" weight="1000"> <label key="plugin.menu.section" /> <condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.SystemAdministratorCondition" /> </web-section>
Let's break down this definition:
<web-section key="plugin-admin-section" location="system.admin" weight="1000">
A web-section element requires a key, which is a unique identifier for this component. location relates to the menu this section needs to be added to and the weight determines at which position it needs to be added to.
location menus can be difficult to find if you are not familiar with the source code of Confluence itself. More location menus are documented on https://developer.atlassian.com/display/CONFDEV/Web+UI+Modules. A few that are commonly used are:
|
Location |
Description |
|---|---|
|
|
The tabs above the user profile view. |
|
|
The drop-down menu when you click the user avatar in the top-right corner. |
|
|
The links in the left-hand side menu in the Administrator Console. |
The label element is the only required element in the web-section plugin. It looks up for the label in your plugin properties file and uses it in the menu section header.
<label key="plugin.menu.section" />
You can add one or more conditions to a web panel or item. The implementation of these conditions must return true in order for the section to display in the interface. This can be used the make sure the links are only available for administrators.
<condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.SystemAdministratorCondition" />
With Web Items you can add links to Confluence via your plugin. If you build a screen you probably want users to find it; adding a web items to your plugin should make this possible.
A common Web Item will be configured similar to this:
<web-item key="config-link" name="Plugin Configuration" section="system.admin/plugin-admin-section" weight="10"> <label key="plugin.menu.config" /> <linklinkId="config-link">/plugins/config/alpha.action</link> <icon height="16" width="16"> <link>/images/icons/config.gif</link> </icon> </web-item>
I'll explain this example a bit more in detail:
<web-item key="config-link" name="Plugin Configuration" section="system.admin/plugin-admin-section" weight="10">
The web-item attribute knows a section argument instead of a location, as Web Items must be placed in sections. In our example, I'm placing this Web Item in the section we have defined earlier.
<linklinkId="config-link">/plugins/config/alpha.action</link>
The link element will determine where the user will go after clicking on the menu item. The linkId argument is optional and will provide an HTML ID when rendered. The link can either be relative to the Confluence server or absolute, pointing to any website you wish.
<icon height="16" width="16"> <link>/images/icons/config.gif</link> </icon>
Web Items can contain icons that will be placed before the their label elements. The icon can have a width and a height attribute. The location of the image is defined by the link element.
Just like Web Sections can, Web Items can contain conditions to determine when a link is shown and to who.