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.

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.

Macro elements

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

*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:

• name — A unique name of the parameter, or "" for the default (unnamed) parameter.
• type — The type of parameter (see MacroParameterType). Currently the following parameter types are supported in the Macro Browser UI:
  • boolean — displays a check box.
  • enum — displays as a drop-down.
  • string — displays an input field (this is the default if type is unknown).
  • 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.

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;
               }
           }
       }
   });
   

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>

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.

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