or
absolute
optional
http://
https://
The body of the link element is its URL. The URL is rendered with Velocity, so you can include dynamic information in the link. For example,
in Confluence, the following link would include the page ID:
Icon Elements
Icon elements have a
and a
attribute. The location of the icon is specified within a
element:
height
width
link
Param Elements
Param elements represent a map of key/value pairs, where each entry corresponds to the param elements attribute:
and
name
value
respectively.
The value can be retrieved from within the Velocity view with the following code, where $item is a
:
WebItemModuleDescriptor
If the
attribute is not specified, the value will be set to the body of the element. I.e. the following two param elements are equivalent:
value
Context-provider Element
Available:
Atlassian Plugins 2.5, Confluence 2.5, Bamboo 3.0, JIRA 4.2 and later
The context-provider element adds to the Velocity context available to the
and
modules. You can add what you need to
web section
web item
the context, to build more flexible section and item elements. Currently only one context-provider can be specified per module. Additional
context-providers are ignored.
The
element must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
context-provider
must implement
, and
com.atlassian.plugin.web.ContextProvider
will be auto-wired by Spring before any additions to the Velocity context.
For example, the following context-provider will add
and
to the context.
historyWindowHeight
filtersWindowHeight
In the following example,
extends
, which is only available in JIRA and
HeightContextProvider
AbstractJiraContextProvider
happens to implement
. The
conveniently extracts the
and
from
ContextProvider
AbstractJiraContextProvider
User
JiraHelper
the context map, which you would otherwise have to do manually.
The above
can be used by nesting the following element in a web item module.
HeightContextProvider
The newly added context entries
and
can be used in the XML module descriptors just
historyWindowHeight
filtersWindowHeight
like normal velocity context variables, by prefixing them with the dollar symbol ($):
Condition and Conditions Elements
Conditions can be added to the
,
and
modules, to display them only when
the given conditions are true.
web section
web item
web panel
all
Condition elements must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
must implement
, and
com.atlassian.plugin.web.Condition
will be auto-wired by Spring before any condition checks are performed.
Condition elements can take optional parameters. These parameters will be passed in to the condition's
method as a map of string
init()
key/value pairs after autowiring, but before any condition checks are performed. For example:
To invert a condition, add the attribute 'invert="true"' to the condition element. This is useful where you want to show the section if a certain
condition is
satisfied.
not
Conditions elements are composed of a collection of condition/conditions elements and a type attribute. The type attribute defines what
logical operator is used to evaluate its collection of condition elements. The type can be one of
or
.
AND
OR
For example: The following condition is true if the current user is a system administrator OR a project administrator:
Example
Here is an example
file containing a single web item:
atlassian-plugin.xml
RELATED TOPICS
Plugin Module Types
Web Panel Plugin Module
Available:
, Confluence 2.5, Bamboo 3.0, JIRA 4.4 and later.
Atlassian Plugin Framework 2.5
On this page:
Purpose of this Module Type
Configuration
Attributes
Elements
Resource Element
Context-provider Element
Condition and Conditions Elements
Web Panel Examples
Application-Specific Locations
Purpose of this Module Type
Web Panel plugin modules allow plugins to define panels, or sections, on an HTML page. A panel is a set of HTML that will be inserted into a
page.
Configuration
The root element for the Web Panel plugin module is
. It allows the following attributes and child elements for configuration:
web-panel
Attributes
Name
Required
Description
Default
class
 
The class which implements this plugin module and which is responsible for providing the web
panel's HTML. In most cases you will not need to provide a custom class to generate the content,
as you can simply point to a static HTML file or a (Velocity) template. See the plugin framework
guide to
. If you omit this attribute, you MUST provide a resource
creating plugin module instances
element and vice versa, to ensure there is always exactly one source for the web panel's content.
 
disabled
 
Indicate whether the plugin module should be disabled by default (value='true') or enabled by
default (value='false').
false
i18n-name-key
 
The localisation key for the human-readable name of the plugin module.
 
key
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the
. A module with key
in a plugin with key
will
complete module key
fred
com.example.modules
have a complete key of
.
com.example.modules:fred
N/A
name
 
The human-readable name of the plugin module. Used only in the plugin's administrative user
interface.
 
system
 
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false').
Only available for non-OSGi plugins.
false
weight
 
Determines the order in which web panels appear. Web panels are displayed top to bottom or left
to right in order of ascending weight. The 'lightest' weight is displayed first, the 'heaviest' weights
sink to the bottom. The weights for most applications' system sections start from 100, and the
weights for the links generally start from 10. The weight is incremented by 10 for each in sequence
so that there is ample space to insert your own panels.
1000
location
The location in the host application where the web panel must be rendered. Note that every host
application declares its own set of web panel plugin points. Currently a web panel can only be
associated with a single location.
 
Elements
The table summarises the elements. The sections below contain further information.
Name
Required
Description
Default
condition
 
Defines a condition that must be satisfied for the web panel to be displayed. If you want to 'invert'
a condition, add an attribute 'invert="true"' to it. The web item will then be displayed if the condition
returns false (not true).
N/A
conditions
 
Defines the logical operator type to evaluate its condition elements. By default 'AND' will be used.
AND
context-provider
 
Allows dynamic addition to the Velocity context available for various web panel elements (in XML
descriptors only). Currently only one context-provider can be specified per web panel.
 
label
Is the i18n key that will be used to look up the textual representation of the link.
N/A
param
 
Parameters for the plugin module. Use the 'key' attribute to declare the parameter key, then
specify the value in either the 'value' attribute or the element body. This element may be repeated.
An example is the configuration link described in
. This is
Adding a Configuration UI for your Plugin
handy if you want to use additional custom values from the UI.
N/A
description
 
The description of the plugin module. The 'key' attribute can be specified to declare a localisation
key for the value instead of text in the element body. I.e. the description of the web panel.
 
resource
 
A resource element is used to provide a web panel with content. It can be used in a way similar to
, using the resource's location attribute to point to a static HTML file or (Velocity)
normal resources
template file that is provided by the plugin's JAR file. To differentiate between static HTML and
Velocity templates that need to be rendered, always specify the
attribute. See the examples
type
further down on this page. It is also possible to embed the contents (both static HTML or velocity)
directly in the
file by encoding it in the resource element's body and
atlassian-plugin.xml
then omitting the
attribute. Note that if you omit the resource element you MUST
location
provide the module descriptor's
attribute, and vice versa, to ensure there is always exactly
class
one source for the web panel's content.
N/A
Condition and Conditions Elements
Conditions can be added to the
,
and
modules, to display them only when
the given conditions are true.
web section
web item
web panel
all
Condition elements must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
must implement
, and
com.atlassian.plugin.web.Condition
will be auto-wired by Spring before any condition checks are performed.
Condition elements can take optional parameters. These parameters will be passed in to the condition's
method as a map of string
init()
key/value pairs after autowiring, but before any condition checks are performed. For example:
To invert a condition, add the attribute 'invert="true"' to the condition element. This is useful where you want to show the section if a certain
condition is
satisfied.
not
Conditions elements are composed of a collection of condition/conditions elements and a type attribute. The type attribute defines what
logical operator is used to evaluate its collection of condition elements. The type can be one of
or
.
AND
OR
For example: The following condition is true if the current user is a system administrator OR a project administrator:
Context-provider Element
Available:
Atlassian Plugins 2.5, Confluence 2.5, Bamboo 3.0, JIRA 4.2 and later
The context-provider element adds to the Velocity context available to the
and
modules. You can add what you need to
web section
web item
the context, to build more flexible section and item elements. Currently only one context-provider can be specified per module. Additional
context-providers are ignored.
The
element must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
context-provider
must implement
, and
com.atlassian.plugin.web.ContextProvider
will be auto-wired by Spring before any additions to the Velocity context.
For example, the following context-provider will add
and
to the context.
historyWindowHeight
filtersWindowHeight
In the following example,
extends
, which is only available in JIRA and
HeightContextProvider
AbstractJiraContextProvider
happens to implement
. The
conveniently extracts the
and
from
ContextProvider
AbstractJiraContextProvider
User
JiraHelper
the context map, which you would otherwise have to do manually.
The above
can be used by nesting the following element in a web item module.
HeightContextProvider
The newly added context entries
and
can be used in the XML module descriptors just
historyWindowHeight
filtersWindowHeight
like normal velocity context variables, by prefixing them with the dollar symbol ($):
Label Elements
Label elements may contain optional parameters, as shown below:
The parameters allow you to insert values into the label using Java's
syntax.
MessageFormat
Parameter names must start with
and will be mapped in
to the substitutions in the format string. I.e.
param
alphabetical order
param0 is {0}, param1 is {1}, param2 is {2}, etc.
Parameter values are rendered using Velocity, allowing you to include dynamic content.
Param Elements
Param elements represent a map of key/value pairs, where each entry corresponds to the param elements attribute:
and
name
value
respectively.
The value can be retrieved from within the Velocity view with the following code, where $item is a
:
WebItemModuleDescriptor
If the
attribute is not specified, the value will be set to the body of the element. I.e. the following two param elements are equivalent:
value
Resource Element
Unless the module descriptor's
attribute is specified, a web panel will contain a single resource child element that contains the
class
contents of the web panel. This can be plain HTML, or a (Velocity) template to provide dynamic content.
A web panel's resource element can either contain its contents embedded in the resource element itself, as part of the
file, or it can link to a file on the classpath when the
attribute is used.
atlassian-plugin.xml
location
A resource element's
attribute identifies the format of the panel's content (currently "
" and "
" are provided by Atlassian
type
static
velocity
Plugin Framework 2.5.0 and atlassian-template-renderer 2.5.0 respectively) which allows the plugin framework to use the appropriate
.
com.atlassian.plugin.web.renderer.WebPanelRenderer
Type
Description
static
Used to indicate that the web panel's contents must not be processed, but included in the page as is.
velocity
Used to indicate that the web panel contains
that needs to be parsed.
Velocity markup
The template rendering system is extensible. You can add custom renderers by creating plugins. For more information on this, check out the
.
Web Panel Renderer Plugin Module
Web Panel Examples
The values of the
attributes in the examples below are not real. They are just illustrative of the kind of location that
location
Confluence, Bamboo and FishEye make available.
A web panel that contains static, embedded HTML:
A web panel that contains an embedded Velocity template:
A web panel containing a Velocity template that is on the classpath (part of the plugin's JAR file):
As mentioned previously, it is also possible to provide your own custom class that is responsible for producing the panel's HTML, by using
the descriptor's class attribute (which makes the resource element redundant):
Note that
MUST implement
.
com.example.FooWebPanel
WebPanel
Application-Specific Locations
Each host application declares its own set of locations where the web panel can be rendered. Please refer to the documentation for each
application:
Confluence:
Web Panel Plugin Module
JIRA:
Web Panel Plugin Module
RELATED TOPICS
Web Panel Renderer Plugin Module
Plugin Module Types
Web Panel Renderer Plugin Module
Available:
and later.
Atlassian Plugin Framework 2.5
On this page:
1.
2.
3.
4.
Purpose of this Module Type
Configuration
Attributes
Writing a Custom Renderer
Known Limitations
Source Code
Purpose of this Module Type
The Web Panel Renderer plugin module allows plugins to define custom renderer engines for
. (Web panels are bits of HTML that
web panels
will be inserted into a page.)
Configuration
The root element for the Web Panel Renderer plugin module is
. It allows the following attributes and child elements
web-panel-renderer
for configuration:
Attributes
Name
Required
Description
Default
class
The class which implements
. This class is
com.atlassian.plugin.web.renderer.WebPanelRenderer
responsible for turning a web panel's content into proper HTML. See the plugin framework guide to
.
creating plugin module instances
 
disabled
 
Indicate whether the plugin module should be disabled by default (value='true') or enabled by
default (value='false').
false
i18n-name-key
 
The localisation key for the human-readable name of the plugin module.
 
key
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the
. A module with key
in a plugin with key
will
complete module key
fred
com.example.modules
have a complete key of
.
com.example.modules:fred
N/A
name
 
The human-readable name of the plugin module. Used only in the plugin's administrative user
interface.
 
system
 
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false').
Only available for non-OSGi plugins.
false
Writing a Custom Renderer
To create your own renderer you should create a class that implements
.
com.atlassian.plugin.web.renderer.WebPanelRenderer
As an example we will create a plugin for the
(version 2.5.0 or higher). We will create a web panel template
Atlassian Reference Application
renderer for
, which is a format that is not supported by the Atlassian Plugin Framework out of the box. We will then
FreeMarker templates
also add a web panel that uses a FreeMarker template.
Using the
, create a new plugin for the Reference Application and make sure the generated
file uses
Atlassian Plugin SDK
pom.xml
version 2.5.0 or higher:
$ atlas-create-refapp-plugin
Add the FreeMarker library to the Maven dependencies:
pom.xml
Create your renderer class:
Note how the
interface declares two render methods: one that takes the name of a template file and one that
WebPanelRenderer
takes the whole template as a String. In this example we have only implemented the former method. The latter is left as an exercise
for you. The consequence of this is that we will not be able to embed our FreeMarker content in
.
atlassian-plugin.xml
Add the new renderer to
:
atlassian-plugin.xml
4.
5.
6.
7.
8.
atlassian-plugin.xml
Add a web panel to the Reference Application's administration page that uses this new renderer:
atlassian-plugin.xml
Add your FreeMarker template:
src/main/resources/templates/mytemplate.ftl
Start up the Reference Application using the command:
)
$ atlas-mvn refapp:run
Go to:
http://localhost:5990/refapp/admin
Known Limitations
You may have noticed how the configuration for our FreeMarker's template loader uses a
freemarker.cache.ClassTemplateLoader
instance which expects templates to be on the classpath. To do this, FreeMarker's
constructor takes a
ClassTemplateLoader
Class
instance and then calls
when it needs to load a template.
Class.getResource()
In our example we use
, which means that our renderer is limited to rendering templates that live
FreeMarkerWebPanelRenderer.class
in its own plugin JAR file. This is sufficient for this tutorial which has the renderer, the web panel and the template all in the same plugin.
However, it would not work when the renderer is shared with other plugins and needs to render a template that lives in another plugin JAR.
If you want to build a shared FreeMarker renderer this way, you would have to implement your own
. Instead of taking a
instance, your template loader would take the
that is
freemarker.cache.TemplateLoader
Class
ClassLoader
returned by
.
plugin.getClassLoader()
To keep the example clear and simple, we have chosen to accept this limitation. However, note that it has been addressed properly in the full
source code that is available below.
Source Code
To access the full source code for this plugin, you can:
browse it online
.
check it out from Subversion
.
RELATED TOPICS
Web Panel Plugin Module
Plugin Module Types
Web Resource Plugin Module
Available:
Atlassian Plugin Framework 1.x and later.
Changed:
became available in
and later. Before that they were
Web resource contexts
Atlassian Plugin Framework 2.5
available in Confluence only, in Confluence 2.10 and later.
became available in
and later.
Web resource transformers
Atlassian Plugin Framework 2.5
became available in Atlassian Plugin Framework 2.7 and later.
Web resource conditions
On this page:
Purpose of this Module Type
Configuration
Attributes
Elements
Example
Referring to Web Resources
Web Resource Contexts
Batched Mode
Non-Batched Mode
Transforming Web Resources
Notes
Purpose of this Module Type
Web Resource plugin modules allow plugins to define downloadable resources. If your plugin requires the application to serve additional
static Javascript or CSS files, you will need to use downloadable web resources to make them available. Web resources are added at the top
of the page in the header with the cache-related headers set to never expire. In addition, you can specify web resources like CSS and
JavaScript to be included in specific contexts within the application.
Configuration
The root element for the Web Resource plugin module is
. It allows the following attributes and child elements for
web-resource
configuration:
Attributes
Name
Required
Description
Default
class
 
The class which implements this plugin module. The class you need to provide depends on the
module type. For example, Confluence theme, layout and colour-scheme modules can use classes
already provided in Confluence. So you can write a theme-plugin without any Java code. But for
macro and listener modules you need to write your own implementing class and include it in your
plugin. See the plugin framework guide to
.
creating plugin module instances
 
disabled
 
Indicate whether the plugin module should be disabled by default (value='true') or enabled by
default (value='false').
false
i18n-name-key
 
The localisation key for the human-readable name of the plugin module.
 
key
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the
. A module with key
in a plugin with key
will
complete module key
fred
com.example.modules
have a complete key of
. I.e. the identifier of the web resource.
com.example.modules:fred
N/A
name
 
The human-readable name of the plugin module. I.e. the human-readable name of the web
resource.
The
plugin
key
system
 
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false').
Only available for non-OSGi plugins.
false
Elements
Name
Required
Description
Default
description
 
The description of the plugin module. The 'key' attribute can be specified to declare a localisation
key for the value instead of text in the element body. I.e. the description of the resource.
 
resource
A resource for this plugin module. This element may be repeated. A 'resource' is a non-Java file that
a plugin may need in order to operate. Refer to
for details on
Adding Plugin and Module Resources
defining a resource.Currently, supported file types are .css and .js.
For web resources, the
attribute must be 'download'.
type
N/A
dependency
 
Dependencies for the web resource module. A web resource can depend on other web resource(s)
to be available. Dependencies are defined in the format 'pluginKey:webResourceKey' e.g.
<dependency>com.atlassian.auiplugin:ajs</dependency>
Note: This element is only available in
and later.
Plugin Framework 2.2
N/A
context
 
Use this element to include web resources like CSS and JavaScript on all screens of a specific type
in the application. See below.
Note: This element is only available in
and later.
Plugin Framework 2.5
 
transformation
 
Use this element to make a particular transformer available to the web resource in the plugin.
Example:
For a complete description, please refer to the page on
Web Resource Transformer Plugin Modules
.
Note: This element is only available in
and later.
Plugin Framework 2.5
 
condition
 
Use this element to define when this web resource should display or not.  See
Web Item Conditions
for more information.
Note: This element is only available in Plugin Framework 2.7 or later.
 
Example
Here is an example
file containing a single web resource:
atlassian-plugin.xml
Referring to Web Resources
In your plugin, you need to refer to a
and call the
method. The reference to
WebResourceManager
requireResource()
can be injected into your constructor:
WebResourceManager
Web Resource Contexts
In
and later of the Plugin Framework, you can automatically include web resources like CSS and JavaScript on all screens of a
version 2.5
specific type in the application. These are called 'web resource contexts'. The currently available contexts are:
Context
Description
atl.general
Everywhere except administration screens
atl.admin
Administration screens. Use with care because poorly formed CSS or JavaScript can prevent access to administering the
application.
atl.userprofile
User profile screens.
atl.popup
Browser pop-up windows. This will open a new window for things like OAuth authorisation, and similar purposes.
The above contexts are applicable to all Atlassian applications. In addition to these application-independent contexts, each Atlassian
application can also supply its own application-specific contexts.  
Example:
To configure your web resource to be included in every page (both administration and non-administration pages), add
<context>
child elements to your
element in your
:
<web-resource>
atlassian-plugin.xml
Using web resource contexts allows you to provide plugins that dynamically create HTML using JavaScript on any page in the application.
For example, the Confluence
includes a snippet of JavaScript on every page in the application, which listens for a
Content Navigation Plugin
particular keyboard shortcut to open a little search box on top the Confluence UI.
Introducing new contexts
If your plugin adds a number of screens to the application, you may find it useful to introduce a new web resource context for your plugin that
your plugin web resources (or any other plugin web resource) can hook into, to be automatically included on these screens.
To introduce a new context in your plugin Velocity templates, you can call the
method on the
requireResourcesForContext()
object from your Velocity templates:
WebResourceManager
This will include any resource in the page that specifies a context like this in its definition:
.
<context>com.acme.plugin.fancy-context</context>
We recommend that you namespace your new contexts in this way so as not to clash with any future contexts in the applications themselves
or in other plugins.
Batched Mode
The default mode for serving web resources in Plugin Framework 2.2 is batched mode. Batched mode refers to the serving of multiple plugin
resources (of the same type) in one request. For example, the two scriptaculous web resources defined above would be served in one
request, containing both scriptaculous.js and effects.js. Hence, batching reduces the number of HTTP requests that web browsers need to
make to load a web page.
URLs for batched resources are in the following format:
For the above scriptaculous example, the following code will be inserted in the header of the page:
Non-Batched Mode
Prior to
, each resource defined was served separately. To revert to this non-batched mode, you can either
Plugin Framework 2.2
use the system property
to turn off batching system wide
plugin.webresource.batching.off=true
or define a 'batch' parameter on each resource like so:
URLs for non batched resources are in the following format:
For the above scriptaculous example with batching turned off, the following code will be inserted in the header of the page:
Transforming Web Resources
Transformers are only available in
and later.
Plugin Framework 2.5
The plugin framework provides web resource transformers that you can use to manipulate static web resources before they are batched and
delivered to the browser.
To use a web resource transformer, you need the following elements in your
file:
atlassian-plugin.xml
The transformer module:
A
element, defining the transformer plugin module. This module can
<web-resource-transformer>
be in the same plugin as the web resource, or in a different plugin.
Transformation elements in the web resource module:
A
element and its child
element
<transformation>
<transformer>
inside the
block, making a particular transformer available to the web resource in the plugin.
<web-resource>
For a complete description and example, please refer to the page on Web Resource Transformer plugin modules.
Notes
Since the resources are returned with headers that tell the browser to cache the content indefinitely, during development, you may
need to hold down the "shift" key while reloading the page to force the browser to re-request the files.
RELATED TOPICS
Web Resource Transformer Plugin Module
Plugin Module Types
Web Resource Transformer Plugin Module
Available:
and later.
Atlassian Plugin Framework 2.5
On this page:
Purpose of this Module Type
Configuration
Attributes of
web-resource-transformer
Child Elements of
web-resource-transformer
Attributes of
transformation
Child Elements of
transformation
Attributes of
transformer
Child Elements of
transformer
Example
Notes
Purpose of this Module Type
Web Resource Transformer plugin modules allow you to manipulate static web resources before they are batched and delivered to the
browser. This means that you can get past the restrictions of straight JavaScript and CSS, including restrictions like no includes, no external
resource support, no CSS variables, only one JS context, and so on.
Configuration
To use a web resource transformer, you need the following elements in your
file:
atlassian-plugin.xml
The transformer module:
A
element, defining the transformer plugin module. This module can
<web-resource-transformer>
be in the same plugin as the web resource, or in a different plugin.
Transformation elements in the web resource module:
A
element and its child
element
<transformation>
<transformer>
inside the
block, making a particular transformer available to the web resource in the plugin.
<web-resource>
Below is a description of the attributes and child elements for each of the above elements.
Attributes of
web-resource-transformer
Name
Required
Description
Default
class
The class which implements
. This class is responsible
com.atlassian.plugin.webresource.transformer.WebResourceTransformer
for doing the resource transformation before it is served to the client. See the plugin framework
guide to
.
creating plugin module instances
 
disabled
 
Indicate whether the plugin module should be disabled by default (value='true') or enabled by
default (value='false').
false
i18n-name-key
 
The localisation key for the human-readable name of the plugin module.
 
key
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the
. A module with key
in a plugin with key
will
complete module key
fred
com.example.modules
have a complete key of
.
com.example.modules:fred
The value of this attribute must match the
attribute of the
element in the
key
transformer
.
web-resource
N/A
name
 
The human-readable name of the plugin module.
 
system
 
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false').
Only available for non-OSGi plugins.
false
Child Elements of
web-resource-transformer
Name
Required
Description
Default
description
 
The description of the plugin module. The 'key' attribute can be specified to declare a localisation key
for the value instead of text in the element body.
 
Attributes of
transformation
Name
Required
Description
Default
extension
All the transformers in the transformation block apply to resources with this extension.
 
Child Elements of
transformation
Name
Required
Description
Default
transformer
Defines a transformation process.
 
Attributes of
transformer
Name
Required
Description
Default
key
The value of this attribute must match the
attribute of the
element.
key
web-resource-transformer
 
(others)
 
You can add your own attributes as required, to pass information to your implementation of the
transformer.
 
Child Elements of
transformer
Name
Required
Description
Default
(others)
 
You can add your own child elements as required, to pass information to your implementation of the
transformer.
 
Example
Here is an example
file containing a web resource and a transformer that turns a static template file into a
atlassian-plugin.xml
JavaScript variable. You could use this transformer for common components that need to use client-side templates.
The template
file looks like this:
testTemplate.txt
Hello world "bob"
and 'friends'
The JavaScript resulting from the transformation is:
Notes
Some information to be aware of when developing or configuring a Web Resource Transformer plugin module:
The
module can live in the same plugin as the
module, or in a different
<web-resource-transformer>
<web-resource>
module. The transformers are registered globally.
You can apply multiple transformers. Any subsequent transformer will process the result of the earlier transformation.
You can pass information to the transformer by adding arbitrary attributes and child elements to the
element in the
<transformer>
resource.
RELATED TOPICS
Web Resource Plugin Module
Plugin Module Types
Web Section Plugin Module
On this page:
Configuration
Attributes
Elements
Label Elements
Tooltip Elements
Param Elements
Context-provider Element
Condition and Conditions elements
Example
Purpose of this Module Type
Web Section plugin modules allow plugins to define new sections in application menus. Each section can contain one or more links. To insert
the links themselves, see the
.
Web Item Plugin Module
Configuration
The root element for the Web Section plugin module is
It allows the following attributes and child elements for configuration:
web-section
Attributes
Name
Required
Description
Default
class
 
The class which implements this plugin module. The class you need to provide depends on the
module type. For example, Confluence theme, layout and colour-scheme modules can use classes
already provided in Confluence. So you can write a theme-plugin without any Java code. But for
macro and listener modules you need to write your own implementing class and include it in your
plugin. See the plugin framework guide to
.
creating plugin module instances
 
disabled
 
Indicate whether the plugin module should be disabled by default (value='true') or enabled by
default (value='false').
false
i18n-name-key
 
The localisation key for the human-readable name of the plugin module.
 
key
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the
. A module with key
in a plugin with key
will
complete module key
fred
com.example.modules
have a complete key of
.
com.example.modules:fred
N/A
name
 
The human-readable name of the plugin module. Only used in the plugin's administrative user
interface.
 
location
Location into which this web item should be placed.
N/A
system
 
Indicates whether this plugin module is a system plugin module (value='true') or not (value='false').
Only available for non-OSGi plugins.
false
weight
Determines the order in which web items appear. Items are displayed top to bottom or left to right in
order of ascending weight. The 'lightest' weight is displayed first, the 'heaviest' weights sink to the
bottom. The weights for most applications' system sections start from 100, and the weights for their
links generally start from 10. The weight is incremented by 10 for each in sequence so that there is
ample space to insert your own sections and links.
N/A
Elements
The table summarises the elements. The sections below contain further information.
Name
Required
Description
Default
condition
 
Defines a condition that must be satisfied for the web item to be displayed. If you want to 'invert' a
condition, add an attribute 'invert="true"' to it. The web item will then be displayed if the condition
returns false (not true).
N/A
conditions
 
Defines the logical operator type used to evaluate the condition elements. By default 'AND' will be
used.
AND
context-provider
 
Allows dynamic addition to the Velocity context available for various web item elements (in XML
descriptors only). Currently only one context-provider can be specified per web item and section.
N/A
description
 
The description of the plugin module. The 'key' attribute can be specified to declare a localisation
key for the value instead of text in the element body. Use this element to describe the section.
 
label
Is the i18n key that will be used to look up the textual representation of the link.
N/A
param
 
Parameters for the plugin module. Use the 'key' attribute to declare the parameter key, then
specify the value in either the 'value' attribute or the element body. This element may be repeated.
An example is the configuration link described in
.
Adding a Configuration UI for your Plugin
Defines a key/value pair available from the web item. This is handy if you want to use additional
custom values from the UI.
N/A
resource
 
A resource for this plugin module. This element may be repeated. A 'resource' is a non-Java file
that a plugin may need in order to operate. Refer to
for
Adding Plugin and Module Resources
details on defining a resource.
N/A
tooltip
 
Is the i18n key that will be used to look up the textual mouse-over text of the link.
N/A
Label Elements
Label elements may contain optional parameters, as shown below:
The parameters allow you to insert values into the label using Java's
syntax.
MessageFormat
Parameter names must start with
and will be mapped in
to the substitutions in the format string. I.e.
param
alphabetical order
param0 is {0}, param1 is {1}, param2 is {2}, etc.
Parameter values are rendered using Velocity, allowing you to include dynamic content.
Tooltip Elements
Tooltip elements have the same attributes and parameters as the label elements. See
.
above
Param Elements
Param elements represent a map of key/value pairs, where each entry corresponds to the param elements attribute:
and
name
value
respectively.
The value can be retrieved from within the Velocity view with the following code, where $item is a
:
WebItemModuleDescriptor
If the
attribute is not specified, the value will be set to the body of the element. I.e. the following two param elements are equivalent:
value
Context-provider Element
Available:
Atlassian Plugins 2.5, Confluence 2.5, Bamboo 3.0, JIRA 4.2 and later
The context-provider element adds to the Velocity context available to the
and
modules. You can add what you need to
web section
web item
the context, to build more flexible section and item elements. Currently only one context-provider can be specified per module. Additional
context-providers are ignored.
The
element must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
context-provider
must implement
, and
com.atlassian.plugin.web.ContextProvider
will be auto-wired by Spring before any additions to the Velocity context.
For example, the following context-provider will add
and
to the context.
historyWindowHeight
filtersWindowHeight
In the following example,
extends
, which is only available in JIRA and
HeightContextProvider
AbstractJiraContextProvider
happens to implement
. The
conveniently extracts the
and
from
ContextProvider
AbstractJiraContextProvider
User
JiraHelper
the context map, which you would otherwise have to do manually.
The above
can be used by nesting the following element in a web item module.
HeightContextProvider
The newly added context entries
and
can be used in the XML module descriptors just
historyWindowHeight
filtersWindowHeight
like normal velocity context variables, by prefixing them with the dollar symbol ($):
Condition and Conditions elements
Conditions can be added to the
,
and
modules, to display them only when
the given conditions are true.
web section
web item
web panel
all
Condition elements must contain a class attribute with the fully-qualified name of a Java class. The referenced class:
must implement
, and
com.atlassian.plugin.web.Condition
will be auto-wired by Spring before any condition checks are performed.
Condition elements can take optional parameters. These parameters will be passed in to the condition's
method as a map of string
init()
key/value pairs after autowiring, but before any condition checks are performed. For example:
To invert a condition, add the attribute 'invert="true"' to the condition element. This is useful where you want to show the section if a certain
condition is
satisfied.
not
Conditions elements are composed of a collection of condition/conditions elements and a type attribute. The type attribute defines what
logical operator is used to evaluate its collection of condition elements. The type can be one of
or
.
AND
OR
For example: The following condition is true if the current user is a system administrator OR a project administrator:
Example
Here is an example
file containing a single web section, using a condition that will be available in JIRA:
atlassian-plugin.xml
RELATED TOPICS
Web Item Plugin Module
Plugin Module Types
Adding Plugin and Module Resources
On this page:
Purpose of a Resource
Example of a Resource Definition
Contents of the Resource Definition
Example of Resource Type: Downloadable Plugin Resources
Example of Resource Type: Stylesheet referring to Images
Values for Param Element
Purpose of a Resource
A 'resource' is a non-Java file that a plugin may need in order to operate. Examples of possible resources might be:
A Velocity file used to generate HTML for a macro or layout plugin module in Confluence.
A CSS file required by a theme layout plugin module.
An image referenced from within a layout plugin module.
A macro help file.
A localisation property file.
Resource definitions can be either a part of the plugin, or part of a particular plugin module.
Example of a Resource Definition
Here is a sample resource definition:
Contents of the Resource Definition
A resource has a name, a type and a location. The resource definition maps an arbitrary resource name to the location of that resource in the
server's classpath.
Element
Attribute
Description
<resource>
 
This block defines the resource. For example:
<resource type="velocity" name="template"
location="com/example/plugin/template.vm"/>
<resource>
name
The name of the resource defines how the plugin module can locate a particular resource. Must be specified if
'namePattern' is not. If your location parameter points to a directory rather than a single resource, you should
specify the name with a trailing '/'. For example:
<resource type="download" name="myimages/"
location="com/example/plugin/myimages"/>
Note that for css/javascript resources, they must have the appropriate file extension in the name i.e.
.css,

.js
<resource>
namePattern
The pattern to use when loading a directory resource.
<resource>
type
The type of a resource tells the module how that resource can be used. The values allowed are different for
each application.
A module can look for resources of a certain type or name. For example, a
plugin requires that its
layout
help file is a file of type
and name
.
velocity
help
Refer to the examples of resource types below.
<resource>
location
The location of a resource tells the plugin where the resource can be found in the jar file. (Resources are
loaded by Java's classpath resource loader.)
The full path to the file (without a leading slash) is required.
Must end in a '/' when using the 'namePattern' attribute to load multiple resources in a directory.
<property>
key/value
Resources may contain arbitrary key/value pairs. For example:
<property key="content-type"
value="text/css"/>
<param>
name/value
Resources may contain arbitrary name/value pairs. For example:
<param name="content-type"
. Refer to the list of values for the param element below
value="image/gif"/>
Example of Resource Type: Downloadable Plugin Resources
The simplest kind of resource, supported with all plugin module types, is of type
, which makes a resource available for download
download
from the application at a particular URL.
Example of Resource Type: Stylesheet referring to Images
Stylesheets for your plugin may often refer to images also in your plugin. In which case you would have to make both the stylesheet and
image(s) downloadable.
Note: If you have multiple stylesheets and javascript resources defined, you should put the resource defintions in a
Web Resource Module.
To refer to your plugin images in a stylesheet, use a relative path based on the resource name defined for the image (which is 'my-images' in
this case).
my-style.css
To reference images already available in an application, you will need to go up three parent directories like so:
Values for Param Element
These are the common name/value pairs supported by the
element.
<param>
Name
Value
(Example)
Description
content-type
image/gif
Specify a MIME content type.
media
print
Declare the media type for CSS resources. This is supported by
.
Web Resource plugin modules
For example, requesting this resource will insert a
in the HTML header, with a media value of 'print':
<link>
ieonly
true
Specify that the resource should be wrapped in an
. This is supported by
Internet Explorer conditional comment
.
Web Resource plugin modules
For example, the web resource declaration below says that the resource should be wrapped in an Internet
Explorer conditional comment, which means it will only be used by Internet Explorer. This is useful for
IE-specific styling to work around browser bugs.
The HTML output when this resource is included will be something like this:
The
parameter also works for JavaScript resources.
ieonly
title
(Your title)
The value given here will form the title attribute of the CSS
tag.
<link>
RELATED TOPICS
Creating your Plugin Descriptor
Plugin Module Types
Component Import Plugin Module
Component Plugin Module
Module Type Plugin Module
Servlet Context Listener Plugin Module
Servlet Context Parameter Plugin Module
Servlet Filter Plugin Module
Servlet Plugin Module
Template Context Item Plugin Module
Web Item Plugin Module
Web Panel Plugin Module
Web Panel Renderer Plugin Module
Web Resource Plugin Module
Web Resource Transformer Plugin Module
Web Section Plugin Module
Adding Plugin and Module Resources
Supporting Minification of JavaScript and CSS Resources
Adding a Configuration UI for your Plugin
Ensuring Standard Page Decoration in your Plugin UI
Using Packages and Components Exposed by an Application
Creating Plugin Module Instances
Plugin Developer's Cookbook
Consuming a Service in my Plugin
Declaring a Dependency on Another Plugin
Declaring a Dependency on a Third-Party Package
Defining an Extension Point in my Plugin
Exposing a Service in my Plugin
OSGi, Spring and the Plugin Framework
Behind the Scenes in the Plugin Framework
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
Converting a Plugin to Plugin Framework 2
OSGi and Spring Reference Documents
Supporting Minification of JavaScript and CSS Resources
Available:
and later.
Atlassian Plugin Framework 2.3
The Atlassian Plugin Framework supports
when serving JavaScript and CSS resources.
minification
On this page:
How Minification Works
Compressing Files in your Build
Disabling Minification
The aim of minification is to remove all unnecessary characters (such as white space) without affecting the functionality.
How Minification Works
For a given resource, the plugin framework will serve the minified file (
or
) if present, otherwise it will serve the
*-min.xxx
*.min.xxx
non-minified file.
For example, take a look at this declaration:
When the resource named
is requested, the system will check for a file called
or
. If
avataror.js
avataror-min.js
avataror.min.js
either of these files exists, it will be served. Otherwise, the plugin framework it will fall back to the old behaviour of streaming the named
location file.
Compressing Files in your Build
There is a Maven 2 plugin that will compress files in your build.
Disabling Minification
You can turn off minification support in your development environments, so that you serve up only non-minified files for debugging purposes:
Minification is automatically disabled in Atlassian developer mode.
RELATED TOPICS
Creating your Plugin Descriptor
Plugin Module Types
Component Import Plugin Module
Component Plugin Module
Module Type Plugin Module
Servlet Context Listener Plugin Module
Servlet Context Parameter Plugin Module
Servlet Filter Plugin Module
Servlet Plugin Module
Template Context Item Plugin Module
Web Item Plugin Module
Web Panel Plugin Module
Web Panel Renderer Plugin Module
Web Resource Plugin Module
Web Resource Transformer Plugin Module
Web Section Plugin Module
Adding Plugin and Module Resources
Supporting Minification of JavaScript and CSS Resources
Adding a Configuration UI for your Plugin
Ensuring Standard Page Decoration in your Plugin UI
Using Packages and Components Exposed by an Application
Creating Plugin Module Instances
Plugin Developer's Cookbook
Consuming a Service in my Plugin
Declaring a Dependency on Another Plugin
Declaring a Dependency on a Third-Party Package
Defining an Extension Point in my Plugin
Exposing a Service in my Plugin
OSGi, Spring and the Plugin Framework
Behind the Scenes in the Plugin Framework
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
Converting a Plugin to Plugin Framework 2
OSGi and Spring Reference Documents
Adding a Configuration UI for your Plugin
On this page:
Purpose of the Configuration UI
Adding a Configuration Link for the Entire Plugin
Adding a Configuration Link for a Module
Example of a Plugin Configuration UI
Notes
Purpose of the Configuration UI
A plugin for an Atlassian application can specify internal links within the application, to allow the user to configure options for the plugin. This
is useful where your plugin requires configuration or user-specific settings to work.
Here are some examples of plugins which provide a configuration UI:
The
requires a Google API Key from Google, which needs to be configured on each server,
Google Maps plugin for Confluence
before it will work properly.
The
provides a configuration screen that is available both from the Plugin Manager and from a web
WebDAV plugin for Confluence
item in the Administration menu.
In
, we tell you how to create the XML descriptor file for your plugin. In
, we tell you how
Creating your Plugin Descriptor
Plugin Module Types
to define the modules within your plugin. Below is information on defining the links to the configuration UI for your plugin.
Adding a Configuration Link for the Entire Plugin
To add a configuration link for your plugin as a whole, place a single
element with the name
within the
param
configure.url
element at the top of the plugin descriptor:
plugin-info
Example of a Plugin Configuration UI
Here is an image showing where the configuration link appear for a plugin within JIRA:
Notes
Configuration links are relative to the application.
The configuration URL is a link to a separate page, which you have defined using one of the following:
A new XWork action that you have defined via an XWork plugin module.
Or a servlet defined via a
plugin module.
Servlet
Not all host applications support configuration links, so you may need to create a web item link in the administration menu to link to
your configuration page.
RELATED TOPICS
Creating your Plugin Descriptor
Plugin Module Types
Component Import Plugin Module
Component Plugin Module
Module Type Plugin Module
Servlet Context Listener Plugin Module
Servlet Context Parameter Plugin Module
Servlet Filter Plugin Module
Servlet Plugin Module
Template Context Item Plugin Module
Web Item Plugin Module
Web Panel Plugin Module
Web Panel Renderer Plugin Module
Web Resource Plugin Module
Web Resource Transformer Plugin Module
Web Section Plugin Module
Adding Plugin and Module Resources
Supporting Minification of JavaScript and CSS Resources
Adding a Configuration UI for your Plugin
Ensuring Standard Page Decoration in your Plugin UI
Using Packages and Components Exposed by an Application
Creating Plugin Module Instances
Plugin Developer's Cookbook
Consuming a Service in my Plugin
Declaring a Dependency on Another Plugin
Declaring a Dependency on a Third-Party Package
Defining an Extension Point in my Plugin
Exposing a Service in my Plugin
OSGi, Spring and the Plugin Framework
Behind the Scenes in the Plugin Framework
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
Converting a Plugin to Plugin Framework 2
OSGi and Spring Reference Documents
Ensuring Standard Page Decoration in your Plugin UI
Available:
Atlassian applications which support
and later will also support standard page
Atlassian Plugin Framework 2.1
decorators.
On this page:
Purpose of the Standard Page Decorators
Specifying a Decorator
Purpose of the Standard Page Decorators
Atlassian applications support standard page decorators, allowing your plugin to generate new web pages with consistent decoration by the
host application across the Atlassian products.
Specifying a Decorator
Specify the decorator with an HTML
tag in your
element:
meta
head
The following decorators are available.
Decorator
Description
Version of
Atlassian
Plugin
Framework
atl.admin
For application administration pages.
2.1 and later
atl.general
For the header and footer of general pages outside the administration UI.
2.1 and later
atl.popup
For content that you want placed in a new browser popup window.
2.3 and later
atl.userprofile
For content on a page in the user profile.
This decorator will generally be accompanied by a web item link or tab. The tab, if applicable,
should be specified by the
meta tag. For example:
tab
In the above example, the value of the
attribute is the ID of the tab. Since plugins can
content
be shared among applications, we recommend that cross-application plugins define their own tab
to ensure the same ID will be used everywhere.
Note: The profile decorator is still experimental. In some applications it may function in the same
way as
. Tabs are not yet supported by all Atlassian applications. If not supported,
atl.general
the tab will simply be ignored.
2.3 and later
RELATED TOPICS
Creating your Plugin Descriptor
Plugin Module Types
Component Import Plugin Module
Component Plugin Module
Module Type Plugin Module
Servlet Context Listener Plugin Module
Servlet Context Parameter Plugin Module
Servlet Filter Plugin Module
Servlet Plugin Module
Template Context Item Plugin Module
Web Item Plugin Module
Web Panel Plugin Module
Web Panel Renderer Plugin Module
Web Resource Plugin Module
Web Resource Transformer Plugin Module
Web Section Plugin Module
Adding Plugin and Module Resources
Supporting Minification of JavaScript and CSS Resources
Adding a Configuration UI for your Plugin
Ensuring Standard Page Decoration in your Plugin UI
Using Packages and Components Exposed by an Application
Creating Plugin Module Instances
Plugin Developer's Cookbook
Consuming a Service in my Plugin
Declaring a Dependency on Another Plugin
Declaring a Dependency on a Third-Party Package
Defining an Extension Point in my Plugin
Exposing a Service in my Plugin
OSGi, Spring and the Plugin Framework
Behind the Scenes in the Plugin Framework
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
Converting a Plugin to Plugin Framework 2
OSGi and Spring Reference Documents
Using Packages and Components Exposed by an Application
Using OSGi within the Atlassian Plugin Framework 2, a plugin can access only those external classes that the host application explicitly
exposes. (Or classes that other plugins expose.) For example, if you are writing a Confluence plugin then you can access only the packages
that Confluence exposes. This means that you cannot assume that all classes on the Confluence classpath will be accessible to your plugin.
Also, a plugin can access only those Spring components that are explicitly exposed by the host application or other plugins.
This restriction applies to 'Version 2' plugins only
The distinction between private and public packages/components is respected only by plugins with
or
in the plugin descriptor.
pluginsVersion="2"
plugins-version="2"
Note: When you are using host components inside your plugin, you should provide a named import for each of those components. This will
make it easier for you to spot and thus prevent name collisions between host components and components created by your plugin.
The table below shows you how to discover the packages and the Spring components that are explicitly exposed by each Atlassian
application, provided that the application supports the Atlassian Plugin Framework 2.
Application
Available Packages
Available Components
Confluence
2.10
See the list in
.
this document
See the list at this URL for your Confluence instance:
http://<baseURL>/admin/pluginexports.action
Confluence
3.0
See the list in
.
this document
See the list at this URL for your Confluence instance:
http://<baseURL>/admin/pluginexports.action
Crowd 1.6
and later
Set the
to 'DEBUG' and restart
Crowd logging level
Crowd. The available packages will be listed to your
log file.
Set the
to 'DEBUG' and restart Crowd. The
Crowd logging level
available components will be listed to your log file.
RELATED TOPICS
Creating your Plugin Descriptor
Plugin Module Types
Component Import Plugin Module
Component Plugin Module
Module Type Plugin Module
Servlet Context Listener Plugin Module
Servlet Context Parameter Plugin Module
Servlet Filter Plugin Module
Servlet Plugin Module
Template Context Item Plugin Module
Web Item Plugin Module
Web Panel Plugin Module
Web Panel Renderer Plugin Module
Web Resource Plugin Module
Web Resource Transformer Plugin Module
Web Section Plugin Module
Adding Plugin and Module Resources
Supporting Minification of JavaScript and CSS Resources
Adding a Configuration UI for your Plugin
Ensuring Standard Page Decoration in your Plugin UI
Using Packages and Components Exposed by an Application
Creating Plugin Module Instances
Plugin Developer's Cookbook
Consuming a Service in my Plugin
Declaring a Dependency on Another Plugin
Declaring a Dependency on a Third-Party Package
Defining an Extension Point in my Plugin
Exposing a Service in my Plugin
OSGi, Spring and the Plugin Framework
Behind the Scenes in the Plugin Framework
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
Converting a Plugin to Plugin Framework 2
OSGi and Spring Reference Documents
Creating Plugin Module Instances
On this page:
Overview
Using the "bean" Prefix
Examples
Making a module instance available to other components or plugin modules
Using "byName" setter injection
Creating a New Prefix
Example
Step 1. Create a PrefixModuleFactory instance
Step 2. Expose it as a component
Step 3. Use the new prefix
Overview
When specifying an implementation of a plugin module, you can specify the class name that the plugin framework should resolve, instantiate,
and inject for you. Instances are created per usage (prototype-scope) and Spring injection will happen via
,
autodetection autowire mode
which tries constructor injection, falling back to setter injection by type.
In
and later, the instantiation of a plugin module has been improved to give you full control how your module
Atlassian Plugin Framework 2.5
classes will be created via a new optional prefix-based, pluggable PrefixModuleFactory interface. Out of the box, the framework ships with
support for the
prefix that allows you to refer to a Spring bean by ID instead of specifying a classname in the module descriptor.
"bean:"
This gives you complete control over the creation, scope, and injection of your plugin modules.
Everything from here down is available in
and later.
Atlassian Plugin Framework 2.5
For example, if you wanted to instantiate a class, you could specify a servlet class via:
<servlet key="myServlet" class="class:com.example.MyServlet" />
Since the "class" prefix is the default, you could also configure the Servlet via:
<servlet key="myServlet" class="com.example.MyServlet" />
The following prefixes are supported:
Prefix
Description
Default
class
Instantiates the class via Spring using the autodetect autowire mode
true
bean
Looks up the specified bean ID in the Spring context
 
Using the "bean" Prefix
Before you can use the "bean" prefix, you must create a bean that lives in the Spring context. This bean can be specified via the
module type or in a custom Spring XML file living in
. When using Spring XML directly, you have full
<component>
META-INF/spring
control over the creation, scope, and injection of the bean. Reasons you may want to use the "bean" prefix include:
Want to use constructor injection even if you have a default constructor.
Want to manually configure the beans to inject, including constants.
Want to share a module instance with components.
Want to customise the scope of the module instance. But be aware that the descriptor may cache the instance later.
Examples
Making a module instance available to other components or plugin modules
In
:
atlassian-plugin.xml
<component key="myServlet" class="com.example.MyServlet" />
<servlet key="myServlet" class="bean:myServlet" />
Using "byName" setter injection
In
:
META-INF/spring/myPlugin.xml
<bean id="myServlet" class="com.example.MyServlet" autowire="byName"/>
In
:
atlassian-plugin.xml
<servlet key="myServlet" class="bean:myServlet" />
Creating a New Prefix
You can create your own prefix for further control over the creation of module instances. This technique can be used to do things like
delegating the creation to a scripting engine or automatically wrapping all module instances in proxies.
Example
Let's say we want to create a new prefix called "named", which instantiates all module instances via a single argument constructor that
expects the name of the plugin.
Step 1. Create a PrefixModuleFactory instance
Our
loads the class then instantiates its constructor with the plugin key:
NamedPrefixModuleFactory
public class NamedPrefixModuleFactory implements PrefixModuleFactory
{
public String getPrefix()
{
return "named";
}
public <T> T createModule(String name, ModuleDescriptor<T> moduleDescriptor) throws
PluginParseException
{
try
{
Class clazz = getClass().getClassLoader().loadClass(name);
return (T)
clazz.getConstructor(String.class).newInstance(moduleDescriptor.getPluginKey());
}
catch (Exception e)
{
throw new RuntimeException("Obviously non-production code here...", e);
}
}
}
Step 2. Expose it as a component
Just by exposing the
as a component, or more specifically, as a bean in our
, the plugin
NamedPrefixModuleFactory
BeanFactory
framework will pick it up and use it for plugin module prefix resolution:
<component key="namedPrefix" class="com.example.NamedPrefixModuleFactory" />
Step 3. Use the new prefix
The prefix is now able to be used by plugin modules that expect objects like the servlet module type:
<servlet key="myServlet" class="named:com.example.MyServlet" />
RELATED TOPICS
Writing Atlassian Plugins
Plugin Module Types
Plugin Developer's Cookbook
This page is in DRAFT and is visible to
.
Atlassian staff only
This page contains a collection of guidelines on the more advanced facilities the plugin framework offers to plugin developers.
First we show a table comparing plugins of different complexities, and answering the question '
'. This information is for
Do I need to xxx?
plugin developers who have heard of or read about all the capabilities and complexities that are available to an OSGi plugin, and then
wonder how much of it they need to know. The Atlassian Plugin Framework takes care of most of the complexity for you, particularly if you
are developing a simple plugin for a single product. Take a look at the table for a quick reference to what you need to do.
Then we list the more advanced things you may like to do, with links to the detailed information.
Do I need to xxx?
Do I need to...
Simple
Plugin
Complex Plugin
Cross-Product Plugin
Add
to the plugin descriptor?
plugins-version="2"
yes
yes
yes
Put my plugin JAR into
?
WEB-INF/lib
 
 
 
Mess with the manifest?
no
maybe
yes
Specify my own Spring config files in
folder?
META-INF/spring
no
maybe
maybe
Define a class path for dependent JARs, other than
?
META-INF\lib
no
no
maybe
Add bundle instructions in
?
atlassian-plugin.xml
no
probably
yes, if not generating your own
manifest
Modify the build process?
no
yes, if generating your own
manifest
yes
Use maven?
no
probably
yes
Definitions:
Simple plugin
 A 'simple' plugin is a self-contained plugin written for a single Atlassian application only. The plugin has no
dependencies other than those already provided by the host application. No other plugins depend on this plugin.
Complex plugin
 A 'complex' plugin is a plugin written for a single Atlassian application. The plugin has one or more
dependencies on other plugins or on external libraries not provided by the host application, and may have other plugins that depend
on it.
Cross-product plugin
 A 'cross-product' plugin is a plugin that can be installed into more than one of the Atlassian applications,
where the plugin code (and perhaps configuration) is the same for all relevant applications.
Advanced Topics
Consuming a Service in my Plugin
Declaring a Dependency on Another Plugin
Declaring a Dependency on a Third-Party Package
Defining an Extension Point in my Plugin
Exposing a Service in my Plugin
RELATED TOPICS
OSGi, Spring and the Plugin Framework
Writing Atlassian Plugins
Consuming a Service in my Plugin
Content required. Perhaps some of it is already present on page
and should be moved from there to
OSGi, Spring and the Plugin Framework
here.
Declaring a Dependency on Another Plugin
Content required. Perhaps some of it is already present on page
and should be moved from there to
OSGi, Spring and the Plugin Framework
here.
Declaring a Dependency on a Third-Party Package
Content required. Perhaps some of it is already present on page
and should be moved from there to
OSGi, Spring and the Plugin Framework
here.
Defining an Extension Point in my Plugin
Content required. Perhaps some of it is already present on page
and should be moved from there to
OSGi, Spring and the Plugin Framework
here.
Exposing a Service in my Plugin
Content required. Perhaps some of it is already present on page
and should be moved from there to
OSGi, Spring and the Plugin Framework
here.
OSGi, Spring and the Plugin Framework
OSGi
is a dynamic module system for Java.
On this page:
OSGi Terminology
Overview of OSGi in the Plugin Framework
OSGi Features
What Benefits do the Above Features Give Us?
Service Registry
Lifecycle
Bundle Manifest
Spring Dynamic Modules
Using Services
Declaring a Bean as an OSGi Service
Declaring an OSGi Service as a Bean
Making Plugins Depend on Each Other
Defining Extension Points for Plugins
OSGi Terminology
Bundle
 A bundle is a JAR file with special OSGi entries in its manifest and containing classes, resources, and other JARs.
Lifecycle
 A lifecycle is the sequence of states a
goes through: uninstalled, installed, resolved, starting, stopping, active.
bundle
Service
 A service is an object instance exposed under the one or more interfaces that it implements and a map of properties.
Take a look at the
for more terms and definitions.
glossary
Overview of OSGi in the Plugin Framework
OSGi Features
Service registry
Lifecycle model
Bundle dependency system
Optional security layer (not currently used, but may be used in the future e.g. to define trusted plugins)
What Benefits do the Above Features Give Us?
You can upgrade bundles at runtime.
Bundles can depend on other bundles at a service, package, or JAR level. At a very simple level, you can define that plugin A
requires plugin B
Bundles can hide packages from other bundles. For example, you might make your API package public but hide other packages.
This reduces the complexity of dependencies, making it easier for you to change your plugin and know that you will not break other
plugins on upgrade.
Bundles can expose packages by version.
Service Registry
A service registry is a map of one or more interfaces bound to object instances, with a set of properties attached to it.
Key  A string representation of the interface name. One or more interfaces that this service is implementing.
Instance
Properties
Example of a service registration:
Key: "com.foo.MyInterface"
Instance: com.foo.MyService
Properties:
name => foo
someProperty => someValue
Lifecycle
A lifecycle is the sequence of states a
goes through: uninstalled, installed, resolved, starting, stopping, active.
bundle
Most stages in the bundle lifecycle are familiar to plugin developers. OSGi adds the
step. This indicates that the OSGi system has
resolved
connected up all the dependencies at a class level and made sure they are all resolved.
Bundle Manifest
When you create an OSGi bundle, the manifest is where you declare information such as a bundle symbolic name (i.e. the plugin key) and
the bundle version (i.e. the plugin version), etc.
You can import a package, and even declare that you need a specific version of the package. This is a nice way to declare your
dependencies. For example, if your plugin uses Velocity, you can say you require Velocity 1.5 or greater.
You can export packages, i.e. make them available to other plugins and/or applications.
You can also define a class path for where you are putting your dependent JARs. Either you can continue putting all your dependent JARs
into the default
folder inside the JAR, or you can choose your own custom location.
META-INF/lib
Example of a bundle manifest:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: org.foo.Example
Bundle-Version: 1.0
Import-Package: org.bar;version="1.3.0"
Export-Package: org.foo.api
Bundle-ClassPath: .,META-INF/lib/foo.jar
More:
.
Setting OSGi Manifest Instructions in your Plugin
Spring Dynamic Modules
The
library (Spring DM) enables developers to build plugins with a consistent dependency injection across
Spring Dynamic Modules
Atlassian applications.
Spring DM takes the service model of OSGi and simplifies it into Spring terms, making the dynamics of OSGi services a bit easier to work
with. This is especially useful for developers who are already familiar with Spring.
Spring DM gives every plugin its own bean factory. You can:
Declare internal beans, e.g. beans used by the plugin but not available publicly.
Expose beans, using a bit of XML, as OSGi services so that other plugins can consume them.
Declare a bean in your bean factory which is simply a proxy to another service provided by another bundle. You declare the interface
in your constructor and get it injected, but Spring handles how that instance of that interface is wired to an actual service in OSGi.
For more information, see the
.
Spring DM documentation
Using Services
<osgi:service id="fooService"
ref="foo"
interface="com.myapp.Foo"/>
Declaring a Bean as an OSGi Service
<!-- bunch of XML namespace stuff skipped -->
<beans>
<bean name="foo" class="com.myapp.FooImpl"/>
<osgi:service id="fooService" ref="foo"
interface="com.myapp.Foo"/>
</beans>
Declaring an OSGi Service as a Bean
<!-- bunch of XML namespace stuff skipped -->
<beans>
<osgi:reference id="foo"
interface="com.myapp.Foo"/>
</beans>
Making Plugins Depend on Each Other
Plugins can generate their own OSGi headers and use:
Require-Bundle: org.otherPlugin;bundleversion="[3.2.0,4.0.0)"
Import-Package: org.otherPlugin.api;version="[3.2.0,4.0.0)"
Defining Extension Points for Plugins
Plugin A contains the
interface and defines a service reference:
org.Foo
<component-import key="foo" interface="foo.Foo" />
Plugin B exposes its implementation:
<component key="foo" public="true"
class="org.bar.FooImpl" interface="org.foo.Foo" />
RELATED TOPICS
Behind the Scenes in the Plugin Framework
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
Converting a Plugin to Plugin Framework 2
OSGi and Spring Reference Documents
Setting OSGi Manifest Instructions in your Plugin
Writing Atlassian Plugins
Behind the Scenes in the Plugin Framework
If you are developing a complex plugin, you may find it useful to know how the Atlassian Plugin Framework works. Below is some information
on specific aspects of the plugin framework.
Going from Plugin to OSGi Bundle
Lifecycle of a Bundle
Dynamic Module Types
Automatic Generation of Spring Configuration
RELATED TOPICS
Writing Atlassian Plugins
Going from Plugin to OSGi Bundle
The plugin framework supports multiple types of plugins ranging from built-in plugins that are little more than an XML file to fully-fledged
OSGi-based plugins.
For version 2 plugins that are deployed into the internal OSGi container, as a plugin author you can ignore all the OSGi trappings and just
provide a JAR containing the
descriptor file.
atlassian-plugin.xml
The Atlassian Plugin Framework 2 tries to hide the complexity of OSGi as much as possible, especially for simple plugins that do not have
dependencies on other plugins. However, since version 2 plugins will be deployed on OSGi, they need to be transformed into an OSGi
bundle that the OSGi container understands. The Atlassian Plugin Framework has a built-in way of transforming plugin JARs into
fully-fledged OSGi bundles.
If you are familiar with OSGi and want to provide an OSGi bundle directly in order to leverage all its features, you are free to do so.
Converting a Plugin into an OSGi Bundle
The following diagram describes the process by which a plugin JAR is dynamically loaded and, at the end of the process flow, transformed
into an OSGi bundle.
RELATED TOPICS
[
]
Setting OSGi Manifest Instructions in your Plugin
Automatic Generation of Spring Configuration
Plugin Framework
Lifecycle of a Bundle
OSGi is a dynamic platform. This means that bundles may be installed, started, updated, stopped, and uninstalled at any time during the
running of the framework.
The table below shows the possible states of an OSGi bundle and how these map to the plugin states.
Status of
OSGi Bundle
Description
Plugin Status
INSTALLED
The bundle has been installed into the OSGi container, but some
of the bundle's dependencies have not yet been met. The bundle
requires packages that have not been exported by any currently
installed bundle.
Disabled
RESOLVED
The bundle is installed, and the OSGi system has connected up
all the dependencies at a class level and made sure they are all
resolved. The bundle is ready to be started. If a bundle is started
and all of the bundle's dependencies are met, the bundle skips
this state.
Disabled
STARTING
A temporary state that the bundle goes through while the bundle
is starting, after all dependencies have been resolved.
Disabled
1.
2.
3.
4.
ACTIVE
The bundle is running.
while Spring is doing its stuff. Spring scans
Disabled
the Spring configuration and builds the context, then
hands the context to the plugin. The plugin needs the
context in order to create instances of each plugin
module.
once Spring has handed the context to the
Enabled
plugin.
STOPPING
A temporary state that the bundle goes through while the bundle
is stopping.
Disabled
UNINSTALLED
The bundle has been removed from the OSGi container.
Disabled
RELATED TOPICS
Behind the Scenes in the Plugin Framework
Writing Atlassian Plugins
Dynamic Module Types
This page is in DRAFT and is visible to
only.
Atlassian staff
Tell the developers what they need to know about dynamic module types  how the Plugin Framework handles them, and how this affects
the decisions a plugin developer will need to make.
Automatic Generation of Spring Configuration
The Atlassian Plugin Framework uses
to implement many of its features for OSGi plugins by automatically generating Spring XML
Spring
configuration files. This generation occurs as several steps in the
that happens at plugin
OSGi plugin -> OSGi bundle transformation
installation. These steps are:
Component Import transformation
Component transformation
Host component imports
Module Type transformation
Component Import Transformation
The
module type allows a plugin to import a component exposed by another plugin or by the host application itself. These
Component Import
elements are converted into the Spring configuration file
as
META-INF/spring/atlassian-plugins-component-imports.xml
Spring DM
elements. See the
.
<osgi:reference>
Spring DM documentation
In their place, a placeholder module descriptor is stored in the plugin framework so that the import will appear in the list of plugin modules.
However, disabling it has no effect.
Component Transformation
The
module type allows a plugin to make an object available for dependency injection within the plugin, and with the 'public' flag,
Component
also expose that instance to other plugins, accessible via the Component Import module type. The transformation that occurs upon
installation converts these elements into Spring
elements in a configuration file called
<beans:bean>
. If the 'public' flag is set to true, the bean instances are also exposed via
META-INF/spring/atlassian-plugins-components.xml
the Spring DM
element. See the
.
<osgi:service>
Spring DM documentation
Like the Component Import module type, in their place, a placeholder module descriptor is stored in the plugin framework so that the
component will appear in the list of plugin modules. However, disabling it has no effect.
Host Component Imports
Upon plugin installation, the plugin framework will scan the classes in the plugin JAR for any references to host components. If any are
detected, the framework will generate the Spring configuration file
to
META-INF/spring/atlassian-plugins-host-components.xml
add a bean for each host component needed. Since host components are always available and do not change during runtime, the bean
definitions are special purpose beans that import the host component services on startup. The Spring DM
element is
<osgi:reference>
not used, because it adds a lot of overhead that is not necessary here. You can override the beans by using the
<component-import>
element to specify a different bean name, since if the plugin framework detects an import for a host component, it will not generate a bean
reference.
This is an example of a generated host component reference named 'foo':
<beans:bean id="foo" class="com.atlassian.plugin.osgi.bridge.external.HostComponentFactoryBean">
<beans:property name="filter" value="(&amp;(bean-name=foo)(plugins-host=true))"/>
</beans:bean>
The 'bean-name' is provided to the plugin framework by the application on initialisation, and the 'plugins-host' property is used to further
restrict the filter to just host components.
1.
Module Type Transformation
The
module allows a plugin to define its own plugin module types that it and other plugins can use. At installation time, it
Module Type
generates a bit of Spring configuration in a file named
to expose the
META-INF/spring/atlassian-plugins-module-types.xml
appropriate
instance.
com.atlassian.plugin.ModuleDescriptorFactory
Here is an example of a module type 'foo' that uses the
module descriptor instance:
my.FooDescriptor
Code in
:
atlassian-plugin.xml
<module-type key="foo" class="my.FooDescriptor" />
Code in
:
META-INF/spring/atlassian-plugins-module-types.xml
<beans:bean id="springHostContainer"
class="com.atlassian.plugin.osgi.bridge.external.SpringHostContainer"/>
<beans:bean id="moduleType-foo"
class="com.atlassian.plugin.osgi.external.SingleModuleDescriptorFactory">
<beans:constructor-arg index="0" ref="springHostContainer"/>
<beans:constructor-arg index="1">
<beans:value>foo</beans:value>
</beans:constructor-arg>
<beans:constructor-arg index="2">
<beans:value>my.FooDescriptor</beans:value>
</beans:constructor-arg>
</beans:bean>
<osgi:service id="moduleType-foo_osgiService" ref="moduleType-foo" auto-export="interfaces"/>
The
bean is only created once per plugin, providing the ability to instantiate module descriptor instances using the
SpringHostContainer
plugin's Spring container. This means the module descriptor class 'FooDescriptor' can support constructor dependency injection for host and
plugin components.
RELATED TOPICS
Going from Plugin to OSGi Bundle
Plugin Framework
Converting a Plugin to Plugin Framework 2
This page contains guidelines on migrating an existing version 1 plugin to the Atlassian Plugin Framework 2. Version 2 and later of the plugin
framework is based on
and Spring Dynamic Modules. The plugin framework has all the advantages of OSGi, plus it will be included
OSGi
into all Atlassian applications. This means that writing plugins for different applications will be more consistent.
Plugins that were written for the old framework will continue to work, but to leverage the new functionality you will need to convert your plugin
to the new framework. This page describes how to migrate an existing plugin to the new plugin framework.
On this page:
Prerequisites
Summary of How to Convert your Plugin
Details of How to Convert your Plugin
1. Set your plugin 'plugins-version' flag to version 2
2. Check that packages used by your plugin are available to OSGi plugins
2.1 Rely on automatic package imports
2.2 Customise package imports and exports with a bundle manifest
3. Check that components used by your plugin are available to OSGi plugins
3.1 Specify qualifiers on ambiguous Spring dependencies
3.2 Expose your plugin components to other plugins
3.3 Import components exposed by other plugins
4. Advanced configuration with Spring configuration files
Notes
Useful External Guides
Prerequisites
First upgrade the host application to a version which supports version 2 of the plugin framework. For example, upgrade to Confluence 2.10 or
later, or JIRA 4.0 or later. See the
.
Plugin Framework Version Matrix
Summary of How to Convert your Plugin
Summary of the steps required to convert your plugin:
Add the
attribute in
:
plugins-version="2"
atlassian-plugin.xml
1.
2.
3.