This page last changed on Oct 23, 2009 by pcurren.

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.

Name Description
Default
documentation-url
The absolute url to the macro's documentation.
 
icon
The relative url to the application for the macro icon.
Note: if you have your icon defined as a downloadable resource, you can refer to this by specifying "/download/resources/PLUGIN_KEY/RESOURCE_NAME" as the icon attribute.
 
hide-body
This attribute is available for macros that falsely declare that they have body (most likely cause they extend BaseMacro) when they don't.
For example the gallery macro. This attribute helps hide the body text field in the macro browser. 
false
hidden
If set to true, the macro is not visible in the macro browser for selection. Plugin authors may want to hide macros that are for their plugin's internal use and shouldn't really be used by users. Note that the parameter does not stop people from inserting a macro via the normal editor though.
false

New Macro Elements

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

Name Required Description
category   The category the macro should appear in. Valid categories are listed below.
alias   Defines an alias for the macro. This means that the macro browser will open for the defined aliases as if it were this macro.
For example if dynamictasklist is an alias of tasklist, editing an existing dynamictasklist macro will open it as a tasklist macro.
parameters Defines a group of parameter elements. See example below.
parameter   This defines a single macro parameter. It must be an element of the parameters element. Its contents are described below.

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

Example

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.

Key Description
{pluginKey}.{macroName}.label Macro label/display name
{pluginKey}.{macroName}.desc Macro description
{pluginKey}.{macroName}.param.{paramName}.label Macro parameter label
{pluginKey}.{macroName}.param.{paramName}.desc Macro parameter description
{pluginKey}.{macroName}.body.label Macro body label (defaults to 'Body Text' if not provided)
{pluginKey}.{macroName}.body.desc Macro body description

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


AllTab.jpg (image/jpeg)
Vote_Macro.jpg (image/jpeg)
Document generated by Confluence on Nov 05, 2009 23:34