Theme Builder Plugin

[All Adaptavist Apps]

Page tree

Versions Compared

Old Version 4

changes.mady.by.user Unknown User (doobya)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (gwilson)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

{with-page} macro

Description

The {with-page} macro does two things:

...

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.

...

Requirements

This macro requires Builder 3.0 or above.

Usage

Code Block
 {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}

...

Property

Required

Default

Notes

direction

(tick)

 

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

(error)

@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

(error)

 

Comma-separated list of spaces to search in

title

(error)

 

Comma-separated list of page titles to search for

label

(error)

 

Comma-separated list of labels the page(s) should have

metadata

(error)

 

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

(error)

 

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

expand
Expand
Display or link to an attachment from an ancestor page
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

 Show image attached to the parent page:
{with-page:direction=up}
 !image.jpg!
{with-page}

Which results in:

Show image attached to the parent pageShow image attached to the parent page
 Wiki Markup

{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:
 Code Block

 Link to "sample.pdf" attached to the first parent page labeled "topic":
{with-page:direction=up|label=topic}
 [^sample.pdf]
{with-page}

Which results in:

{with-page:direction=up|label=topic}
 [^sample.pdf]
{with-page}

 Expand
Find a page in the current tree with a given label and render its attachments in the current page
 Expand
Link to "sample.pdf" attached to the first parent page labeled "topic"Link to "sample.pdf" attached to the first parent page labeled "topic"
 Wiki Markup
Find a page in the current tree with a given label and render its attachments in the current page
 Wiki Markup


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
}
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:
...
 page
 Expand


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
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
 Wiki Markup
 page
{with-page:direction=up|label=homepage}
 {with-page:direction=down|label=sponsors}
  {gallery}
 {with-page}
{with-page}

 Expand
Displaying content in a sidebar specific to the current page's location in the page tree
Displaying content in a sidebar specific to the current page's location in the page tree
 Wiki Markup


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':
...


{code
}
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}
{code}


Which results in:
...
 sidebar
 Expand
 

Forum-specific content for the
Forum-specific content for the sidebar
 Wiki Markup
 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}

...