Including Information in your Macro for the Macro Browser
The Macro Browser helps users to browse and insert macros while adding or editing content. If you are a plugin author, you need to include metadata in your macro so that works correctly and makes use of the new Macro Browser framework.
As of Confluence 4.0, all macros must contain metadata in order to function correctly in Confluence.
Including Macro Browser Information in your Macro
You need to include information in your macro so that it appears and behaves correctly in the macro browser and displays the correct parameter input fields. This will require simple additions to your macro definition in the
Macro Descriptor Attributes
The following macro attributes contain information specifically for the macro browser.
The absolute URL pointing to the macro's documentation.
The relative URL to the application for the macro icon. To display well in the macro browser, the image should be 80 pixels by 80 pixels, with no transparency.
This attribute is available for macros that falsely declare that they have body (most likely cause they extend BaseMacro) when they don't.
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.
The following macro elements contain information specifically for the macro browser. They should be placed inside your
The category the macro should appear in. Valid categories are listed below.
Defines an alias for the macro. This means that the macro browser will open for the defined aliases as if it were this macro.
Defines a group of parameter elements. See example below.
This defines a single macro parameter. It must be an element of the parameters element. Its contents are described below.
The following categories for macros have been defined (see MacroCategory.java). A macro with no category will show up in the default 'All' category.
<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- displays a check box.
enum- displays a select field.
string- displays an input field (this is the default if unknown type).
spacekey- displays an autocomplete field for search on space names.
attachment- displays an autocomplete field for search on attachment filenames.
username- displays an autocomplete field for search on username and full name.
confluence-content- displays an autocomplete field for search on page and blog titles.
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.
It is possible to define a hidden parameter, to send information along with your form, invisible for users to see. Take a look at the examples below how to define this.
atlassian-plugin.xml define a
The following is an example of the Recently Updated Macro defined:
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.
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.
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.
Macro label/display name
Macro parameter label
Macro parameter description
Macro body label (defaults to 'Body Text' if not provided)
Macro body description
You will need to place the keys in a .properties file with a resource of type i18n in your plugin.