Confluence 3.5 : Writing User Macros
This page last changed on Oct 11, 2010 by smaddox.
User macros are short pieces of code that perform an often-used function or add some custom formatting to a page. People can call the macro into action by adding the macro keyword to their Confluence pages. You can write a user macro by adding code on a screen in the Confluence Administration Console. You need to have System Administrator permissions in order to create user macros.
On this page: Creating a User MacroTo create a user macro,
The sections below tell you about each of the input fields. Macro NameEnter the text that you and other users will type, within curly brackets, to invoke the macro from within a page. For example, if you enter a macro name of 'status', then you would enter the following wiki markup on a Confluence page to invoke the macro: {status} Partial screenshot: Entering the macro name when creating a user macro VisibilitySet the visibility options to specify who can see this macro when they are searching via the Macro Browser or Autocomplete. The options are as follows:
Partial screenshot: Visibility Macro TitleEnter the text that should appear in the Macro Browser and in Autocomplete, to identify this macro when people are looking for it to insert onto a page. Partial screenshot: Macro Title DescriptionEnter the text that should appear in the Macro Browser describing this macro. Note that the Macro Browser's search will pick up matches in the description as well as in the title. Partial screenshot: Macro Description CategoriesSelect one or more categories for your macro. To select more than one category, hold down the 'Ctrl' key while selecting. These are the categories that appear in the Macro Browser, helping users to choose a macro from a logical set. Partial screenshot: Macro Categories Icon URLIf you would like the Macro Browser to display an icon for your macro, enter the URL here. You can enter an absolute URL or a path relative to the Confluence base URL. For example:
Partial screenshot: Icon URL Documentation URLEnter the URL pointing to the online help or other documentation for your macro. Partial screenshot: Documentation URL Macro Body ProcessingSpecify how you want Confluence to process the body of your macro before passing it to your macro. Below is an explanation of the macro body and the options available. What is the macro body?The macro body is the content on the wiki page between the macro start tag and end tags. If the macro allows a body, users will be able to enter content into the macro body. How can I use the macro body?If you specify that your macro has a body, you will be able to pass text to the macro when you invoke it from within a page. For example: {expand}My expandable/collapsible text.{expand} If your macro has a body, anything the user types within the body of the macro will be available to the macro in the $body variable. See the section about the template below. In addition, the options below allow you to tell Confluence to pre-process the body before it is placed in the macro output. What are the options for macro body?
Partial screenshot: Macro Body Processing Output FormatSelect the markup format that you will use when coding the macro processing in the macro template (see below). If you want to code in HTML (Velocity), select HTML. If you want to code in wiki markup, select that. Note: If you select the macro body processing option of 'Convert wiki markup to HTML' with an output format of 'Wiki Markup', you will get unexpected results. The rendered HTML is escaped, as if the user had typed HTML into the page. Partial screenshot: Output Format_ TemplateEnter code to specify what the macro will do. Quick guide:
See our detailed guide to writing a user macro template. Examples and Best PracticesSee:
RELATED TOPICSDeveloper documentation: Library of user-contributed user macros |
![]() |
Document generated by Confluence on Mar 16, 2011 18:31 |