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.

Only pages meeting _all_ the selection criteria will be returned and listed by the macro (boolean AND relationship between the search terms).

The \{list-pages} 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.

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

\{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} 

We'll show examples of common structures 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. Basic Use

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

{code}
 {list-pages:direction=up}
{code}

Which results in:

{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.

h4. 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-pages:direction=down}
{code}

Which results in:

{list-pages:direction=down}




h2. CSS Customisation

To follow.

h2. Hints and Tips

None at present.

h2. Frequently Asked Questions

None at present.