Confluence Docs 3.0 : Documenting Macros This page last changed on Jun 02, 2009 by agnes@atlassian.com.
| This document is for the notation guide only. Please also see updating macros for the Macro Browser.
The Confluence notation guide is the popup window that describes all the markup and macros available within a Confluence installation. Obviously, if a macro is installed, you will want it to also appear in the notation guide. To do this you will need to: Write a help file Tell Confluence where to find that help file ### Writing the Help File The help file is a file containing a fragment of HTML. Your HTML will be inserted into a two-columned table, so you should provide a single table row with two columns. On the left-hand side, put usage examples of your macro. On the right hand side provide a description and sample output. The file will be rendered through Velocity, which means useful things like $req.contextPath are available to you. Here's an example of the help file used for the {note} macro:
    <tr bgcolor=ffffff>
      <!-- The left-hand table cell should contain usage examples -->
      <td>
        {note:title=Be Careful}<br />
        The body of the note here..<br />
        {note}
      </td>

      <!-- The right-hand cell describes the macro and its available arguments -->
      <!-- and may include sample output -->
      <td>
        <p>
          Prints a simple note to the user.

        <!-- Provide a list of all possible macro arguments -->
        <ul>
          <li><b>title:</b> - (optional) the title of the note.</li>
          <li><b>icon:</b> - (optional) if "false", don't display the icon.</li>
        </ul>
        </p>

        <!-- This is the sample output -->
        <div align='center'><div class='informationMacroPadding'>
        <table cellpadding='5' width='85%' cellspacing='0' class='noteMacro' border='0'>
        <tr><td width='16' valign='top'>
        <img src="$req.contextPath/images/icons/emoticons/warning.png" width="16"
         height="16" align="absmiddle" alt="" border="0"></td><td>
         <b class="strong">Be Careful</b><br /><br/>
         The body of the note here.. $req.contextPath/images/icons/emoticons/warning.png
         </td></tr></table></div></div>
        </td>
    </tr>
### Configuring the help file in your macro The help file is included in your macro as a plugin resource of type "velocity" and name "help". Here's the plugin definition of the note macro, including its help file:
    <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>
The "help-section" parameter is optional, and determines which section of the notation guide the macro will be documented in. The following sections are available (Note that regular wiki markup is also defined in here, so some sections like 'breaks' are unlikely to be appropriate for any real macro):
texteffects | Macros that change the appearance of text contained within them (e.g. {color})
headings | Macros that create headings within a page
breaks | Macros related to line- or paragraph breaks, or rulers
links | Macros related to links to other wiki or external content (e.g. {anchor})
lists | Macros related to lists
images | Macros for inserting or manipulating images within a page (e.g. {gallery})
tables | Macros for forming static tables (e.g. {section} and {column})
advanced | Macros for creating more complex structures in a page (e.g. {panel} or {info})
confluence | Macros for manipulating or displaying Confluence data (e.g. {children})
external | Macros for manipulating or displaying data from other systems (e.g. {rss})
misc | Macros that do anything else (Try to avoid using this section)
If you don't provide a help section, your macro documentation will appear in the "Macros" section of the notation guide. (This section only appears in the notation guide if it is needed).

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