This documentation relates to the latest version of Confluence.
If you are using an earlier version, please go to the documentation home page and select the relevant version.

User Macro Plugins

Added by Charles Miller, last edited by Jonathan Nolen on Jan 17, 2007  (view change)
All Versions
Click for all versions
Confluence 2.9 Documentation

Index
You can create user macros without writing a plugin through the User Macros administration menu.

Adding a user macro plugin

User Macros are a kind of Confluence plugin module.

User macro plugin modules are available in Confluence 2.3 or later

User Macro Plugin Modules

User macro plugin modules allow plugin developers to 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 by 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

Macro plugin modules are configured entirely inside the atlassian-plugin.xml file, as follows:

<atlassian-plugin name='Hello World Macro' key='confluence.extra.helloworld'>
    <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!]]></template>
    </user-macro>

    <!-- more macros... -->
</atlassian-plugin>
  • The <template> section is required, and defines the velocity template that will be used to render the macro
  • All the velocity variables available in User Macros are available in user macro plugin modules
  • The name and key of the macro must be specified the same as Macro Plugins
  • No class attribute is required
  • The attributes of the <user-macro> element match the corresponding configuration for user macros:

Available Attributes

Attribute Required Default Value Allowed Values
hasBody No false
  • true – the macro expects a body (i.e. {hello}World{hello})
  • false – the macro does not expect a body (i.e. Hello, {name})
bodyType No raw
  • raw – the body will not be processed before being given to the template
  • escapehtml – HTML tags will be escaped before being given to the template
  • rendered – the body will be rendered as wiki text before being given to the template
outputType No html
  • 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 being inserted into the page

Labels:

macro macro Delete
plugin plugin Delete
usermacro usermacro Delete
developer developer Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Comments (4)

 

  1. Sep 12, 2007

    James Mortimer says:

    once I have my atlassian-plugin.xml file, how do I package this as a plugi...
    • once I have my atlassian-plugin.xml file,
      • how do I package this as a plugin and deploy it to my server?
      • how do I package it so that it shows up in the plugin repository for others to use?

    1. Jun 29

      Anonymous says:

      This is described in Writing Confluence Plugins.

      This is described in Writing Confluence Plugins.

  2. Jul 23

    Anonymous says:

    HI  I also want Help For UserMacro ,so that That Help File description can...

    HI

     I also want Help For UserMacro ,so that That Help File description can include in NOTATION GUIDE .

    For Plugins Macros , There is xml tag in atalassian-plugin.xml file

     

    <resource type="velocity" name="help" location="templates/extra/layout/notemacro-help.vm">
        <param name="help-section" value="advanced"/>
    </resource>
     

    \\ <macro name='note' class='com.atlassian.confluence.extra.information.NoteMacro' key='note'>
    <description>Draws a note (yellow).</description>
    <resource type="velocity" name="help" location="templates/extra/layout/notemacro-help.vm">
        <param name="help-section" value="advanced"/>
    </resource>
</macro>
     

    I tried that code in UserMacro but it is not working ........ dont know why ??? anything wrong or  is there any other procedure  

    1. Jul 25

      Azwandi Mohd Aris says:

      Hi there, I believe you have followed the instructions in the following page: ...

      Hi there,

      I believe you have followed the instructions in the following page:

      If that is the case, please ensure that notemacro-help.vm is located in the right path, as in templates/extra/layout/ directory of your JAR. Hope that helps.

      Cheers,
      Azwandi

Add Comment