PageTree Plugin

Name AJAX PageTree
Vendor Atlassian
Authors Alain Moran, Matthew Jensen, Guy Fraser, Zohar Melamed
Homepage http://confluence.atlassian.com/display/CONFEXT/PageTree+Plugin
Issue Management http://developer.atlassian.com/jira/secure/BrowseProject.jspa?id=10017
Categories Content Macros
Version 1.8
Availability Confluence v2.8.0 to v2.9-m5
State Stable
Support Unsupported Plugins
License Freeware / Open Source (BSD)
Price Free
Release Docs http://confluence.atlassian.com/display/CONFEXT/PageTree+Plugin
Java API Docs n/a
Download Source http://svn.atlassian.com/fisheye/browse/public/contrib/confluence/pagetree-plugin/tags/pagetree-1.8
Download JAR pagetree-1.8.jar
You will need to use version 1.5 or earlier if you are using Confluence 2.7 (or earlier).

Description

A macro that embeds the ajax page tree found in the browse space content page by william jones and zohar melamed, with extensions by adaptavist.com

Usage

{pagetree:root=PageName|sort=natural|excerpt=true|reverse=false|startDepth=3|expandCollapseAll=true|searchBox=true}

root defines the page which acts as the root of the tree. It can be the page name, or any of the following

  • @home - set the root page to the Home page (default)
  • @self - set the root to the current page
  • @parent - set the root to the parent of the current page
  • @none - pagetree shows all pages in the space, including Orphaned pages

sort may be one of the following

  • position - sort pages using the Confluence 2.8 sorting rules which uses the position if set, otherwise reverts to natural ordering (default for versions 1.7 onwards).
  • natural - sort pages in natural order, eg: title1, title2, title10 (default for versions before 1.7).
  • bitwise - sort pages using standard alphabetical sorting on the page title, eg:title1, title10, title2
  • creation - sort pages by creation date
  • modified - sort pages by modification date

excerpt is a true/false flag that states whether page excerpts should be included in the tree display (defaults to false)

reverse is a true/false flag that allows you to reverse the order of display (defaults to false)

searchBox is a true/false flag that allows you to add a search box that would allow searching within the page tree (defaults to false)

startDepth is any number greater than 0 that indicates how many levels of descendants to show initially. (defaults to 1)

expandCollapseAll is a true/false flag that allows you to add an expand all and collapse all feature (defaults to false)

If you just see a message "Loading..." and nothing else, make sure you have Base URL correctly set in your General Configuration settings.
Creating a navigation panel for your space

A popular usage of {pagetree} is to create a navigation panel showing a table of contents for your space. You can find the instructions in the Confluence User Guide.

Installation

Download the plugin jar (URL at top of this page) and upload via the Plugin Manager.

If you are upgrading from an earlier version, you will need to restart Confluence to clear the velocity cache in order to ensure the latest features are used.
This plugin now accessible through the Confluence Repository Client.

Version History

Version Comments Author
1.0 Initial Release zohar melamed
1.1 ?? zohar melamed
1.2 Added some enhancements:
  • Ability to display excerpts
  • Ability to have more than one instance on a page
  • Natural Sorting by default (1, 2, ... 10 etc)
  • Ability to sort by natural, bitwise, creation, modified
  • Ability to reverse sort
  • Ability to display excerpts next to items in the tree
Adaptavist.com
1.2.1 Fixed sort-order selection issue Adaptavist.com
1.2.2 Fixed PGTR-1, added scriptaculous effects and resolved issues with rendering wiki text in excerpts Adaptavist.com
1.2.3 Fixed PGTR-2, and resolved issues with rendering links in excerpts Adaptavist.com
1.2.4 Fixed pagetree for confluence installs with a base path, resolved JS error in branch collapse which lead to a page refresh Adaptavist.com
1.2.5 Fixed pagetree for confluence 2.1.1 installs and tested against 2.0, 2.0.1, 2.0.2, 2.0.3, 2.1, 2.1.1, 2.1.2, 2.1.3, 2.1.4, 2.1.5a Adaptavist.com
1.2.6 Removed the requirement for the domain name to be set in general configuration, Added defaulting the root page to the homepage of the current space, Added the ability to use the @parent and @self macro pagenames Adaptavist.com
1.5 Last pre-Confluence 2.8 version Atlassian.com
1.7 Updated to comply with Confluence 2.8's new sorting rules Atlassian.com
1.8 PGTR-14, added expand all and collapse all feature. Also added the startDepth feature.
PGTR-7, added @home and @none values for the root parameter
Fixed PGTR-16, PGTR-17 and PGTR-18
Atlassian.com

Outstanding issues

Labels

plugin plugin Delete
macro macro Delete
confluence20 confluence20 Delete
confluence21 confluence21 Delete
repository_current repository_current Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jan 05, 2006

    Anselm McClain says:

    Thanks for the plugin it's helpful. It would be great if there were a way to ha...

    Thanks for the plugin - it's helpful.

    It would be great if there were a way to have the menu expanded by default to x levels. As it is now, I need to click down to the page I wish to visit, then click the page itself. If the top levels were expanded it would save a click.

    Also - it doesn't seem to have any memory of how I've left the various trees. It would be nice if things would stay expanded / collapsed while I'm browsing through the site.

    Best of luck!

    1. Mar 08, 2006

      Bernard Durfee says:

      Same here, this would be a nice feature.

      Same here, this would be a nice feature.

      1. Mar 08, 2006

        Guy Fraser says:

        Which bit the default expansion or the memory of what's been expanded?

        Which bit - the default expansion or the memory of what's been expanded?

  2. Jan 06, 2006

    James Matheson says:

    I am working with the 'left navigation' theme and I want to put the PageTree plu...

    I am working with the 'left navigation' theme and I want to put the PageTree plug in into the Navigation page.   
    I can get the PageTree macro working in the main page, but when I put it in the Navigation page, I get a NullPointerException (output in the Navigation area).   The Navigation page looks correct when I view it, it only has a problem when it is rendered as the side bar. 

    Has anyone had any success this plugin in the Navigation page?

    1. Apr 19, 2006

      Othman Alaoui says:

      No success here so far (see my comments below).

      No success here so far (see my comments below).

  3. Feb 15, 2006

    Mingyi Liu says:

    Excellent macro! I like it a lot. I made a slight modification so that users can...

    Excellent macro! I like it a lot. I made a slight modification so that users can hide the tree if they want to (and change 'display:inline' to 'display:none' if you want the tree menu to be hidden by default):

    #if ($action.isPrintableVersion() == false)
    <style>
    .spacetree * ul{
    padding-left:0px;
    margin-left: 0px;
    }
    .spacetree * li{
    margin-left: 5px;
    padding-left:5px;
    }
    </style>
    
    <script>
      function toggleNavTree()
      {
        var td = document.getElementById('treenavtd');
        if(td.style.display == 'none') td.style.display = 'inline';
        else td.style.display = 'none';
      }
    </script>
    
    <table>
    <tr><a href="javascript:toggleNavTree()">Toggle Space Navigation Tree</a></tr>
    <tr>
    <td id="treenavtd" style="display:inline;" valign="top" align="left" width="22%" >
    <div class="tabletitle">Space Map</div>
    <div class="spacetree">
    #includePage($helper.spaceKey "TreeNavigation")
    </div>
    </td>
    <td valign="top" align="left" width="78%">
    <div class="wiki-content">
    <blockquote>
    $body
    </blockquote>
    </div>
    </td>
    </tr>
    </table>
    #else
    <div class="wiki-content">
        $body
    </div>
    #end

    An important question is: Most of our pages in a space is not branced off "Home", but I would like the tree to include all pages in a space, is it possible to modify the macro to allow setting root to space name so that all pages of a space would display? Thanks!

  4. Feb 27, 2006

    Jonty Hurwitz says:

    Hi Zohar I'm coming into your 'little family owned bank' on Thursday to discuss ...

    Hi Zohar

    I'm coming into your 'little family owned bank' on Thursday - to discuss our fund factsheet reporting technology.  Our new product version links directly in with Confluence.  Thought it might be nice for you and I to hook up.  I can't seem to get your email anywhere so I hope you're watching this page.  Give me a shout:  jonty.hurwitz@statpro.com

  5. Mar 02, 2006

    Guy Fraser says:

    Zohar & William would it be possible to change the license of this plugin to BSD...

    Zohar & William - would it be possible to change the license of this plugin to BSD (ie. a certified open source license)?

  6. Mar 03, 2006

    samuel halle says:

    If you dont want to create a page only for the tree navigation, you can put the ...

    If you dont want to create a page only for the tree navigation, you can put the macro directly in the page layout, just replace a line of the code of Mingyi Liu from

    #includePage($helper.spaceKey "TreeNavigation")

    to

    $helper.renderConfluenceMacro("{pagetree:root=$space.homePage.title|sort=natural|excerpt=true|reverse=false}")
    1. Mar 03, 2006

      Alain Moran says:

      You should already be able to simply insert a pagetree macro into any page ... t...

      You should already be able to simply insert a pagetree macro into any page ... there is no reason that it should go onto its own page, I think thats just one way of using it.

      Possibly the idea of creating it in its own page was a workaround for the fact that it didnt use to work correctly with server trees on a single page. That issue is now resolved though so you shouldnt have any problems using it like a standard macro (thats the way that we and our clients use it)

      1. Mar 03, 2006

        Guy Fraser says:

        Samiel is referring to a technique to embed the page tree in to a theme....

        Samiel is referring to a technique to embed the page tree in to a theme. The left nav theme has a "navigation page" which allows you to add your own content to the left nav bar and the conventional way of adding the page tree was to put it on that navigation page. However, with the modification shown above, you can remove the navigation page completely and embed the page tree directly in to the left nav theme.

  7. Mar 16, 2006

    Rune Stilling says:

    Hi I get the same exception. Did you find a solution?

    Hi - I get the same exception. Did you find a solution?

    1. Jun 21, 2006

      John Russell says:

      Hi after working for several weeks, we are also seeing this error.&nbsp; No reso...

      Hi - after working for several weeks, we are also seeing this error.  No resolution at this time. 

  8. Mar 27, 2006

    Troy McKinnon says:

    I used the plugin repository to update my PageTree plugin. Now all my pages are ...

    I used the plugin repository to update my PageTree plugin. Now all my pages are saying:

    "The page you were trying to reach does not exist. You may want to try a search, or browse the site to find the page you were looking for."

    I use the layout mod with the following:

    $helper.renderConfluenceMacro("{pagetree:root=$space.homePage.title|sort=natural|excerpt=true|reverse=false}")

    1. Mar 27, 2006

      Guy Fraser says:

      I'll get Alain to check this out tomorrow. Have you tried it without the sort/ex...

      I'll get Alain to check this out tomorrow. Have you tried it without the sort/excerpt/reverse parameters?

      Also, could you try restarting Confluence to see if that makes any difference?

      Do you get the same error when you place the pagetree on a normal page (ie. within the normal wiki markup of that page)?

      1. Mar 27, 2006

        Troy McKinnon says:

        Restart didn't matter. Removing params didn't matter. One a regular page it thr...

        Restart didn't matter.
        Removing params didn't matter.

        One a regular page it throws a NPE

        1. Mar 27, 2006

          Guy Fraser says:

          Which version of Confluence are you using? It might be worth using the "Downgra...

          Which version of Confluence are you using?

          It might be worth using the "Downgrade" link to revert to an earlier version of the plugin whilst we track down the bug.

          1. Mar 27, 2006

            Troy McKinnon says:

            Not sure on the download link? is it in the repository plugin? We are using Ver...

            Not sure on the download link? is it in the repository plugin?

            We are using Version: 2.1.1 Build:#406 Dec 23, 2005

            1. Mar 27, 2006

              Guy Fraser says:

              With the latest version of the repository plugin,...

              With the latest version of the repository plugin, you should be able to click on the "AJAX Page Tree" plugin title in the list to go to the details page - on there it should list all versions and there should be "Downgrade" links next to the older versions.

              We've not had any error reports on Confluence 2.1.1 but we'll do more testing tomorrow to see if we can find what's causing the bug.

              Do you get any stack traces or other error messages in your log files?

              Also, which version of Java are you using and how were any previous versions of the plugin installed (manually, via Plugin Manager, via Plugin Repository, etc?)

              1. Mar 27, 2006

                Troy McKinnon says:

                Websphere 6 w/1.4.2 Installed via plugins admin not repository plugin. Had to ...

                Websphere 6 w/1.4.2

                Installed via plugins admin not repository plugin.

                Had to roll back to 1.2.2 (#5) for it to work again.

                1. Mar 27, 2006

                  Guy Fraser says:

                  Thanks for the info Troy that should allow us to track down the bug far more qui...

                  Thanks for the info Troy - that should allow us to track down the bug far more quickly as we'll be able to review all the changes that were made between 1.2.2 and 1.2.3 (which seems to have been the point at which it broke on your configuration).

        2. Mar 28, 2006

          Alain Moran says:

          Troy could you email a copy of the exception that pagetree throws when viewed on...

          Troy could you email a copy of the exception that pagetree throws when viewed on a normal page to amoran at adaptavist.com, that may shed some light as to why you are seeing this problem and others are not. So far I am unable to reproduce any errors when using pagetree as you have outlined above, however I am runing 2.1.2 through Tomcat for my immediate tests (2.1.1 is currently downloading)

          1. Mar 28, 2006

            Alain Moran says:

            I have found and fixed a couple of problems with running pagetree under 2.1.1, h...

            I have found and fixed a couple of problems with running pagetree under 2.1.1, however I'm still unsure as to the meaning of your initial error

            "The page you were trying to reach does not exist. You may want to try a search, or browse the site to find the page you were looking for."

            Did this happen when you clicked on a link within an otherise functional pagetree, or did this happen within the area on the page you were expecting the pagetree to be displayed?

            1. Mar 29, 2006

              Troy McKinnon says:

              Door number 2: "or did this happen within the area on the page you were expecti...

              Door number 2:

              "or did this happen within the area on the page you were expecting the pagetree to be displayed?"

              The area "navigation Tree" which was suppose to be produced by the layout's call to the page tree was replaced with the confluence (default?) page not found page.

  9. Apr 18, 2006

    Hellmut Adolphs says:

    guys, any clue why I would get this exception? Cause: com.opensymphony.xwork.co...

    guys, any clue why I would get this exception?

    Cause:

    com.opensymphony.xwork.config.ConfigurationException: There is no Action mapped for namespace /confluence/pages and action name naturalchildren
     at com.opensymphony.xwork.DefaultActionProxy.(DefaultActionProxy.java:72)

    Stack Trace: [hide]com.opensymphony.xwork.config.ConfigurationException: There is no Action mapped for namespace /confluence/pages and action name naturalchildren
    at com.opensymphony.xwork.DefaultActionProxy.(DefaultActionProxy.java:72)
    at com.opensymphony.xwork.DefaultActionProxyFactory.createActionProxy(DefaultActionProxyFactory.java:45)
    ....

    Thanks in advance! 

  10. Apr 18, 2006

    Hellmut Adolphs says:

    Ok, that error I reported just before this post, seems to be related to the serv...

    Ok, that error I reported just before this post, seems to be related to the server Base URL in my configuration which goes something like <server>/confluence

    When I use the page tree macro, it tries to create the URL like this:

    /confluence//confluence/pages/naturalchildren.action?decorator=none&excerpt=false&sort=natural&reverse=false&pageId=264&treeId=1

     If I remove the /confluence from the server base URL, then it messes up all the short URLs generated within confluence.  Any idea why the macro is looking to add /confluence to the base URL?

  11. Apr 19, 2006

    Othman Alaoui says:

    Please change the "Download JAR" link to point to the latest 2.1.xcompatible ver...

    Please change the "Download JAR" link to point to the latest 2.1.x-compatible version of this plugin: 1.2.5. Thanks.

    1. Apr 19, 2006

      Othman Alaoui says:

      I take that back: i am still getting the same NPE I was getting with 1.2.4 with ...

      I take that back: i am still getting the same NPE I was getting with 1.2.4 with 1.2.5 as well:

      2006-04-19 22:43:49,395 ERROR [renderer.radeox.macros.AbstractHtmlGeneratingMacro] execute Error rendering macro with url: root=Table of Contents
      java.lang.NullPointerException
              at com.bnpparibas.confluence.extra.tree.PageTree.getHtml(PageTree.java:88)
              at com.atlassian.confluence.renderer.radeox.macros.AbstractHtmlGeneratingMacro.execute(AbstractHtmlGeneratingMacro.java:44)
              at com.atlassian.renderer.macro.RadeoxCompatibilityMacro.execute(RadeoxCompatibilityMacro.java:149)
              at com.atlassian.confluence.renderer.v2.macros.RadeoxCompatibilityMacro.execute(RadeoxCompatibilityMacro.java:26)
              at com.atlassian.renderer.v2.macro.ResourceAwareMacroDecorator.execute(ResourceAwareMacroDecorator.java:45)
              at com.atlassian.renderer.v2.components.MacroRendererComponent.processMacro(MacroRendererComponent.java:330)
              at com.atlassian.renderer.v2.components.MacroRendererComponent.makeMacro(MacroRendererComponent.java:231)
              at com.atlassian.renderer.v2.components.MacroRendererComponent.makeMacro(MacroRendererComponent.java:131)
              at com.atlassian.renderer.v2.components.MacroRendererComponent.handlePotentialMacro(MacroRendererComponent.java:116)
              at com.atlassian.renderer.v2.components.MacroRendererComponent.render(MacroRendererComponent.java:78)
              at com.atlassian.renderer.v2.V2Renderer.render(V2Renderer.java:54)
              at com.atlassian.renderer.v2.V2RendererFacade.convertWikiToXHtml(V2RendererFacade.java:57)
      1. Apr 19, 2006

        Othman Alaoui says:

        sorry should have given this info: I am using Confluence 2.1.4 I installed the...

        sorry should have given this info:

        • I am using Confluence 2.1.4
        • I installed the plugin through the built-in plugin manager
        • the page containing the pagetree macro displays "Loading ..." and never updates
        • I am using the built-in left navigation theme, which includes my Navigation page which uses pagetree. This left navigation side bar is where the NPE shows up: "Error rendering macro: java.lang.NullPointerException."
        1. Apr 19, 2006

          Othman Alaoui says:

          Just saw your note above: If you just see a message "Loading..." and nothing el...

          Just saw your note above:

          If you just see a message "Loading..." and nothing else, make sure you have Base URL correctly set in your General Configuration settings.

          That fixed the stuck "Loading..." problem. Thanks. Still getting NPE on leftnav however.

          1. Apr 28, 2006

            Guy Fraser says:

            We'll be looking in to this error shortly after we release Builder theme v1.6 (n...

            We'll be looking in to this error shortly after we release Builder theme v1.6 (next few days hopefully).