Nested expand macros in Confluence wiki

This week I discovered that you can embed one {expand} macro inside another, to create a tree of expandable sections on a Confluence page. This is useful for a new navigation panel that we’re designing, and it’s probably useful in other situations too.

TL;DR: Add a number of expand macros. For example, {expand}, {expand2} and {expand3}. The code for each one is identical to the code for the original {expand} macro. (See the docs.) Nest away!

The details

We’ve been using the {expand} macro for a while. It defines an expandable section (a show/hide panel) on a Confluence page. Up to now, we have only ever needed a single layer of expandable sections.

First, the basic {expand} macro

The {expand} macro defines an expandable section on a Confluence page, and indicates it with a blue arrow as shown in the first screenshot below.

An expandable section, hidden

An expandable section, collapsed

Here is the page after someone has clicked the text next to the blue arrow:

An expandable section, expanded

An expandable section, expanded

The {expand} macro is not shipped with Confluence, or not yet. I’m using Confluence 3.5. The macro will be part of Confluence 4.0, due for release soon.

The {expand} macro is a user macro. That means that you can add it to Confluence quite easily, by entering some code into a form on the Confluence administration console. You do need to be a Confluence system administrator. The Confluence documentation describes how to add the macro.

Once you have added the macro, people can use it on their wiki pages. The basic format is this:

{expand:title=Click here to show text...}
All this text is hidden inside a show/hide block.
{expand}

So far, so good. Where does the nesting come into it?

Nesting the expandable sections

This week I came across a situation where it would be nice to embed one expandable section inside another. To show you what I mean, I’ve made up a dummy page with three nested layers of expandable sections. In this screenshot, just the first level (“Fruit and veg”) is expanded:

Just the top level expanded

In the next screenshot, the “Fruit” level is expanded too:

Two levels expanded

Two levels expanded

And here’s the page with all levels expanded:

All levels expanded

All levels expanded

Each of the blue arrows is produced by an expand macro. Inside the third layer, I have used a bulleted list to display the lowest level of categorisation. For example, the bulleted list shows the types of apple: “Granny Smith”, “Golden Delicious”  and “Red Delicious”.

How to nest the {expand} macros

First you need to add a few more user macros, one for each layer in your nested tree. For my example I needed three layers.

  • The original {expand} macro supplies the “Fruit and veg” layer.
  • I added an {expand2} macro for the “Fruit” layer and the “Vegetables” layer.
  • I added an {expand3} macro for the types of fruit (“Apples” and “Oranges”) and the types of vegetable (“Potatoes” and “Carrots”).

The code for the {expand2} and {expand3} macros is exactly the same as the code for the original {expand} macro.  The Confluence documentation describes how to add the {expand} macro and gives the full code.

Next, use the three macros on a Confluence page. Here is the full wiki markup of my example page:

{expand:title=Fruit and veg}

{expand2:title=Fruit}

{expand3:title=Apples}
* Granny Smith
* Golden Delicious
* Red Delicious
{expand3}

{expand3:title=Oranges}
* Navel
* Valencia
{expand3}

{expand2}

{expand2:title=Vegetables}

{expand3:title=Potatoes}
* Marfona
* Nicola
* King Edward
{expand3}

{expand3:title=Carrots}
* Nantes
* Chantenay
{expand3}

{expand2}
{expand}

That’s it! :)

About these ads

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 20 August 2011, in Confluence, technical writing and tagged , , , , . Bookmark the permalink. 27 Comments.

  1. Very nice. This is similar to the {toggle-cloak} and {cloak} macros, but the usage is much simpler. The only thing you don’t get with {expand} is the ability to separate the toggle text from the body (cloaked) text.

  2. Hi Sarah, fantastic blog! Hope you won’t mind me asking, but would you have any advice/tips for someone looking to move into technical writing in Sydney? I’m working as an illustrated book editor in London at the moment but am looking to move into this field in future. I don’t really have have a strong IT background at present but I’m very quick with systems and databases and am looking into pursuing an MIT qualification in Sydney next year. Any pearls of wisdom you cared to offer about this would be greatly appreciated! :)

    Cheers,
    Alison

    • Hallo Alison

      It’s nice to hear from you! Sydney is a lovely place to live, and technical writing is a great field to work in. It can be hard to get into your first role as technical writer. A good way to start would be to look for an open source project that needs some documentation done. For example, Mozilla holds a doc sprint every now and then. Here’s a recent blog post about that:

      http://hacks.mozilla.org/2011/07/better-docs-by-who-you-doc-sprint-august-12-13/

      You could consider joining the New South Wales branch of the Australian Society for Technical Communication:

      http://www.astcnsw.org.au/

      That’s probably only worth while once you get here.

      The AusTechWriters list is an active email forum, and people often post job offers to the list. Sometimes the offers are just what a starter needs, for example something more in the line of a 6-week editing contract. To join the list, send an email message to “austechwriter-request@freelists.org”, with “subscribe” in the subject field.

      There are also a couple of LinkedIn groups where job ads are posted regularly:
      NSW tech writers: http://www.linkedin.com/groups?mostPopular=&gid=2263506
      Technical writers Australia: http://www.linkedin.com/groups/Technical-Writers-Australia-89653

      Good luck with the move! Ping me when you get here, and we can catch up for a hot chocolate. :)

      Cheers
      Sarah

  3. Nice post as always Sarah! At work, we are comparing Confluence and a couple of other wikis, and one of the features we were looking for was the ability to nest topics. This post came along at the right time!

  4. Hi Sarah,

    Thanks so much, that’s all incredibly helpful. Hot chocolate is definitely my shout when I get back! :)

    Cheers,
    Alison

  5. I often use the expand macro, but nesting them will be so much more fun! Thanks!

  6. I’m new to Confluence. We’re using 3.5.1.3. I’m curious about the include text macro. I’d like to know if there’s a way to include MORE than one include macro in the page? I saw the limitation as you can only include one of these macros. However, I have cases where I want to not have to repeat information across pages in the same space.

    • Hallo Sanjay
      You can have as many {include} macros on one page as you like. You can also have multiple {excerpt-include} macros on one page. The only limitation is that you can have only one {excerpt} macro on a page. That is the macro that you use to define a reusable chunk. The workaround is to have a separate page for each reusable chunk, and include it on all the pages where you need it.

      I hope you’re having fun with Confluence! Please let me know if you’d like more help with the content reuse macros.

      Cheers, Sarah

  7. Hi Sarah,

    The only problem with this approach with the excerpt macros on multiple pages is it makes the content non-contiguous. I need a single page in which a lot of my information resides and then be able to excerpt out from that ONE page to other pages that need specific sections from that original page to include in many child pages. That makes maintenance so much easier since not all the content needs to be in all the pages but some does.

    • Hallo sanjay

      The Multi Excerpt Plugin should satisfy that requirement:

      https://plugins.atlassian.com/plugin/details/169

      It is developed and supported by Artemis Software. I see that there’s a question-mark next to Confluence 3.5 support, in the table under “Compatibility with Confluence”. It’s worth contacting the vendors and finding out more.

      I hope this helps!

      Cheers
      Sarah

      • Thank you sarah, what strikes me is that almost 2500 people downloaded this plug-in, at $80 and no support since it hasn’t been updated for quite some time, if this is a feature that makes sense, how come it hasn’t been included in Confluence itself?

  8. Mark Ganzer

    Hi Sarah,
    When I try this I get an error:
    Unknown macro: {expand2}
    Is there something I have to enable here?
    Thanks,
    Mark

    • Hallo Mark

      First, a quick check: Are you using Confluence 3.5? The instructions on this page won’t work with Confluence 4.0 or later.

      If you’re using Confluence 3.5, then you’ll need to add the {expand2} user macro to the wiki. Actually, you can call the macro anything you like. The important thing is that the macro script for your new macro is the same as the script for the existing {expand} macro. The instructions and script are on this page: http://confluence.atlassian.com/display/CONF35/Writing+the+Expand+User+Macro

      I’ve tried to recreate the {expand2} macro on Confluence 4, but with no luck. Maybe someone with better JavaScript and Velocity skills can help.

      Cheers, Sarah

  9. Mark Ganzer

    Thanks for the info! We are on 3.5.13, but finding somebody to admit to ownership has been less than simple. I am tracking down folks now, but looks like we do not have the expand2 macro.

  10. Hi Sarah,
    Do you know if this functionality breaks in Confluence 4.x?

    I’m testing out Confluence 4.1 and have an {expand2} nested inside an {expand}. When I click the first “click here to expand” link, the nested one also expands. I.e. when you click to expand one section all the sub sections expand as well.

    Any advice?
    Thanks,
    Dee :)

  11. I am new to confluence and trying to use the Expans function, I was wondering if ther is a way to switch the default so that it is expanded first and then users can colapse?

  12. Hallo all

    From Confluence 4.3.2, it’s now possible to nest Expand macros. Yaayyy! See the Confluence 4.3.2 Release Notes: https://confluence.atlassian.com/display/DOC/Confluence+4.3.2+Release+Notes

    Cheers, Sarah

  13. Hello Sarah,
    Is it possible to link or attach a particular page to the {expand} marco??
    I have a parent page with two child pages. Now what I would like to do is on the parent page have an expand button with one of the child pages. So when you click the expand button, all you see is the child page.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,465 other followers

%d bloggers like this: