{builder-show:mode=view,edit|context=page,blogpost}
stuff to show
{builder-show}

If you view the HTML source of this web page you'll see the following:

<!-- main.vmd
  themebuilder : 'com.adaptavist.confluence.sitebuilder.SiteBuilderVelocityHelper@524c9770'/'$themebuilder.initialise'
  spaceKey : 'USERGUIDE'
  pageId : '10583'
  currentURL : '/pages/viewpage.action?spaceKey=USERGUIDE&title=builder-show+macro&focusedCommentId=11666379'
  contextPath : ''
  spaceName : 'User Guides'
  decorator : '$decorator'
  printable : 'false'
  mailId : '$mailId'
  mode : 'view'
  context : 'page'
-->

To display some content only on news items (blogposts), you must use the macro within a panel in the Builder theme:

Code Block
{builder-show:context=news} {menulink:news}Back to News Summary{menulink} {builder-show}

To show something in multiple contexts, simply separate them with commas:

Code Block
{builder-show:context=page,blogpost} something to show {builder-show}

When you change the view of something, eg. look at the normal view or editable view, the "mode" changes and you can take advantage of this to customise your theme depending on which mode is currently active. For example, if you only want to show something when it's being edited (eg. editing a page or news item), use the following:

Code Block
{builder-show:mode=edit} something to show {builder-show}

You can show something in multiple modes by separating them with commas:

Code Block
{builder-show:mode=edit,view} something to show {builder-show}

If you only want to show something in view mode within the context of a page, use the following:

Code Block
{builder-show:mode=view|context=page} something to show {builder-show}

When more than one parameter of the macro is specified, both parameters must match so in the example above the user must be looking at a page context in view mode.

You can specify multiple modes and contexts, for example:

Code Block
{builder-show:mode=view,edit|

You can show content only if a space exists by specifying it's space key as follows:

Code Block
Code Block
{builder-show:mode=view,edit|context=page,blogpost} something to showspace=ACCOUNTS} Here's some info about the accounts space, but you'll only see this if you have privileges to access the accounts space. {builder-show}

In the example above, the content would be shown if the user is looking at either a "page" or a "blogpost" (news item) that must also be in either the "view" or "edit" modeAs you can see, this is ideal for customising content based on which spaces a user has privilegs to access.

You can show content only if a space exists by specifying it's space key as followsthe current page has a parent page using the following notation:

Code Block
{builder-show:spacepage=ACCOUNTS@parent} Here'sThis some info about the accounts space, but you'll only see this if you have privileges to access the accounts space. {builder-show}

As you can see, this is ideal for customising content based on which spaces a user has privilegs to access.

page has a parent page! {builder-show}

This is useful because you often want to include additional navigation on pages that have a parent page, for example you might want to include the scrollbar macro to show a linear navigation bar.

Pages which don't have a parent are:

• The space homepage
• Orphan pages (pages within a space that don't have a parent)

You can display content if the current page has a specific title, for example:

Code Block
{builder-show:title=My Homepage} Hi all, this must be my home page because it's title is "My Homepage"!

You can display content only if a specific page exists:

Code Block
{builder-show:page=My Page} {include:My Page} {builder-show}

In the example shown above, we only include the page if it exists. This hides the nasty error message that the include macro generates if that page does not exist. While it might seem a little strange to only show things if a specific page exists (especially considering you know the title of that page), it's extremely useful in scenarios where you are using templates and only want to show content or links if a specific page exists within the current space.

You can show content only if the current page has a parent page using the following notation:

Code Block
{builder-show:page=@parent} This page has a parent page! {builder-show}

This is useful because you often want to include additional navigation on pages that have a parent page, for example you might want to include the scrollbar macro to show a linear navigation bar.

Pages which don't have a parent are:

• The space homepage
• Orphan pages (pages within a space that don't have a parent)

You can display content if the current page has a specific title, for example:

Code Block
{builder-show:title=My Homepage} Hi all, this must be my home page because it's title is "My Homepage"! {builder-show}

This can come in handy if you are using templates to generate content and want to show something based on the page title.

Another use is if users are constantly using a page title that causes problems, for exmaple they might call a page "Meetings" and you want them to call it "yyyy/mm/dd - Meeting with x, y, z") - as such you could add this to the Title panel within theme configuration:

Code Block
{builder-show:title=Meeting} You muppet! Use a more descriptive page title that includes the date (and time if appropriate), type of meeting and who was involved, etc. {builder-show}

OK, you might not want to be that harsh in explaining to users that "Meeting" isn't a great page title and that they should use something more descriptive, but you get the general idea.

Another use is to add labels to pages based on their title:

Code Block
{builder-show:title=Home}{add-label:home-page}{builder-show}

Simply add that to the Header panel in theme config and any page called "Home" will get a label of "home-page" added to it thanks to the add-label macro. This is useful because it allows you to search all home pages within the site!

Enter a list of metadata keys or metadata key:value pairs, if the metadata is found then the item will be shown/hidden. Ths check is recursable.

Enter a list of metadata keys or metadata key:value pairs, if the metadata is found then the item will be shown/hidden. Ths check is recursable.

This only works if it is used inside a page or news item

Code Block
{builder-show:attachment=foo.jpg,bar.png} show this if either foo.jpg or bar.png are attached to the current page/news {builder-show}