This user macro embeds an expandable text box into your page .
An XSS vulnerability was found on early versions of this user macro. Please make sure you upgrade to version 1.3 |
Example
Usage
Edit a page in Wiki Markup mode and embed the following text
{expand:Are you writing a FAQ-style series of entries?}
The answer can now pop out when the users clicks on it.
{expand}
- The title cannot include wiki markup or cover multiple lines
- Create a panel by embedding the {panel} macro in the text body
- anchors are created to allow hyperlinking to expandable sections (does not affect expanded state)
- for example: Are you writing a FAQ-style series of entries? - Expandable Text
Installation
Versions and Compatibility Matrix
| Version | Authors | Description / Confluence Compatibility | 1.4.0 | 2.10 | 2.3.3 | 2.5.7 | 2.7.x | 2.8.2 | 2.9.x |
|---|---|---|---|---|---|---|---|---|---|
| Current | ? | ? | ? | ? | ? | |
|||
| see comments | Julie Leung | fixes expand button in preview mode by inserting javascript in global html ( incompatible with Tim's fix below) |
|
|
|
|
|||
| 1.3.1 | Tim Moore | fixes depricated '$action.random' dependency, ( breaks Julie's feature above) |
|
||||||
| 1.3 | Roberto Dominguez | Added context path in images sources and html encoded title | |
|
|
||||
| 1.2 | James Mortimer | changed function names to avoid conflict with 'toggle' function in {attachments} macro (reported by Guy) | |
|
|
||||
| 1.1 | James Mortimer | introduced code to use renderer that is backwards compatible with confluence 2.10 | |
|
|
||||
| 1.0 | David Soul [Atlassian] | original version | |
|
|
= works, but requires extra code for '#render()' velocity template
Instructions
You must be a Confluence administrator to install this plugin.
- From Confluence, go to 'Administration -> User Macros'
- Select 'Create a new user macro'
- Set 'Macro Name' to 'expand'
- Select 'Macro has a body'
- Select a rendering mode, depending on your version of Confluence
- If you are on confluence versions prior to 2.3.3 (i.e. 2.10)
- add the velocity template code from this page at the TOP of the user macro 'Template' field"\: Render user macro wiki body in confluence prior to 2.3.3
- For version 2.3.3 and later
- Select 'Convert macro body wiki markup to HTML'
- Select 'Macro generates HTML markup'
- If you are on confluence versions prior to 2.3.3 (i.e. 2.10)
- For all versions, add (or append) the velocity script below into 'Template' and select 'Save': Expand Text User Macro Source
- you may choose to use the code from an earlier version from the compatibility table above.
Feature Requests
Needs to:
- detect if we are in 2.3, if so, skip the first code block
- detect if we are in preview or template modes. If so, we need to do a different renderer (currently, throws error in preview mode if the page does not yet exist, probably because of the getRealTitle)
- work in preview mode, or at the least, detect if in preview mode, and if so, display the page with all sections expanded, by default (Julie's feature in the comments permits this)
Related Macros
The Toggle-Cloak Macro bundled with the Composition Plugin offers more advanced functionality such as
- Multiple titles may open one panel
- The panel no longer needs to be beneath the title
- Optionally allowing only one panel open at a time

Comments (51)
Jan 09, 2007
Audrey M. Schaffer says:
Is it possible it use the expand macro on things other than plain text, such as ...Is it possible it use the expand macro on things other than plain text, such as whole pages or sub-pages?
For instance, if I use the reporting or sub-page macros to display the full contents of my children pages, can I then allow users to show/hide them using expand?
How would I code this?
Oct 09, 2007
Keith Brophy says:
Is this possible (adding the expand functionality around the child page listing)...Is this possible (adding the expand functionality around the child page listing)?
Jan 11, 2007
Guy Fraser says:
The Visibility Plugin (specifically deck and card macros) already do this sort o...The Visibility Plugin (specifically deck and card macros) already do this sort of thing...
Jan 11, 2007
Guy Fraser says:
doh! cloak and toggle-cloak macros even hehedoh! cloak and toggle-cloak macros even hehe
Jan 11, 2007
James Mortimer says:
I use those packages already. Those two packages lack beginner syntax: required ...I use those packages already. Those two packages lack beginner syntax: required a macro that just used:
{expand} some text {expand}or
{expand:Title} some text {expand}Mar 01, 2007
Bob Swift says:
I agree. Having a simple macro is good. It eliminates that ugly requirement for ...I agree. Having a simple macro is good. It eliminates that ugly requirement for the composition-setup macro. The more complex one is also needed. I would probably prefer to have the simple syntax macro as part of the Composition Plugin so that similar stuff is together. I suspect it would be an easy addition. But in the meantime, this one is useful.
Mar 01, 2007
James Mortimer says:
i agreei agree
Mar 01, 2007
David Peterson [CustomWare] says:
I'm happy to add it to Composition if the authors are ok with that. Composition ...I'm happy to add it to Composition if the authors are ok with that. Composition is due for some housecleaning also (removing the requirement for composition-setup, faster performance), but that will take longer...
Mar 01, 2007
James Mortimer says:
Also, I recently had some cloaks and toggles created by an SQL query (about 30) ...Also, I recently had some cloaks and toggles created by an SQL query (about 30) and they take 5-10 seconds to initialize the composition setup plugin and render all the 'expand' buttons, even efter the page loads. The above macro, although wasteful in the amount of HTML code that is downloaded, renders instantly on the client.
Jul 18, 2007
pnina grossman says:
speaking of which, is there any way to get the toggle macro to "fold" to the sid...speaking of which, is there any way to get the toggle macro to "fold" to the side?
Jul 20, 2007
Fennie Ng says:
Hi Pnina, I'm afraid you need to do some customization on the expand macro sour...Hi Pnina,
I'm afraid you need to do some customization on the expand macro source code to "fold" to the side. Perhaps, you want to write your own javascript code to perform this.
Regards,
Fennie.
Aug 17, 2007
Andrew Miller says:
To make this a bit more efficient, I dropped the javascript into the "At the end...To make this a bit more efficient, I dropped the javascript into the "At the end of the HEAD" section in "Custom HTML" in the Admin pages.
It's a small amount of Javascript to cache and for page that use this a lot it's a good difference.
Aug 17, 2007
James Mortimer says:
Good idea. Would you document that above as an alternative installation method V...Good idea. Would you document that above as an alternative installation method Version 1.2?
Aug 17, 2007
Alain Moran says:
What happens when a user deletes your JS, not knowing what it is?What happens when a user deletes your JS, not knowing what it is?
Aug 21, 2007
James Mortimer says:
I assume you mean, 'what happens when an 'admin' deletes your JS, not knowing wh...I assume you mean, 'what happens when an 'admin' deletes your JS, not knowing what it is?
Sep 11, 2007
Guy Fraser says:
This macro borks if the {attachments} macro is used on the same page (it seems t...This macro borks if the {attachments} macro is used on the same page (it seems the expand macro uses the same JS as the attachments macro and they conflict).
Anyone mind if we (at some point) add an Java version of the expand macro to our open source Content Formatting Macros plugin?
Sep 11, 2007
James Mortimer says:
he he. I think I already submitted "include this macro in content formatting mac...he he. I think I already submitted "include this macro in content formatting macros" or "composition plugin" as either a comment on your page, or a feature request...
I think it fits extremely well in either of those plugins.
Thanks Guy!
Sep 11, 2007
David Peterson [CustomWare] says:
You're thinking of the Composition Plugin, I think James - Guy is suggesting add...You're thinking of the Composition Plugin, I think James - Guy is suggesting adding it to their Confluence Formatting macros plugin, which doesn't have the {composition-setup} (which I do eventually want to make optional, but haven't had the time).
Sep 12, 2007
James Mortimer says:
yes David, I am considering either of those plugins as a more appropriate home...Sep 12, 2007
Roberto Dominguez says:
James, You forgot to include ${bootstrap.webAppContextPath} in the image source...James,
You forgot to include ${bootstrap.webAppContextPath} in the image sources.
Sep 12, 2007
James Mortimer says:
Thanks. That seems like a good suggestion. I haven't noticed any problems with...Sep 12, 2007
Roberto Dominguez says:
Done. Problem is only when you have a context path (i.e. http://localhost:8080/c...Done. Problem is only when you have a context path (i.e. http://localhost:8080/confluence/)
Sep 12, 2007
James Mortimer says:
obsolete comment thread - content incorporated into the page - Confluence Admin,...Jan 22, 2008
Jon Hertzig says:
Having an issue with bullets inside the expanded text. If the title is formatted...Having an issue with bullets inside the expanded text. If the title is formatted, the bullets seem to pick up the formatting., eg:
regular text
Jan 23, 2008
James Mortimer says:
How do you bold the titles? The only way I could do it was to bold the entire bl...How do you bold the titles? The only way I could do it was to bold the entire block, which will bold the bullets of course.
*{expand:bold} reg - test - test {expand}*this did not work, because we don't 'render' the title
{expand:*bold*} reg - test - test {expand}and this did not work because of the logic of the confluence rendering engine
*{expand:bold}* reg - test - test {expand}with something like this:
or
Mar 12, 2008
jms says:
Two things you could add 1) don't display anything if the body is empty #if($b...Two things you could add
1) don't display anything if the body is empty
#if($body && $body.length()>0) [current code of the macro] #endI think the last line of the macro should use $!body instead of $body, as $!body will print as nothing if empty, whereas $body will print as $body if empty:
2) only display the body when in printable version
If the same macro is used multiple times on the same page, it's worth doing a no-body {expand-include} macro that will include the javascript only once , to be called on top of the page. And remove the javascript inclusion from the current {expand} macro.
Mar 12, 2008
James Mortimer says:
1) good idea. Can't think of any issues with this. Have you tested it on your ow...1) good idea. Can't think of any issues with this. Have you tested it on your own server? if so, go ahead and modify and document the code to reflect this.
2) good idea. What version of confluence was the $!body versus $body feature introduced? If was introduced recently, just use an #if($body)$body)#end instead.
3) re: splitting that JS from the expand macro: beginner users don't often 'get' split macros like that. for that type of macro, see the 'composition plugin', I think. A better way would be to just add a 'includejavascript=[true]/false' parameter that 'optimizers' can put the 'false' value, but the basic 'expand' will always work for novice users.
Mar 13, 2008
jms says:
1) Will do. Still testing. 2) $!body is a Velocity thing, called silent notation...1) Will do. Still testing.
2) $!body is a Velocity thing, called silent notation. Been there for a while (since velocity 1.3 at least).
3) I would have added a parameter, except I don't know of a quick way to split the $param1 into name/value in Velocity. Plus in my current use case, I can move around the {expand} without having to remember that all but the first one should have the flag set to false.
Mar 13, 2008
James Mortimer says:
1) thank you for testing. not everyone actually does that. 2) it should be backw...1) thank you for testing. not everyone actually does that.
2) it should be backwards compatible, then, so yes, go ahead. I've tested that on my server and it works.
3) don't use param1. param1 doesn't exist if there is an = sign in the 2nd parameter slot. instead, confluence creates a variablename using the text before the = sign. For example, if the expected syntax used is "{expand:my title|includejavascript=true}", then $paramincludejavascript will contain "true" as a string. it's case sensitive, and the parameters are always all strings (not numbers or boolean). This code might be helpful, but I don't have time to test it right now:
#set($includejavascript="TRUE") #if($paramincludejavascript && $paramincludejavascript.length()>0) #if($paramincludejavascript.toUpperCase()=="FALSE") #set($includejavascript="FALSE") #end #end #if($includejavascript=="TRUE") insert javascript here #endMay 29
Julie Leung says:
I'm wondering if there has been a fix or enhancement to this macro to be able to...I'm wondering if there has been a fix or enhancement to this macro to be able to operate the expand link (and therefore to see the expandable text) within the preview?
I see that in the "Feature Requests" section of this page, there is a comment of "detect if we are in preview or template modes. If so, we need to do a different renderer (currently, throws error in preview mode if the page does not yet exist, probably because of the getRealTitle)". However, my problem isn't that I get an error because the page isn't existant yet, but rather, on a page that already exists, that I can't actually operate the expand to preview the content underneath. Because I use expand so much within my content, this forces me to save multiple versions of my page just to troubleshoot any formatting issues "inside" the expand macros.
If anyone knows how the macro "code" can be changed so that expandable text can be rendered in the preview, pleaes comment! I would greatly appreciate it.
May 29
James Mortimer says:
Excellent enhancement idea. I'd like to use that too! Please contribute it when ...Excellent enhancement idea. I'd like to use that too! Please contribute it when you find an answer
Aug 18
Julie Leung says:
UPDATED 8/18/2008This workaround provides {expand} functionality in Preview mode...This workaround provides {expand} functionality in Preview mode for Confluence 2.8.1 and 2.8.2 only. As mentioned above in the compatibility matrix, this workaround does not work in Confluence 2.9. In Confluence 2.9, implement the {expand} user macro in the traditional way (with javascript functions inserted during each call to {expand} and it will work for both preview and normal modes.
So, I've managed to implement a fix on my local version of Confluence which I am looking for feedback on.
Using the FireBug extension for Firefox, I was able to determine that, in preview mode, the "ExpandMacroToggleAnswer(id)" javascript function wasn't available, so nothing happened when the onclick event was received. I'm a real-time OO programmer and just new to the world of web development, so I don't really know why in preview mode this javascript wasn't available to the page.
On a hunch, I decided to try to cut the javascript into the "Custom HTML" section as Andrew Miller suggested above and to therefore remove the <script> sections from the user macro. This is good practise, anyways, because there is so much redundant javascript code on pages where I use this macro a lot.
This worked except that I then lost the open and closed icons after I clicked in preview mode. On another hunch (don't you just LOVE hunches!), I considered that for SOME reason, the extra ${bootstrap.webAppContextPath} suggested by Roberto Dominguez might be the problem. I removed them from the path in the javscript in the "Custom HTML" section, but not in the actual