Page History

...

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.

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.

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 criteria). Within a list of search terms (e.g. list of labels or metadata), any page matching at least one of the items in the list will be returned (boolean OR relationship within 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.

See also the list-* macros page for an overview.

Requirements

This macro requires Builder 3.0 or above.

Usage

Code Block

 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

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

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 pages amongst the ancestors of the start page descendant/descendants/descendents/down - search for pages amongst the descendants of the start page sibling/siblings - search for pages amongst the siblings of the start page children - search for pages amongst the children of the start page none - don't search, just use the start page
startPage or startFrom	@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

Expand

	List ancestor pages
	List ancestor pages

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

Wiki Markup



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

List of all parent pages (from the current page)
{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

Expand

	List all children pages
	List all children pages

Wiki Markup



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

Expand

	Specifying the starting page for the search
	Specifying the starting page for the search

Wiki Markup



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

Expand

	Searching in more than one space
	Searching in more than one space

h3. Searching in more than one space

Wiki Markup



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}

Expand

	List all pages with specific names
	List all pages with specific names

h3. List all pages with specific names

Wiki Markup



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

Expand

	List pages with given labels
	List pages with given labels

with given labels

Wiki Markup



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}

Expand

	List pages with given metadata
	List pages with given metadata

h3. List pages with given metadata

Wiki Markup



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}

Expand

	Specifying a default page to return
	Specifying a default page to return

h3. Specifying a default page to return

Wiki Markup



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

Hints and Tips

None at present.

Frequently Asked Questions

None at present.

Page tree

Versions Compared

Old Version 3

New Version Current

Key

Requirements

Usage

Parameters

Examples

Hints and Tips

Frequently Asked Questions