Page History

h1. \{with-page} macro

h2. 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 [with-* macros] page for an overview.

h3. 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 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 [Theme Builder 2.0|Documentation] 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.

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 the page to render with amongst the ancestors of the start page 
* _descendant/descendants/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|(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 Display or link to an attachment from an ancestor pagespage

Let's start with a simple example: listingrendering allan ancestorimage pages (i.e. parent, parent's parent, etc. all the way to the root attached to the parent page, into the body of the current space)page.

{code}
 ListShow ofimage allattached parent pages (from to the currentparent page):
{with-page:direction=up}
 !image.jpg!
{with-page}
{code}

Which results in:

ListShow ofimage allattached parentto pages (from the currentparent page):
{with-page:direction=up}
 !image.jpg!
{with-page}

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 fromAlthough 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,. much likeSince the \{children} macro does, but then recursively (at infinite depth)page can be found by labels and metadata, the specific page name is not required.  For instance:

{code}
 ListLink of all children pages (from the current page)to "sample.pdf" attached to the first parent page labeled "topic":
{with-page:direction=down=up|label=topic}
 [^sample.pdf]
{with-page}
{code}

Which results in:

List ofLink all children pages (fromto "sample.pdf" attached to the currentfirst parent page) labeled "topic":
{with-page:direction=descendants=up|label=topic}
 [^sample.pdf]
{with-page}


h3. SpecifyingFind thea starting page forin the search

You may specify the page at which the \{with-page} macro should start searching.  By default (if nothing is specified) this will becurrent tree with a given label and render its attachments in the current page

Suppose there is a page somewhere in 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
{with-page:direction=down|startPage=Builder:}
{code}

Which results in:

List of all children pages in the [Builder|Builder:] space
{with-page:direction=down|startPage=Builder:}

h3. Searching in more than one space

You can set the \{with-page} macro to search for pages in more than one space.

By default, the macro will search for pagestree (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}
 bq. Find page labeled 'sponsors' in the current space.page tree, Youknowing canit specifyis a differentchild spaceof with {{startPage=spacekey:}} as pera parent page with 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:label 'homepage', then render the images attached to the page labeled 'sponsors' in a gallery on the current page:
{with-page:direction=downup|startPage=@home|space=Builder,Bubbles}
{code} 

Which results in:

List of pages in the [Builder|Builder:] and [Bubbles|Bubbles:] spaces:
label=homepage}
 {with-page:direction=down|startPage=@home|space=Builder,Bubbles}


h3. List all pages with specific names

The \{with-page} 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:
{with-page:direction=down|startPage=Builder:|title=Panel Macros,Menu Macros,Utility Macroslabel=sponsors}
  {gallery}
 {with-page}
{with-page}
{code}

Which results in:

Listbq. ofFind pagespage titled "Panel Macros", "Menu Macros", or "Utility Macros"labeled 'sponsors' in the [Builder|Builder:] space:
{with-page:direction=down|startPage=Builder:|title=Panel Macros,Menu Macros,Utility Macros}

h3. List pages with given labels

The \{with-page} 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'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=downup|label=builder,themehomepage}
{code}

Which results in:

List of pages labeled 'builder' or 'theme':
{with-page:direction=down|label=builder,themesponsors}

h3. List pages with given metadata

A list of metadata _keys_, or _key:value_ pairs, can be given to the \{with-page} macro as search criterion.  {gallery}
 {with-page}
{with-page}

h3. Displaying content in a sidebar specific to the current page's location in the page tree

If you are specifyusing 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:
{with-page:direction=down|startPage=Builder:|metadata=author:gfraser}
{code}

Which results in:

List of pages authored by [~gfraser] in the [Builder:] space: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:|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':

{code}
{with-page:direction=downup|startPage=Builder:@self|metadatatitle=author:gfraserForum}


h3. SpecifyingThis awill defaultonly pageappear 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.
when you're in the %withpagetitle% section of the space.
 {list-descendants:startPage=@self|label=sticky}
{with-ancestor}
{code}

Which Listresults of parent pages:in: 

{with-page:direction=downup|startPage=@root@self|defaulttitle=@home}
{code}

Which results in:
List of parent pages:
{with-page:direction=down|startPage=@root|default=@home}


h2. CSS Customisation

To follow.Forum}
 This will only appear when you're in the %withpagetitle% section of the space.
 {list-descendants:startPage=@self|label=sticky}
{with-ancestor}


h2. Hints and Tips

None at present.

h2. Frequently Asked Questions

None at present.