Event Listener module
Job module
Language module
Macro Module
Theme module
Web UI modules
Workflow module

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, this page provides details on how to make use of the new Macro Browser framework.

Starting from Confluence 4.0, all macros must contain metadata to function correctly in Confluence.

Including Macro Browser information in your macro

To make sure your macro appears and behaves correctly in the Macro Browser, and displays the correct parameter input fields, you need to make 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.

Name

Description

documentation-url

The absolute URL pointing to the macro documentation.

icon

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.

hide-body

This attribute is available for macros that falsely declare that they have body (most likely because 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.

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.

Default: false.

Macro elements

The following macro elements contain information specifically for the Macro Browser. They should be placed inside your <xhtml-macro> element.

Name*

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.

*parameters is a required element.

Macro categories

The following categories for macros are defined (see MacroCategory). 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:

The following parameter attributes are optional:

  • required — use to mark parameter as required, defaults to 'false'.
  • multiple — use to mark that parameter may have several values, defaults to 'false'.
  • default — use to define 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

To send information along with your form, you can define a hidden parameter, which will be invisible for users. Take a look at the following examples on how to define this.

  1. In the atlassian-plugin.xml, define a string parameter:

    1
    2
    <xhtml-macro name="example-formatting" key="example-formatting" class="some.path.ExampleFormatting.java"
           icon="/download/resources/${atlassian.plugin.key}/images/example-formatting.png">
        <category name="formatting"/>
        <parameters>
            <parameter name="willbehidden" type="string"/>
        </parameters>
    </xhtml-macro>
    
    <resource type="download" name="images/" location="images">
        <param name="content-type" value="image/png"/>
    </resource>
    
    <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" />
        <dependency>confluence.editor.actions:editor-macro-browser</dependency>
        <context>macro-browser</context>
    </web-resource>
    
  2. Inside the js/hidden-parameter-field.js, add the following:

    1
    2
    AJS.MacroBrowser.setMacroJsOverride("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.

Example of parameter use

The following code is an example of parameter use:

1
2
<xhtml-macro name="example-parameters" documentation-url="http://docs.example.com/some/path"
       class="some.path.ExampleFormatting.java" key="example-parameters">
       <category name="confluence-content"/>
       <parameters>
           <parameter name="users" type="username" multiple="true"/>
           <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="15">
               <alias name="maxResults"/>
           </parameter>
           <parameter name="theme" type="enum">
               <value name="concise"/>
               <value name="social"/>
               <value name="sidebar"/>
           </parameter>
           <parameter name="showProfilePic" type="boolean"/>
           <parameter name="hideHeading" type="boolean"/>
       </parameters>
   </xhtml-macro>

Note that the previous example contains parameter types that 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, perform the following steps:

  1. Create a resource for icons/images if you don't already have one. e.g.

    1
    2
    <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 contains the resource directory myplugin/images/icons.

  3. Set the icon attribute on the macro. For example:

    1
    2
    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 look up 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.

Rate this page: