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.

NOTE: 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 atlassian-plugin.xml file.

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.
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.


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. 

Default: false.


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.

Default: false.

Macro Elements

The following macro elements contain information specifically for the macro browser. They should be placed inside your <macro> element.




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.
For example if dynamictasklist is an alias of tasklist, editing an existing dynamictasklist macro will open it as a tasklist 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.

*parameters is required.

Macro Categories

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

  • formatting
  • confluence-content
  • media
  • 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 - 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.
Hidden Parameter

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.

Within the atlassian-plugin.xml define a string parameter.

<macro name="example-formatting" key="example-formatting" class=""
    <category name="formatting"/>
        <parameter name="willbehidden" type="string"/>

<web-resource key="hidden-field-parameter" name="Add a hidden field">
    <resource type="download" name="hidden-parameter-field.js" location="js/hidden-parameter-field.js" />

Inside the js/hidden-parameter-field.js

AJS.MacroBrowser.getMacroJsOverride("example-formatting").fields.string = {
  "willbehidden": function(param) {
    var parameterField = AJS.MacroBrowser.ParameterFields["_hidden"] (param, {});
    if (!parameterField.getValue()) {
      parameterField.setValue('hidden field value');
    return parameterField;

Autocompletion on the parameter types may show up that hidden is also a supported type. Keep in mind that choosing this type will not make the field hidden.


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"
  <category name="confluence-content"/>
    <parameter name="spaces" type="spacekey" multiple="true">
      <alias name="space"/>
    <parameter name="labels" type="string">
      <alias name="label"/>
    <parameter name="width" type="percentage" default="100%"/>
    <parameter name="types" type="string">
      <alias name="type"/>
    <parameter name="max" type="int" default="100">
      <alias name="maxResults"/>
    <parameter name="sort" type="enum">
      <value name="title"/>
      <value name="creation"/>
      <value name="modified"/>
    <parameter name="reverse" type="boolean" default="false"/>

WARNING: 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.


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.




Macro label/display name


Macro description


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.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport