Confluence Docs 3.0 : Updating macros for the Macro Browser 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. Attachments: AllTab.jpg (image/jpeg) Vote_Macro.jpg (image/jpeg)

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