[All Adaptavist Apps]
Page History
...
{with-page}
...
macro
...
Description
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
...
...
...
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
| Code Block |
|---|
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. h3. 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 | h2. Requirements This macro requires [Builder 3.0|Builder:Builder Release Notes] or above. h2. Usage {code} {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} {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:
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
| |||
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:
|
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.
| Code Block |
|---|
* _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. 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. {code} Show image attached to the parent page: {with-page:direction=up} !image.jpg! {with-page} {code} |
Which
...
results
...
in:
| Expand | ||||
|---|---|---|---|---|
| ||||
Show image attached to the parent 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:
| Code Block |
|---|
} Link to "sample.pdf" attached to the first parent page labeled "topic": {with-page:direction=up|label=topic} [^sample.pdf] {with-page} {code} |
Which
...
results in:
| Expand | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| in:
Link to
|
|
|
|
|
|
|
|
| |||||||||||||
:
h3. |
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.
| Code Block |
|---|
} bq. 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} {code} |
Which
...
results in:
| Expand | ||||
|---|---|---|---|---|
| ||||
in:
bq. 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:
h3. |
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
...
...
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':
| Code Block |
|---|
Forum-specific content for the sidebar {code} {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} {code} |
Which
...
results
...
in:
| Expand | ||||
|---|---|---|---|---|
| ||||
h2. |
Hints
...
and
...
Tips
...
None
...
at
...
present.
...
Frequently
...
Asked
...
Questions
...
None
...
at
...
present.
Overview
Community Forums
Content Tools
Apps