{list-pages} macro

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.

Requirements

This macro requires [Theme Builder 2.0] or above.

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.

Parameters

Property	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	@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		Comma-separated list of spaces to search in
title		Comma-separated list of page titles to search for
label		Comma-separated list of labels the page(s) should have
metadata		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		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)

Examples

Basic Use

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

 {list-pages:direction=up}

Which results in:

Unknown macro: {list-pages}

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.

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):

 {list-pages:direction=down}

Which results in:

Unknown macro: {list-pages}

CSS Customisation

To follow.

Hints and Tips

None at present.

Frequently Asked Questions