Support for Server products ended Feb. 15, 2024. Learn what this means for you.

User Macro module

Available:

Confluence 2.3 and later

To create user macros without writing a plugin, define the user macro in the Confluence Administration Console. For more information see Writing user macros.

Adding a user macro plugin

User macro is a kind of Confluence plugin module.

For more information about plugins in general, read Confluence plugin guide.
For an introduction to writing your own plugins, read Writing confluence plugins.

User macro plugin modules

With user macro plugin modules, developers can define simple macros directly in the atlassian-plugin.xml file without writing any additional Java code. User macro plugin modules are functionally identical to user macros configured through the administrative console, except that they can be packaged and distributed in the same way as normal plugins.

User macros installed as plugin modules do not appear in the user macro section of the administrative console, and are not editable from within the user interface. They appear just as normal plugin modules in the plugin interface.

Configuring a macro plugin module

Configure entire macro plugin modules inside the atlassian-plugin.xml file as follows:

1
2
<atlassian-plugin name='Hello World Macro' key='confluence.extra.helloworld' pluginsVersion='2'>
    <plugin-info>
        <description>Example user macro</description>
        <vendor name="Atlassian Software Systems" url="http://www.atlassian.com"/>
        <version>1.0</version>
    </plugin-info>

    <user-macro name='helloworld' key='helloworld' hasBody='true' bodyType='raw' outputType='html'>
        <description>Hello, user macro</description>
        <template><![CDATA[Hello, $body and $paramexample !]]></template>
        <parameters>
            <parameter name="example" type="string"/>
        </parameters>      
    </user-macro>

    <!-- more macros... -->
</atlassian-plugin>

The <template> section is required. It defines the velocity template that renders the macro.
You can find all available velocity variables in Writing user macros tutorial.
The name and key of the macro must be specified the same way as in Macro module.
No class attribute is required.
The attributes of the user-macro element match the configuration for user macros (see available attributes later on this page).
The parameter elements are the same as for xhtml-macro.

If your macro doesn't define any parameter, you should leave <parameters> tag empty.

Available attributes

Attribute	Allowed Values
hasBody	`true` – the macro expects a body (i.e. {hello}World{hello}). `false` – the macro does not expect a body (i.e. Hello, {name}) Default: false.
bodyType	`raw` – the body will not be processed before it is given to the template. `escapehtml` – HTML tags will be escaped before they are given to the template. `rendered` – the body will be rendered as wiki text before it is given to the template. Default: raw.
outputType	`html` – the template produces HTML that should be inserted directly into the page. `wiki` – the template produces wiki text that should be rendered to HTML before it is inserted into the page. Default: html.