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 Descriptor Example of a Plugin Descriptor Contents of the Plugin Descriptor `atlassian-plugin` element `plugin-info` element `description` element `version` element `application-version` element `vendor` element `param` element `bundle-instructions` element Elements Describing Plugin Modules ## Purpose of a Plugin Descriptor When 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 Descriptor Here 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 Descriptor Below is a description of the plugin information provided in the descriptor XML file. #### `atlassian-plugin` element This 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>
Attribute | Description
--- | ---
key | Each plugin has a plugin key which must be unique to the plugin. We suggest using the Java convention of reversing your domain name in order to ensure your key is unique. The plugin key must be defined in lower case in the plugin descriptor. When you call the plugin via a macro in Wiki Markup, you can use any capitalisation, e.g. {module1} or {Module1}. Within the plugin, each module has a module key. Refer to the information on module types for information about the module key.
name | This is a human-readable name, used for display in menus within the application.
state | To disable the entire plugin by default, specify `<atlassian-plugin state="disabled"/>`.
plugins-version | To create an OSGi plugin, use `plugins-version="2"`. The attribute `pluginsVersion` is still supported but has been deprecated since version 2.1 of the plugin framework.
#### `plugin-info` element This 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.
Nested element | Description
--- | ---
<description> | A human-readable description of your plugin.
<version> | The version of your plugin. This number is displayed in the application's plugin manager.
<application-version> | Supply the versions of the application that will support your plugin.
<vendor> | Supply information about the developer of the plugin.
<param> | Supply parameter values if required by your plugin.
<bundle-instructions> | Declare plugin dependencies and shorten your export package lists by specifying OSGi bundle instructions directly in the plugin XML (OSGi plugins only).
These nested elements are described in more detail below. #### `description` element The 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` element The 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
| Deprecated since Atlassian Plugin Framework 2.2
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>`.
Attribute name | Description
--- | ---
min | This is the lowest version of the application which your plugin is compatible with.
max | This is the highest version of the application which your plugin is compatible with.
    <atlassian-plugin ...>
        <plugin-info>
            <!-- ... -->
            <application-version min="2.0" max="2.7" />
        </plugin-info>
    </atlassian-plugin>
#### `vendor` element The vendor of the plugin. Provides a link in the plugin administration screens. Its parent element is `<plugin-info>`.
Attribute name | Description
--- | ---
name | Supply your name or the name of the company you work for.
url | Supply a web site address.
    <atlassian-plugin ...>
        <plugin-info>
            <!-- ... -->
            <vendor name="Acme Systems Ltd" url="http://acme.example.com/" />
        </plugin-info>
    </atlassian-plugin>
#### `param` element Arbitrary 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.
Attribute | Description
--- | ---
name | The name of the parameter.
(body) | The value of the parameter.
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` element This 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: `<Export-Package>` `<Import-Package>` 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 Modules In 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 Writing Confluence Plugins Enabling TinyMCE Plugins Converting a Plugin to Plugin Framework 2 Creating your Plugin Descriptor Confluence Plugin Module Types Accessing Confluence Components From Plugin Modules Including Javascript and CSS resources Adding Plugin and Module Resources Adding a Configuration UI for your Plugin Ensuring Standard Page Decoration in your Plugin UI Making your Plugin Modules State Aware Confluence Plugin Tutorials Form Token Handling Information sourced from Plugin Framework documentation

Document generated by Confluence on Nov 05, 2009 23:34