Updating macros for the Macro Browser

The Macro Browser is a new feature in Confluence 3.0, helping users to browse and insert macros while adding/editing content. If you are a plugin author, you may want to update your macro so it makes use of the new Macro Browser framework.

Default macro display

Even without updating your plugin, macros will be available in the Macro Browser's 'All' category. As demonstrated in the screenshot below, the vote macro is available with its description displayed.

The insert macro screen will then display:

• a single input field for the parameters
• body text field (only if the macro returns true for hasBody())
• notation help for the macro (only if available)

Updating your macro

However, you may want to update your macro so it behaves correctly in the macro browser and displays the correct parameter input fields. This will require simple changes to your macro definition in the atlassian-plugin.xml file. All of the bundled macros in Confluence 3.0 have been updated in this way.

New Macro Descriptor Attributes

The following are new macro attributes introduced for the macro browser.

New Macro Elements

The following are new macro elements introduced for the macro browser. They should be placed inside your <macro> element.

Macro Categories

The following categories for macros have been defined (see MacroCategory.java). A macro with no category will show up in the default 'All' category.

• formatting
• confluence-content
• visuals
• navigation
• external-content
• communication
• reporting
• admin
• development

Parameter Options

Each <parameter> element must have the following attributes:

• name - A unique name of the parameter, or "" for the default (unnamed) parameter.
• type - The type of parameter. Currently the following parameter types are supported in the macro browser's UI:
  • boolean
  • enum
  • string (this is the default if unknown type)

These are optional:

• required - whether it is a required parameter, defaults to 'false'
• multiple - whether it takes multiple values, defaults to 'false'
• default - the default value for the parameter

It can also have the following optional child elements:

• <alias name="xxx"/> - alias for the macro parameter
• <value name="xxx"/> - describes a single 'enum' value - only applicable for enum typed parameters

例

The following is an example of the Recently Updated Macro defined:

<macro name="recently-updated" key="recently-updated" icon="/images/icons/macrobrowser/recently-updated.png"
documentation-url="http://confluence.atlassian.com/display/DOC/Recently+Updated+Macro">
  <category name="confluence-content"/>
  <parameters>
    <parameter name="spaces" type="spacekey" multiple="true">
      <alias name="space"/>
    </parameter>
    <parameter name="labels" type="string">
      <alias name="label"/>
    </parameter>
    <parameter name="width" type="percentage" default="100%"/>
    <parameter name="types" type="string">
      <alias name="type"/>
    </parameter>
    <parameter name="max" type="int" default="100">
      <alias name="maxResults"/>
    </parameter>
    <parameter name="sort" type="enum">
      <value name="title"/>
      <value name="creation"/>
      <value name="modified"/>
    </parameter>
    <parameter name="reverse" type="boolean" default="false"/>
  </parameters>
</macro>

Note that this example contains parameter types which aren't all supported in the macro browser UI, but may be in future releases.

Macro Icon Example

To provide an icon for your macro -
1) Create a resource for icons/images if you don't already have one. e.g.

<resource key="icons" name="icons/" type="download" location="myplugin/images/icons"/>

This must be a top level resource in your atlassian-plugin.xml and must be defined before the macro.

2) Ensure your plugin should contain the resource directory myplugin/images/icons

3) Set the icon attribute on the macro e.g.

icon="/download/resources/pluginkey/icons/iconfile.png"

i18n Conventions

Instead of having to define i18n keys for each element in the macro definition, the following convention is used to lookup i18n keys for the macro browser.

You will need to place the keys in a .properties file with a resource of type i18n in your plugin.