[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 23.0|DocumentationBuilder:Builder Release Notes] 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. |