The {with-page} macro does two things:
See also the with-* macros page for an overview.
Pages can be retrieved based on:
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.
The {with-page} macro then renders the wiki markup in the macro body as if the markup were in the body of the page that was found.
Within the body of the macro, the following variables are replaced by the contents given in the following table:
Variable |
Replacement |
---|---|
%withceoid% |
the database id of the page |
%withceotitle% |
the title of the page |
%withceoname% |
the title of the page |
%withpageid% |
the database id of the page |
%withpagetitle% |
the title of the page |
%withpagename% |
the title of the page |
This macro requires Builder 3.0 or above.
{with-page:direction=ancestors|startPage=My Page|space=DOC|title=Page 1,Page 2|label=test,label2|metadata=key1,key2:value1,key2:value2|default=Default Page} |
Examples of common structures can be found in the examples below.
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:
|
|
startPage |
@self |
The page to start the search from. The following values are permitted:
|
|
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:
|
|
|
|
None at present.
None at present.