[All Adaptavist Apps]
Wiki Markup |
---|
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.
{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.
See also the [list-* macros] page for an overview.
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.
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 pages amongst the ancestors of the start page
* _descendant/descendants/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|(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. |