Writing the Expand User Macro

This page tells you how to create a user macro that embeds an expandable text box into your page. (For full details about creating a user macro, see the guide to writing user macros.)

A Working User Macro

This is a working user macro that you may want to install onto your Confluence site. In a future release, we intend to bundle this user macro with Confluence. At present, we are making it available on this documentation page so that you can try it out.

Defining the 'Expand' User Macro

To create the 'Expand' user macro,

Go to the Confluence Administration Console and click 'User Macros' in the left-hand panel.
Click the link on the text 'Click here to create a new User Macro' at the top of the list of macros.

Enter the macro attributes as follows:

Macro Name: expand
Visibility: Visible to all users in the Macro Browser
Macro Title: Expand
Description: Embeds an expandable text box into your page
Categories – Formatting
Icon URL: /images/icons/macrobrowser/expand.png
Documentation URL: http://confluence.atlassian.com/x/UBpODQ
Macro Body Processing: Convert wiki markup to HTML
Output Format: HTML

Template:

## @param title:title=Expand Title|type=string|required=false|desc=Title for the text to expand|default=Click here to expand...
##
## Check for a blank first parameter
##
#if ($paramtitle && $paramtitle.length() > 0)
   #set ($expandtitle = $paramtitle)
#elseif ($param0 && $param0.length() > 0)
   #set ($expandtitle = $param0)
#else
   #set ($expandtitle = "Click here to expand...")
#end
#set ($toggleId = $action.random)
#set ($imagePath = "${bootstrap.webAppContextPath}/images/icons")
#set ($imageRight = "$imagePath/arrow_right.png")
#set ($imageDown = "$imagePath/arrow_down.png")

<style type="text/css">
@media all {
    .expand-content { margin-left: 20px; }
    .expand-control-icon { display: inline-block; width: 20px; }
    .expand-control-text { vertical-align: top; text-decoration:none; }
    .expand-control-image { vertical-align: middle; text-decoration:none; }
}
@media screen {
    .expand-hidden { display: none; }
    .expand-control { cursor: pointer; text-decoration: none; }
}
@media print {
    /* show expander text in print */
    .expand-content { display: block !important; }
}
</style>

## In standard display mode we provide JS for opening and closing the div and initially display
## it closed.
#if ($renderContext.outputType == "display")
    ##
    ## Toggle body div and icon when expander clicked or the user hits enter.
    ##
    <script type="text/javascript">
    //<![CDATA[
        // preload open image (variable not used elsewhere)
        new Image().src = "$imageDown";
        function expandmacroExpand(eventee,clickee) {
            var expander = jQuery(clickee),
                expanderImage = jQuery(".expand-control-image", expander),
                expanderContent = expander.next(),
                e = eventee;
            if (e.type == "mouseup" || (e.type == "keyup" && e.keyCode == 13)) {
                if (!expander.hasClass("on")) {
                    // open
                    expanderImage.attr("src", "$imageDown").attr("alt", "Open");
                    expanderContent.fadeIn("fast").removeClass("expand-hidden");
                    expander.addClass("on");
                } else {
                    // close
                    expander.removeClass("on");
                    expanderContent.fadeOut("fast").addClass("expand-hidden");
                    expanderImage.attr("src", "$imageRight").attr("alt", "Closed");
                }
            }
        }
    //]]>
    </script>
    ##
    ## Display: Expanded content is hidden and twixie is pointing right
    ##
    <div id="expander-$toggleId" class="expand-control" onmouseup="expandmacroExpand(event,this)" onkeyup="expandmacroExpand(event,this)" tabindex="0"><span class="expand-control-icon"><img class="expand-control-image" src="$imageRight"></span><span class="expand-control-text">$generalUtil.htmlEncode($expandtitle)</span></div>
    <div class="expand-content expand-hidden">$!body</div>
#else ## For exports etc we want the style to be the same but there's no JS so the content must always be visible
    ##
    ## Display: Expanded content is shown and twixie is pointing down.  There are no events defined.
    ##
    <div id="expander-$toggleId" class="expand-control" tabindex="0"><span class="expand-control-icon"><img class="expand-control-image" src="$imageDown"></span><span class="expand-control-text">$generalUtil.htmlEncode($expandtitle)</span></div>
    <div class="expand-content">$!body</div>
#end

Click 'Save'.

Example and Usage of the 'Expand' Macro on a Page

See the user guide for the Expand macro.

Prerequisites, Limitations and Other Notes

HTML exports do not show the expanded text. When you export the page to HTML, the text between the macro tags is not visible. Nothing happens when readers click the 'expand' icon. This issue is logged as CONF-21315. If you like, you can vote for the issue or 'watch' it to keep informed of progress.

Text is expanded in PDF exports. When you export the page to PDF, the text between the macro tags is expanded so that readers can see it on the PDF page. If this is not working on your Confluence site, please ask your administrator to get the latest version of the macro 'template' above.

This macro is not bundled with Confluence. If you are interested, you can consider watching and voting for this issue: CONF-2803.

Page tree

A Working User Macro

Defining the 'Expand' User Macro

Example and Usage of the 'Expand' Macro on a Page

Prerequisites, Limitations and Other Notes

RELATED TOPICS