Example User Macro - Formatted Panel

This example demonstrates how to write a user macro that creates a panel that is preformatted with specific colours. It will create a panel that looks like this:

(Title)

 

Note: The panel's title will be empty if the user does not give a value for the title parameter.

Before you start, see Writing user macros for an introduction to creating your own user macros. 

Defining the 'Formatted Panel' user macro

To create the 'Formatted Panel' user macro:

  1. Go to  > General Configuration > User Macros.
  2. Choose Create a User Macro.
  3. Enter the macro details (see table below)
  4. Choose Add.

Field Value
Macro name formpanel
Visibility Visible to all users in the Macro Browser
Macro Title Formatted Panel
Description Creates a panel preformatted with specific colours
Categories Formatting
Icon URL You can leave this field blank
Documentation URL You can leave this field blank
Macro body processing Escaped
Template

Enter the code below in the template field. See below for a more detailed explanation of the code below.

## @param Title:title=Title|type=string|desc=Title
<ac:structured-macro ac:name="panel">
        <ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
        <ac:parameter ac:name="borderStyle">solid</ac:parameter>
        <ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
        <ac:parameter ac:name="borderWidth">2</ac:parameter>
        <ac:parameter ac:name="titleColor">#000000</ac:parameter>
    <ac:parameter ac:name="title">$!paramTitle</ac:parameter>
    <ac:rich-text-body>$body</ac:rich-text-body>
</ac:structured-macro>

Explanation of the code in the macro template

Below is a breakdown of the user macro template code. 

Item Description
## @param Title:title=Title|type=string|desc=Title

@param defines the metadata for your macro parameters.

@param Title

This parameter is called "Title".

title=Title

defines the parameter title that will appear in the macro browser as "Title".

type=string

defines the field type for the parameter as a text field.

desc=Title

defines the description of the parameter in the macro browser.

<ac:structured-macro ac:name="panel">

This calls the Confluence Panel macro.

The easiest way to find out the code name of a Confluence macro by viewing the Storage Format of a page containing the macro. You'll need Confluence Administrator permissions to view the storage format.

<ac:parameter ac:name="titleBGColor">#ccc</ac:parameter>
<ac:parameter ac:name="borderStyle">solid</ac:parameter>
<ac:parameter ac:name="borderColor">#6699CC</ac:parameter>
<ac:parameter ac:name="borderWidth">2</ac:parameter>
<ac:parameter ac:name="titleColor">#000000</ac:parameter>

Sets the parameters for the macro: the background colour, border style, border colour, border width and title colour.

To discover the names of the parameters for a Confluence macro, view the storage format as described above.

<ac:parameter ac:name="title">$!paramTitle</ac:parameter>

Enters the value stored in the 'Title' parameter into the title section of the macro.

The ! tells the macro to leave the title blank, when there is no data in the "Title" parameter.

<ac:rich-text-body>$body</ac:rich-text-body>

Users can enter data that is stored in the body of the macro. This line enables the macro to access and store the body content passed to your macro.

</ac:structured-macro>

This command marks the end of the macro.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport