[All Adaptavist Apps]

Page tree
Skip to end of metadata
Go to start of metadata

{pagetree2} macro

(info) This macro required Theme Builder 3 or above









Builder Version




Defines where the page tree should start from:

  • SPACEKEY:pagename - a specific page in a specific space
  • page title - a specific page (defined by it's title) in the current space
  • @self - the current page
  • @parent - the parent of the current page
  • @parentparent - the parent of the parent of the current page
  • @space - the currently viewed space showing all top-level pages and also news items (default)
  • @orphan - same as @space
  • @root - the root of the current tree
  • @home - the homepage of currently viewed space (does not include news items)
  • @dashboard - the Confluence dashboard showing all spaces the user has access to




current space

If you want to show a page tree for a different space, specify the space key of that space using this parameter.





An alternate way to specify the page (by it's title) to use as the root node of the tree.





The target window that links in the tree should be opened in (eg. _blank or _self).





Should icons be shown in the tree?

  • true - show icons (default)
  • false - do not show icons





When a node is selected in the tree, what should be highlighted?

  • node - highlight the node caption (default)
  • row - highlight the entire row





Only allow a single node to be expanded?

  • false - allow any number of nodes to be expanded (default)
  • true - when a node is opened, collapse all other nodes





Should different levels of the tree be indented?

  • true - indent each level (default)
  • false - left align all levels





Should the root node of the tree be shown?

  • true - show the root node
  • false - hide the root node





Defines how the structure of the tree is visualised:

  • plus-lines - +/- buttons, dotted lines (default)
  • plus-nolines - +/- buttons, no lines
  • ball-lines - yellow sphere buttons, dotted lines
  • ball-nolines - yellow sphere buttons, no lines
  • arrow - green arrow buttons, no lines





Which icon set should be used?

  • computer - computer style icons (default)
  • website - website style icons
  • builder - Theme Builder style icons
  • bookshelf - bookshelf style icons





An optional CSS class to assign to the outer wrapper of the page tree.





When a link is clicked, should the corresponding page be opened?

  • true - open the link
  • false - highlight the link, but don't open it





Allow pages in the tree to be dragged to new locations?

  • true - allow page moving
  • false - do not allow page moving





The name of the tree (for use with pagepanel macro)
(warning) May be deprecated or changed in future versions





Should the page title be used as the tooltip when hovering over items in the tree?

  • true - display the page title in the tooltip
  • false - display the date and author of the item in the tooltip





Prevent the tree expanding beyond this depth on page startup.



Hints and Tips

CSS Customisation


See Also

  • No labels


  1. Unknown User (l0xbbar)

    Hi all,


    doesn't work, if the current space name contains " characters. Example: space name = Space "XYZ".


  2. Unknown User (rupert.shanks@ne.nykline.com)


    Iam trying to get the pagetree to open by default to over 2 levels of child pages. Here is the markup I am using


    However it only opens to 1 child level by default and allowdrag doesnt work at all. Does anyone know what Im doing wrong?
    P.S. Confluence 3.2.1 and Builder 4.0.1


    1. Unknown User (amoran)

      Heh, you have misunderstood the initialDepth parameter .. it's not a counter to force that depth, it's a counter to limit to that depth (wink)

      So if you are 10 levels deep, the initialDepth parameter will limit the number of layers that are expanded to 5 - preventing 10 layers deep of information being retireved.

      For the usage you are describing you probably want to be looking at the sorted-children macro (eg {sorted-children:@space|depth=5})

      1. Unknown User (rupert.shanks@ne.nykline.com)

        Ok thanks Alain. I did realise it was meant to limit the amount of layers, but surely something must be making them expand in the first place? How do you do that?

  3. Unknown User (jbrown@interthinx.com)

    How would I go inserting a dynamic parameter into the pagetree2 tag? Basically I want it so that it always starts at the top level parent page. I am using this as part of a Theme Builder menu. So I want any pages that are using this template to have a pagetree that shows the toplevel parent.

    So my structure might be something like this:

    HR Space

    • Home
    • Announcements
    • Best Practices Wiki
      • Policy 1
      • Policy 2
        • Policy 2 Detail A
        • Policy 2 Detail B
      • Policy 3

    So I am trying to build a pagetree that would be used in a template for the "Best Practices Wiki". So I want to insert a dynamic parameter into the tag that gets what the top level page is (in this case "Best Practices Wiki"). I don't want to hard code the page since I will be using this in a template and I will be using it for many different areas.

    I assume the structure would be something like


    So how do I insert the top level parent?

    1. Unknown User (amoran)

      Depending on your perspective it's going to be one of {pagetree2:@space}, {pagetree2:@home} or {pagetree2:@root}

      1. Unknown User (jbrown@interthinx.com)

        But wouldn't that include all pages in the whole space? That is not what I am looking to do. I want a pagetree that will include all pages that are contained within the top level parent. So If you look at my example structure if the pagetree was included on the page "Policy 3" or "Policy 2 Detail B", the outputted page tree would look something like:

        Best Practices Wiki

        • Policy 1
        • Policy 2
          • Policy 2 Detail A
          • Policy 2 Detail B
        • Policy 3

        Does that make sense? Maybe I am wording it incorrectly. I guess another way to say it would be that I want a menu with whatever the top level child page would be (since I suppose the top level parent could be considered the main space page).

        1. Unknown User (amoran)

          1. Unknown User (jbrown@interthinx.com)

            ah ok. yes, that did work. For some reason I was thinking that @root would include everything in the entire space.

            1. Unknown User (amoran)

              The HTML documentation above was incorrect, I noticed it when you questioned my answer so I updated it .. however you should use the confluence notation guide as your most authoritative source of info as it is updated at the same time as the code - the html docs tend to lag a bit :s

  4. Unknown User (okmi)

    I am able to get this macro to render fine on any of my pages, but I can't seem to get it to work in the "sidebar" section of 3.3's default 'Documentation' theme. Any ideas? Instead of rendering, it spits out a bunch of javascript...

    1. Unknown User (amoran)

      That sounds like the pagetree macro is rendering correctly but the confluence documentation theme isn't able to cope with HTML in the sidebar ... you will need to contact Atlassian and get them to fix the documentation theme.

      1. Unknown User (okmi)

        Will do - thanks. I noticed that it rendered perfectly fine in a normal wiki page, but when I try to add that same macro to the settings section of the documentation theme, it just spits out the javascript because it seems to be stripping the opening script tags: http://i.imgur.com/cvtd6.png

  5. Unknown User (gdhugga@cfri.ca)

    for the life of me i cannot get the pagetree2 to sort manually rather then alphabetically I have draged and changed the sorting by using > browse pages, where the sorting is correct under the tree heading.

    in my LSB the code is Unable to render content due to system error: java.lang.ClassCastException: com.adaptavist.confluence.theme.engine.macros.deprecated.Pagetree2Macro cannot be cast to com.atlassian.renderer.v2.macro.Macro I have also tried sort=natural, sort=tree, sort=position but am unable to do anything other then alphabetical sort.

    any help would be appericiated.

  6. Unknown User (bandersson)

    There is the list-spaces macro and the pagetree2 macro, what I'd really like to see is a combination of the two that will list


    Unknown macro: {html}


    space pages

    Unknown macro: {html}



    Unknown macro: {html}


    sub-space pages

    currently I see no way to build a space/page tree that has the root space at the top level with and sub-spaces and pages as children.

    1. Unknown User (amoran)

      Interesting idea, {pagetree2} isn't currently parent-space enabled ... I'll add the idea to our list of feature requests, but it's likely to be several months before we can look at adding it.

      If you need this feature within a reasonable time-frame then you will need to request a quote for the work at http://tracker.adaptavist.com

    2. Unknown User (scayla)

      One way would be to use the {sql} (or {sql-query} for read-only queries) plugin, find all the spaces and subspaces (I don't know how to find the relation between a space and a subspace but information might be somewhere in the database). Then, output the result as wiki markup.
      You'll get something like that :

      SELECT '{pagetree2:space=' + s.spacekey + '}'
      FROM spaces s, (might be other tables too)
      WHERE .... (something that will find spaces and links between spaces and subspaces)

      This way, for each space, you'll get the pagetree macro showing all the pages inside, and if you manage to find the subspaces, you'll list pages the same way.

      The code I gave is wrong, just the idea in order to help you.
      There might also be an easier way to achieve what you're asking for, dunno.


      1. Unknown User (amoran)

        Sadly the metadata2 code only stores the parent space (as a content property btw), so builder (for compatibility with other metadata2 parent space plugins) also only stores this data (in the same place).

        To get the child space lists in an efficient way you need access to the builder java api (it builds the tree structure and then caches it).

        What's been asked for is definitely possible to achieve. It's just that, right now, we are booked out until at least the new year with paid-for work, and as more work comes in work on the free plugins will get pushed back.

  7. Unknown User (bng_goldenboy)

    Is it possible to use custom icons in the pagetree? And, can I do it on a per-page basis? How would I go about setting that up? Thanks!

  8. Unknown User (kmorankar)

    Hi there ..

    My requirement may be wierd but for one of the site we are building we require to sub-sections in the same page in page tree. i.e.

    if my tree should look like below

        - Home

            - Page1


    and subsection1 and page1 will be pointing to the same page but at different location on the page. Is it possible using any other macros if not this ?

    Thanks for the help.

    1. Unknown User (amoran)

      That would require development to achieve ... if you require a quote for the work then please request it through the SALES project on tracker.adapatavist.com

  9. Unknown User (davis.1114)


    I am using the pagetree2 macro and I'm trying to customize the CSS options. We have all of the customizations correct except the selected node does not remaine highlighted after the page loads.
    How can I change the code in order to show what page is currently active

    .atb-leftSidebar a:link, .atb-leftSidebar a:visited{
    text-decoration: none;
    background-color: transparent;
    .atb-leftSidebar a:hover, .atb-leftSidebar a.node:link:hover, .atb-leftSidebar a.node:visited:hover, .atb-leftSidebar a.prnnode:link:hover, .atb-leftSidebar a.prnnode:visited:hover{font-weight: bold; background-color: transparent;border:none;

    Any thoughts?


    1. Unknown User (amoran)

      Have you heard of firebug, it allows you to click on an html element & see what classes are applied to it ... I find it invaluable in answering these kinds of questions.

      In this case, try:

      a.selprnnode {
        background-color:red !important;// or whatever you like really
      1. Unknown User (davis.1114)

        That worked like a charm! However, the node that i'm on only highlights up until the 3rd child page. Do you know why that would be?

        thanks for all your help!

  10. Unknown User (luboskral)

    Just an idea, the existence of the parameter labels would be very useful ...

    1. Unknown User (amoran)

      I assume you mean that it would be useful if you could specify a label & the tree only displays pages which have that label?

      One question ... what happens when there are pages with the label but their parent pages do not?

      1. Unknown User (luboskral)

        This is certainly a problem. Creating archive drawings. Drawings are divided according to reports. The drawing document are as descendants of the pages containing specific and additional information. This site has no descendants. To view the structure drawings is an ideal tree. Using the tree view and "ballast" contains documents that contain drawings ...

        1. Unknown User (amoran)

          If I understand you correctly you want to view a tree that contains only 'drawings' but in the same structure as a more complicated tree which contains other data?

          That's not going to be possible with the pagetree as it stands, however I do think that kind of navigation would be possible from a custom macro.

          The custom macro would likely do all the grunt work of locating the pages with labels and tracing their parentage back to root in one pass & then dump the complete tree out as a set of nested lists. These lists could then be made active like the pagetree with some pretty basic JS.

          However the initial search for pages will generate a significant load on your server in a space with lots of pages or if you have many users or slow authentication. This could be mitigated to some extent by using intelligent caching inside the macro, however in large spaces with many pages in the tree you are also looking at a significant increase in bandwidth usage since every page view would need to download the entire tree.