The {with-page} macro does two things:
- Searches for a page based on the parameters specified
- Renders the macro body in the context of the page that was found.
See also the with-* macros page for an overview.
1. Retrieving a page
Pages can be retrieved 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.
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.
2. Rendering in the context of the page that was found
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 |
Requirements
This macro requires Builder 3.0 or above.
Usage
{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.
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 the page to render with amongst the ancestors of the start page
- descendant/descendants/descendents/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
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
Display or link to an attachment from an ancestor page
Let's start with a simple example: rendering an image attached to the parent page, into the body of the current page.
Show image attached to the parent page:
{with-page:direction=up}
!image.jpg!
{with-page}
Although image.jpg is attached to the parent page, it is rendered in this page. The body of the macro is the same syntax as if it were written in the parent page.
Similarly, any attachment to any parent page can be rendered or linked to the current page. Since the page can be found by labels and metadata, the specific page name is not required. For instance:
Link to "sample.pdf" attached to the first parent page labeled "topic":
{with-page:direction=up|label=topic}
[^sample.pdf]
{with-page}
Find a page in the current tree with a given label and render its attachments in the current page
Suppose there is a page somewhere in the current tree (not necessarily a direct parent, child or sibling) which has attachments we want to use in the current page. We can combine {with-page} macros, first searching up the tree, then within that macro search down the tree again, looking for the page. Finally, we provide markup making use of the attachments found.
Find page labeled 'sponsors' in the current page tree, knowing it is a child of a parent page with the label 'homepage', then render the images attached to the page labeled 'sponsors' in a gallery on the current page:
{with-page:direction=up|label=homepage}
{with-page:direction=down|label=sponsors}
{gallery}
{with-page}
{with-page}
Which results in:
Find page labeled 'sponsors' in the current page tree, knowing it is a child of a parent page with the label 'homepage', then render the images attached to the page labeled 'sponsors' in a gallery on the current page
Unknown macro: {with-page}
Unknown macro: {with-page}
| There are no images attached to this page. |
Unknown macro: {with-page}
Displaying content in a sidebar specific to the current page's location in the page tree
If you are using a page to include in a sidebar on all pages in a space, you can use the {with-page} macro to show content in the sidebar depending on the location of the current page.
For instance, if you have a Forum set up (using the Bubbles plugin) you can show information in the sidebar relevant to the forum, only on forum pages.
In this example, we will display a list of child pages to the Forum page, labeled 'sticky':
Forum-specific content for the sidebar
{with-page:direction=up|startPage=@self|title=Forum}
This will only appear when you're in the %withpagetitle% section of the space.
{list-descendants:startPage=@self|label=sticky}
{with-ancestor}
Which results in:
Forum-specific content for the sidebar
Unknown macro: {with-page}
This will only appear when you're in the %withpagetitle% section of the space.
Unknown macro: {list-descendants}
Unknown macro: {with-ancestor}
Hints and Tips
None at present.
Frequently Asked Questions
None at present.