Confluence Docs 3.0 : Creating your Plugin Descriptor
This page last changed on Sep 07, 2009 by smaddox.
On this page: Purpose of a Plugin DescriptorWhen developing a plugin for an Atlassian application such as Confluence or JIRA, you need to create a 'plugin descriptor' for your plugin. The plugin descriptor is an XML file that tells the application all about the plugin and the modules contained within it. The descriptor must be a single file named atlassian-plugin.xml and must be located at the root of the plugin's jar file. Example of a Plugin DescriptorHere is a sample plugin descriptor: <!-- Every plugin must have a key, which identifies the plugin uniquely to the system --> <!-- and a name, which is used to display the plugin in menus. --> <atlassian-plugin key="com.atlassian.confluence.plugins.example" name="Example Plugin" plugins-version="2"> <!-- The plugin info block allows you to provide more information about your plugin --> <plugin-info> <description> A sample plugin for demonstrating the file format. </description> <!-- This version is displayed in the application's Plugin Manager. --> <version>1.0</version> <!-- The versions of the application this plugin is is compatible with --> <application-version min="1.3" max="1.3"/> <vendor name="Atlassian Software Systems Pty Ltd" url="http://www.atlassian.com/"/> <!-- The location of any plugin configuration (optional) --> <param name="configure.url">/admin/plugins/example/configurePlugin.action</param> <!-- Specifically declare bundle instructions (optional) --> <bundle-instructions> <Export-Package>my.external.pkg</Export-Package> <Import-Package>com.mylibrary,*;resolution:=optional</Import-Package> </bundle-instructions> </plugin-info> <!-- Here is where you define your modules. The code you use --> <!-- to define a module depends on the module itself. This is just --> <!-- a sample, which will not load if installed into Confluence --> <!-- Modules must have a key that is unique within the plugin, a name --> <!-- and an implementing class. --> <example key="module1" name="Example Module" class="com.atlassian.confluence.plugins.example.ExampleModule"> <!-- All modules can optionally have a description --> <description>An example module</description> </example> </atlassian-plugin> Contents of the Plugin DescriptorBelow is a description of the plugin information provided in the descriptor XML file. atlassian-plugin elementThis is the root element for your plugin descriptor. For example, the plugin descriptor file should have this structure: <atlassian-plugin key="com.atlassian.confluence.plugins.example" name="Example Plugin" plugins-version="2"> <!-- ... --> </atlassian-plugin>
plugin-info elementThis element contains plugin information displayed by the application for administrators, plugin parameters and OSGi bundle instructions. Its parent element is <atlassian-plugin>, and it supports several nested elements.
These nested elements are described in more detail below. description elementThe body of this element is a description of your plugin. Its parent element is <plugin-info>. <atlassian-plugin ...> <plugin-info> <!-- ... --> <description>New macros for integration with Acme Corp. web services</description> </plugin-info> </atlassian-plugin> version elementThe body of this element is the current version of your plugin. Its parent element is <plugin-info>. Plugin versions are sometimes compared within an application to determine the newer version, particularly when performing automated upgrades. Versions are compared by splitting the version number into components and comparing them numerically first and alphabetically second. Following are some sample version numbers in ascending order: 0.99, 1.0, 1.0.1-alpha, 1.0.1-beta, 1.0.1-beta2, 1.0.1, 1.0.1.0, 1.1, 1.2, 1.10, 2.0. <atlassian-plugin ...> <plugin-info> <!-- ... --> <version>1.2</version> </plugin-info> </atlassian-plugin> application-version element
Describe which versions of the host application are compatible with this plugin. Enforcement of this property varies between applications: some applications strictly enforce compatibility, while others ignore the value. Its parent element is <plugin-info>.
<atlassian-plugin ...> <plugin-info> <!-- ... --> <application-version min="2.0" max="2.7" /> </plugin-info> </atlassian-plugin> vendor elementThe vendor of the plugin. Provides a link in the plugin administration screens. Its parent element is <plugin-info>.
<atlassian-plugin ...> <plugin-info> <!-- ... --> <vendor name="Acme Systems Ltd" url="http://acme.example.com/" /> </plugin-info> </atlassian-plugin> param elementArbitrary parameters for a plugin. These can be nested in many other elements. Attribute 'name' gives the name of the parameter. The body of the element is its value.
One commonly used parameter is the URL for your plugin's configuration screen. Its parent element is <plugin-info>. Below is an example. <atlassian-plugin ...> <plugin-info> <!-- ... --> <param name="configure.url">/admin/plugins/example/configurePlugin.action</param> </plugin-info> </atlassian-plugin> bundle-instructions elementThis element allows you to declare plugin dependencies and shorten your export package lists by specifying OSGi bundle instructions directly in the plugin XML. The element's parent element is <plugin-info>. <atlassian-plugin ...> <plugin-info> <!-- ... --> <bundle-instructions> <Export-Package>my.external.pkg</Export-Package> <Import-Package>com.mylibrary,*;resolution:=optional</Import-Package> </bundle-instructions> </plugin-info> </atlassian-plugin> As seen in the above example, the bundle-instructions element allows child elements, including:
The Atlassian Plugin Framework uses the bnd tool to generate OSGi bundles. This tool is available as the Bundle Plugin for Maven. For details of the bnd directives, please refer to the bnd documentation. Elements Describing Plugin ModulesIn the rest of the descriptor XML file, you will define any modules that make up your plugin. Please refer to the list of module types for more information. RELATED TOPICS
Information sourced from Plugin Framework documentation |
![]() |
Document generated by Confluence on Nov 05, 2009 23:34 |