The {pagetree} macro, is used for displaying a tree view of the page hierarchy.
The {pagetree} macro displays a tree view of the hierarchy of pages using a user-definable page as its root. It can display both the page title and any excerpt that is inside the page. The tree entires can be sorted by title, creation or modification date and may also be reversed.
The {pagetree} macro parameters define the way that the entries are sorted, whether the excerpt should be included or not and the page that is to be the root of the tree.
{pagetree:root=myPage|excerpt=true}
Parameters
Parameter
Required
Default
Notes
root
Space Homepage
The page from which the tree view will start (ie. it's first "root" node). This setting defaults to the Space Homepage (as defined in [USERGUIDE:Space Admin]) but can also be:
any page title — the title of a page to use as the root node
@self — the current page
@parent — the parent page for the current page being viewed
excerpt
false
Whether excerpts should be displayed or not
sort
natural
The order in which pages should be sorted, this paramater can take one of four values
natural — Natural sort order is the order that most people would expect, ie 'title 10' comes after 'title 2'
bitwise — Bitwise sorting is confluence's default mode of sorting, using this alogorithm 'title 10' comes before 'title 2' since '1' is less than '2' (the zero never gets considered)
creation — Sorts the pages in the order that they were created
modified — Sorts the pages in the order of their last modification date
reverse
false
Setting this parameter to true will reverse the order of sorting
This plug-in is available without cost for both commercial and non-commercial purposes.
This software is released under the following license:
Copyright (c) 2005, BNP Paribas
By william jones & zohar melamed
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the BNP Paribas nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This macro is compatible with Confluence 1.3.x, 1.4.x and 2.x. It has been tested by Adaptavist with Confluence 2.1.
To display a tree starting with the space home page, use the macro as follows:
{pagetree}
Which results in:
Unknown macro: {pagetree}
To display the tree starting from a specific page, use the root parameter as follows:
{pagetree:root=Macros}
Which produces the following output:
Unknown macro: {pagetree}
You can also specify the root page as "@self" for the current page or "@parent" for the parent of the current page.
Displaying page excerpts
Excerpts embedded into pages may be displayed alongside the link to the page by setting the excerpt flag to true
{pagetree:root=Navigation and Lists|excerpt=true}
Which looks like this:
Unknown macro: {pagetree}
Bitwise sort order
Bitwise sorting simply takes each character of the title and compares it with the next title in order to decide which should be displayed first. This is the simplest kind of sorting, and is used by confluence in most places.
{pagetree:root=pagetree macro|sort=bitwise}
Which looks like this:
Unknown macro: {pagetree}
Natural sort order
Bitwise sorting works very well in most cases however when your title contains a number of some kind it starts to break down. A bitwise sort will think that 'title 10' should come after 'title 1' but before 'title 2', since when the bitwise sort gets to the first digit in 'title 10' it doesnt understand that the zero should also be taken into account.
Natural sorting is very similar to bitwise sorting, however as the two titles are being compared the algorithm checks to see if the characters it is comparing are numbers or not. If they are numbers then it works along the title until it finds something that isnt a number and then uses the whole number value to compare against the other title.
Since this method of sorting produces more reliable results than the standard bitwise sort used elsewhere in confluence, it has been chosen as the default sort method for the {pagetree} macro
{pagetree:root=pagetree macro}
Which looks like this:
Unknown macro: {pagetree}
Creation Date sort order
There may be occasions when you need to sort by the date that the page was created (first to last / oldest to newest), to do this you set the sort aglorithm to 'creation' as can be seen below.
{pagetree:root=pagetree macro|sort=creation}
Which looks like this:
Unknown macro: {pagetree}
Modification Date sort order
There may be occasions when you need to sort by the date that the page was last modified (first to last / oldest to newest), to do this you set the sort aglorithm to 'modified' as can be seen below.
{pagetree:root=pagetree macro|sort=modified}
Which looks like this:
Unknown macro: {pagetree}
Reversing the sort order
You can also display any of the sort orders in reverse order by setting the reverse parameter to true
{pagetree:root=pagetree macro|reverse=true}
Which produces a reverse-alphabetical sort as can be seen below:
Unknown macro: {pagetree}
Reverse sorting however may be more useful when used in conjunction with the modification or creation date sorting, for example the following code produces the pagetree with the most recently modified page at the top.
Would it be possible to add some options to pretty up some of the formatting when excerpts are displayed? I neet to turn it on, but we have excerpts that have muliple lines and the pagetree macro displays these lines left justified under the node. Maybe even just indenting to the top line of the excerpt would look better. Thoughts?
It's a little odd that using root=@parent doesn't show the actual root page. If you want to, in effect, show how the current page fits into a larger structure (i.e., as the child of the parent, along with the siblings and the page's children), you have to show the entire structure.
root=@self similarly only shows children, which is great if you've labeled something "here are the children" but confusing if you haven't and useless if there are no children.
It would be more helpful if @parent showed the parent and the children, etc., of the parent.
Anyway of modifying this macro to allow other parameters like "showroot=true"?
Open
Added by
Would it be possible to add some options to pretty up some of the formatting when excerpts are displayed? I neet to turn it on, but we have excerpts that have muliple lines and the pagetree macro displays these lines left justified under the node. Maybe even just indenting to the top line of the excerpt would look better. Thoughts?
It's a little odd that using root=@parent doesn't show the actual root page. If you want to, in effect, show how the current page fits into a larger structure (i.e., as the child of the parent, along with the siblings and the page's children), you have to show the entire structure.
root=@self similarly only shows children, which is great if you've labeled something "here are the children" but confusing if you haven't and useless if there are no children.
It would be more helpful if @parent showed the parent and the children, etc., of the parent.
Anyway of modifying this macro to allow other parameters like "showroot=true"?
Charlie at ETR Associates
We need a version of this plugin that lists all the pages inside a space, not just those grouped under the space home page.
Cheers,
Kalle Hallivuori
Sulake Corporation Oy
Yes, we need this too please.
It would probably be better to just link to the Space Tree View which you can do with the [menulink macro] or the link-to macro