Page History

h1. \{list-pages} macro

h2. Description


The \{list-pages} macro generates a list of pages based on the parameters given to it.  

It allows listing pages based on:

- a specific *page name*,
- page *hierarchy* (parent/child relationships),
- page *labels*, and
- *metadata* _keys_ or _key:value_ pairs which the pages must have.

The \{list-pages}{excerpt}The macro searches for pages based on these properties in the current space by default, or in any number of spaces which can be specified in the macro parameters.{excerpt}

If more than one search criterion is specified (e.g. labels and metadata), then only pages meeting _all_ the selection criteria will be returned and listed by the macro (boolean AND relationship between the search terms).

Finally, if no page is found satisfying the selected parameters, a default page can be specified to be listed by the macro instead.

h2. Requirements

This macro requires [Theme Builder 2.0|Documentation] or above.


h2. Usage

{code}
 {list-pages:direction=ancestors|startPage=My Page|space=DOC|title=Page 1,Page 2|label=test,label2|metadata=key1,key2:value1,key2:value2|default=Default Page} 
{code}

Examples of common structures can be found in the examples at the bottom of this page.

h2. Parameters

||Property||Required||Default||Notes||
||direction|(/)| |The direction (in page hierarchy) that the macro should look in when searching for pages.  The following values are permitted:
* _ancestor/ancestors/up_ - search for the page to render with amongst the ancestors of the start page 
* _descendant/descendants/down_ - search for the page to render with amongst the descendants of the start page 
* _sibling/siblings_ - search for the page to render with amongst the siblings of the start page 
* _children_ - search for the page to render with amongst the children of the start page 
* _none_ - dont search, just use the start page |
||startPage|(x)|@self|The page to start the search from.  The following values are permitted:
* _@self_ - the current page (default) 
* _@root_ - the root of the current page's tree 
* _@parent_ - the parent of the current page 
* _@home_ - the homepage of the current space 
* _pagetitle_ - a named page (either the page title, or spacekey:title) |
||space|(x)| | Comma-separated list of spaces to search in |
||title|(x)| | Comma-separated list of page titles to search for |
||label|(x)| | Comma-separated list of labels the page(s) should have |
||metadata|(x)| |Comma-separated list of metadata _key:value_ pairs, or metadata _keys_ which the pages must posess. If a _key:value_ pair is specified, then the _key_ must have that _value_; if only the _key_ is specified then any _value_ is valid |
||default|(x)| | Specifies a default page to use if no page was found with the previous search parameters.  The following values are permitted:
* _@self_ - the current page (default) 
* _@root_ - the root of the current page's tree 
* _@parent_ - the parent of the current page 
* _@home_ - the homepage of the current space 
* _pagetitle_ - a named page (either the page title, or spacekey:title) |

h2. Examples

h3. List ancestor pages

Let's start with a simple example: listing all ancestor pages (i.e. parent, parent's parent, etc. all the way to the root of the current space).

{code}
 List of all parent pages (from the current page):
{list-pages:direction=up}
{code}

Which results in:

List of all parent pages (from the current page):
{list-pages:direction=up}

As you can see, each page in the space's hierarchy, from the current up to the top (root) is listed as a link to the page itself.

h3. List all children pages

Similarly, we can list all children, and children's children pages from the current page, much like the \{children} macro does, but then recursively (at infinite depth):

{code}
 List of all children pages (from the current page):
{list-pages:direction=down}
{code}

Which results in:

List of all children pages (from the current page):
{list-pages:direction=descendants}

h3. Specifying the starting page for the search

You may specify the page at which the \{list-pages} macro should start searching.  By default (if nothing is specified) this will be the current page.

For instance, to list all pages in a space, specify the spacekey: as the parameter for startPage as follows:

{code}
 List of all children pages in the [Builder|Builder:] space
{list-pages:direction=down|startPage=Builder:}
{code}

Which results in:

List of all children pages in the [Builder|Builder:] space
{list-pages:direction=down|startPage=Builder:}

h3. Searching in more than one space

You can set the \{list-pages} macro to search for pages in more than one space.

By default, the macro will search for pages in the current space.  You can specify a different space with {{startPage=spacekey:}} as per the example above.  Additionally, you can specify a list of spaces to search in:

{code}
 List of pages in the [Builder|Builder:] and [Bubbles|Bubbles:] spaces:
{list-pages:direction=down|startPage=@home|space=Builder,Bubbles}
{code} 

Which results in:

List of pages in the [Builder|Builder:] and [Bubbles|Bubbles:] spaces:
{list-pages:direction=down|startPage=@home|space=Builder,Bubbles}


h3. List all pages with specific names

The \{list-pages} macro can retrieve pages based on their names (page titles).  For this, use the following syntax:

{code}
 List of pages titled "Panel Macros", "Menu Macros", or "Utility Macros" in the [Builder|Builder:] space:
{list-pages:direction=down|startPage=Builder:|title=Panel Macros,Menu Macros,Utility Macros}
{code}

Which results in:

List of pages titled "Panel Macros", "Menu Macros", or "Utility Macros" in the [Builder|Builder:] space:
{list-pages:direction=down|startPage=Builder:|title=Panel Macros,Menu Macros,Utility Macros}

h3. List pages with given labels

The \{list-pages} macro can be used to list pages containing any one label in the list specified.  Pages listed by the macro will have at least one of the labels.

{code}
 List of pages labeled 'builder' or 'theme':
{list-pages:direction=down|label=builder,theme}
{code}

Which results in:

List of pages labeled 'builder' or 'theme':
{list-pages:direction=down|label=builder,theme}

h3. List pages with given metadata

A list of metadata _keys_, or _key:value_ pairs, can be given to the \{list-pages} macro as search criterion.  

If you specify a _key:value_ pair, then the macro will return only pages containing both that _key_ and the specific _value_ for that key.  If you only specify a _key_ then the macro will return all pages containing that _key_, regardless of the _value_.

See the [Metadata plugin page|http://confluence.atlassian.com/display/CONFEXT/Metadata+Plugin+2] for more information on the Metadata plugin and _key:value_ pairs.

{code}
 List of pages authored by [~gfraser] in the [Builder|Builder:] space:
{list-pages:direction=down|startPage=Builder:|metadata=author:gfraser}
{code}

Which results in:

List of pages authored by [~gfraser] in the [Builder:] space:
{list-pages:direction=down|startPage=Builder:|metadata=author:gfraser}


h3. Specifying a default page to return

In order to prevent the macro from returning an empty list in case no pages are found meeting the given search criteria, you may specify a default page to return.

{code}
 List of parent pages:
{list-pages:direction=down|startPage=@root|default=@home}
{code}

Which results in:
List of parent pages:
{list-pages:direction=down|startPage=@root|default=@home}


h2. CSS Customisation

To follow.

h2. Hints and Tips

None at present.

h2. Frequently Asked Questions

None at present.