Confluence Docs 3.0 : User Macros This page last changed on Jul 02, 2008 by mike@atlassian.com. User macros allow you to create simple formatting macros using the Confluence web interface.
| User Macro Plugins and Macro Plugins If you want to distribute your user macro as a plugin, please see User Macro Plugins. If you want to create more complex, programmatic macros in Confluence, you may need to write a Macro Plugin. Note also that Macro Plugins and User Macro Plugins can appear in the Confluence Notation Guide, whereas User Macros do not. Here is an example of the Confluence Notation Guide.
- You need to have System Administrator permissions in order to create user macros. On this page: Creating a User Macro Examples Example 1: User Macro to Create a Red Box Example 2: User Macro to Display 'Hello World' Example 3: User Macro to Demonstrate the Use of Parameters Available Objects User Macro Library ## Creating a User Macro To create a user macro, Go to the 'Administration Console' and click 'User Macros' in the left-hand panel. Click 'Create a User Macro' at the top of the list of macros. Supply the information in the input fields as explained below, then click the 'Save' button. Screenshot: Creating a User Macro Input fields: 'Macro Name' — Enter the text that you will type, within curly brackets, to invoke the macro from within a page. For example, to invoke the 'floatright' macro defined in the above screenshot, you would type:
      {floatright}
- 'Macro has a body' — Check this box if you will pass body-text to the macro when you invoke it from within a page, e.g. :
      {floatright}my text{floatright}
If you select 'Macro has a body', anything the user types within the body of the macro will be available in the macro in the `$body` variable. The options below allow you to tell Confluence to pre-process the body before it is placed in the macro output: Use unprocessed macro body — The body of the macro will be output exactly as entered, including any HTML markup. For example if the macro body is <b>body</b>, it will be displayed as body in the page. Escape HTML in macro body — The body of the macro will be output with HTML markup escaped. So if the macro body is <b>body</b>, it will be displayed as <b>body</b> in the page. Convert macro body wiki markup to HTML — The body of the macro will be converted from wiki text to HTML markup. So if the macro body is *body*, it will be displayed as body in the page. 'Output' — Choose one of the following options: 'Macro generates HTML markup' — Choose this if you wish to write your Template in HTML markup (as shown in the above screenshot). 'Macro generates wiki markup' — Choose this if you wish to write your Template in wiki markup. 'Template' — This specifies what the macro will do. Write this using the Velocity templating language. Here is more information on the Velocity project. Note: If you ticked Macro has a body, your template can refer to the body-text by specifying `$body`. ## Examples #### Example 1: User Macro to Create a Red Box As an example, let's write a simple macro that simply creates a red box (using an existing Confluence style) around some text (useful for writing about error conditions for example - hence the macro name 'error'). After clicking "New User Macro", enter `error` as the Name of your macro, and then put the following in the Template text area:
    <div class="errorbox">$body</div>
Then click Add. You should now see your new macro in the User Macros library, and you can now enable and disable it individually. To use the macro within a page, you would add notation like:
    {error}This is bad{error}
And your page would (magically!) have an error box on it, like so: This is bad #### Example 2: User Macro to Display 'Hello World' Take a look at an example of a 'Hello World' macro. #### Example 3: User Macro to Demonstrate the Use of Parameters This example demonstrates how you can pass parameters into your macro. Let's say you want to write your own font colour macro:
    <span style="color: $param0">$body</span>
The usage of this macro would be:
    {colour:red}Some example text{colour}
which will produce: Some example text If your macro requires more than one parameter, you can use variables $param0 to $param9 to represent them. To specify multiple parameters, use:
    {colour:red|blue|green}
Where red, blue and green are the 1st, 2nd and 3rd parameters respectively. Alternatively, you can also use explicitly named parameters in your macro. These macro parameters will appear as variables with the name $param<x> where <x> is the name of your parameter. To specify named parameters, use:
    {style:colour=red}
In your user macro you can then use `$paramcolour` which will have the value `red` in this case. ## Available Objects The user macro above uses the `$body` object, which is available for use within your user macro template if the macro has a body. You can pass parameters to your user macro in the same way as any other macro, separated by the pipe | sign. These parameters are provided to your template as `param1`, `param2`, ... `paramN`. The complete list of objects available for use are:
Name | Description | Doc Reference
--- | --- | ---
$body | The body of the macro (if the macro has a body) |
$param0-n | The parameters passed to your macro (as available) |
$param<name> | Named parameters passed to your macro (as available) |
$config | The `BootstrapManager` object, useful for retrieving Confluence properties | BootstrapManager
$content | The current `ContentEntity` object that this macro is a included in (if available) | ContentEntityObject
$space | The `Space` object that this content object is located in (if relevant) | Space
$generalUtil | A `GeneralUtil` object, with useful utility methods for URL encoding etc | GeneralUtil
$action | A blank `ConfluenceActionSupport` object, useful for retrieving i18n text if needed | ConfluenceActionSupport
$webwork | A `VelocityWebWorkUtil` object, for its htmlEncode() method | VelocityWebWorkUtil
$req | The current `HttpServletRequest` object (if the page is rendered as a result of an HTTP request) | HttpServletRequest
$res | The corresponding `HttpServletResponse` object (not recommended to be played with) | HttpServletResponse
$userAccessor | For retrieving users, groups and checking membership | UserAccessor
$permissionHelper | For determining user rights | PermissionHelper
| Velocity Context in Exporters The above context is not inherited by the Velocity context created for PDF or Word exports. To see the available objects in that context, see this page.
Normally, a parameter like $param2 that is missing will appear as '$param2' in the output. To display nothing when a variable is not set, use an exclamation mark after the dollar sign like '$!param2'. You can read more about object usage in the Velocity Template Overview. ## User Macro Library Below is a list of existing user macros, written by other Confluence users. If you wish, you can install these on your Confluence site.
| Be careful when installing user macros from unknown authors
Popup when over page element — Allows to create a popup for adding a word definition or anything else Show Page Name as Link — Shows the page name as a link. Side Toggle User Macro — This user macro embeds an expandable table column, which means expandable side bar. It is extended from Expand Test User Macro. Space access — Shows the users who has access permissions. umc-link-window css style-able link macro — Limited alternative to {link-window} supporting css style reference for link that pops up in new window User Activity — Display a table of user activity for a space. Add Tool Tip to Normal Text — Display tool tip over hovered text. Automatically label news post — Automatically labels news post items by the desired label (or labels). Bookmark Icons — displays an icon toolbar to link the current page on del.icio.us, Digg and other bookmarking services. Calling Attention to Page Content — Sometimes, there is content on your page that you want people to see but you want to reference it elsewhere on your page. The {callattention2} macro makes this an easy 2 step process. Count pages in space — Automatically counts the number of pages in the space. Create link with underline only on hover — Display underline for link only when hovering. DailyMotion user macro — Allows users to easily embed DailyMotion videos within Confluence Display trackback — Display all trackbacks of current page. Drop Shadows User Macro — Automatically add cross-browser, cross-platform drop-shadows to your panels... editable user macro edit-include user macro — Creates an seperately editable subsection of a page by implementing {include}, {link-to} and {link-page} macros. A user macro workaround. Escape User Macro Expand Text User Macro — This user macro embeds an expandable text box into your page. Flash Video user macro — Allows users to embed flv videos within Confluence Font Size — Change the font size Gadget User Macro — A simple user macro to embed Google gadgets. Get your gadgets from the Google Directory. icq-time User macro — Displays an ICQ user's local time using a groovy animated Flash widget... include_permissionchecked user macro — When including a page where user has no permission to view you get an ugly red error hint Indent User Macro — Easily indent content Install Search Engine user macro — Add a link allowing to install a OpenSearch engine in your browser. Link to this page name in a different space — Link to a page of this page's name in a specific space. Link with colour — Display a link in a different colour. MacroDocumentation user macro — Easily explain your usermacros to your authors how to use with code example and rendered view. Mailto User Macro — Renders a block of text as a mailto, using urlencode to convert spaces and newlines properly. New Window User Macro — Make links open in a new window No-Export macro — A simple user macro to prevent the enclosed text from being exported to PDF, Word of HTML. Particular useful exported manuals or documentation. no-include User Macro nomarkup macro — Render plain text with no wiki markup notation Obfuscate email addresses — Obfuscate email addresses on public pages using javascript Page Title Style — Apply custom style to the page title. Profile Image Macro — This user macro can be used to insert a user profile image or space logo easily into any Confluence page. Related Content User Macro — A simple user macro to automatically generate related content based on the labels on the page. This macro wraps the {content-by-label} macro, pulling the labels directly from the page. If no labels are specified, the macro simply doesn't render anything. Rich Text Editor in Scaffolding — Enable the Rich Text Editor in your Scaffolding textareas. Round Rectangle Macro — Macro for creating rounded rectangles Show Page Source Inline Macro — Display the source code of your page within the page itself. Helpful for showcasing your wiki coding mastery. Show the content ID (page ID) in a page — Allows display of the page's Content ID - the unique ID field of the page. Show-to User Macro — The show-to-authenticated and show-to-anonymous user macros provide a quick way to show content to only authenticated or anonymous users. (OBSOLETE) Simple approvals — A simple script to mark a version of a page as approved Space List Pulldown Menu — Creates a pulldown menu of spaces based on a given tag space-permissions user macro — Creates a summary table for the permissions assigned to the current space. Spaces listed by label — List all Spaces (Name and Link) by a defined space label (if exists). SVG Image Macro SVG Image User Macro — A simple user macro to embed scalable vector graphics in wiki pages. You need to install a browser plugin, such as Adobe, to get it to work. Team Macro — create a formatted table of users Twitter — shows the latest three twitter posts Typewriter text effect - User Macro — This user macro allows you to add a typewriter text effect to your content, adding one letter at a time until the text is fully displayed... Under construction macro — Simple macro to warn people a page is being worked on User Macro Snippets — Snippets, tools and standards for writing user macros User Profile Quick Jump Macro — Allows to quick jump to a user profile based on its id. Version Macro — Allows to display the current version of the page. Video and Audio Embed Macro With Autoplay Disabled Word to Confluence Converter YouTube user macro — Allows users to easily embed YouTube videos within Confluence ##### RELATED TOPICS User Macro Plugins Macro Plugins Confluence Plugin Guide Attachments: create-user-macro.PNG (image/png)

Document generated by Confluence on Nov 05, 2009 23:34