Skip to end of metadata
Go to start of metadata

The builder-show macro isused to show content in specific contexts, modes and other filters...

Usage

{builder-show:mode=view|context=page|label=meetings|metadata=mykey:myvalue}
stuff to show
{builder-show}

Parameters

Note:
Some parameters, marked "Theme Only", can only be used within Builder theme panels, ie. you cannot use them within pages, etc.

The "Ver" column shows which version of Theme Builder the parameter became available in.

Property

Required

Default

Notes

Theme Panels Only

Ver

decorator

(error)

n/a

Only show the content when a specific decorator us being used, eg. "printable", etc.

(tick)

 

action

(error)

n/a

Only show the content for specific action(s), eg. "viewpage". NB: The ".action" part of the action name should not be included.

(tick)

3.0

context

(error)

n/a

Only show the content for specific context(s), eg. "page", "global", etc.

(tick)

 

mode

(error)

all modes

Only show the content for specific modes, eg. "view", "edit", etc.

(tick)

 

space

(error)

n/a

Only show the content if a specific space (referred to by the Space Key) exists.

 

 

spacekey

(error)

current space

The space against which permission checks will be made. Default is current space.

 

 

pagetitle

(error)

current page

the page against which permission checks will be made. Default is current page

 

 

exists

(error)

n/a

Only show the content if a specific page (referred to by the page title) exists. @parent can be used to show data if the page is not at the root level, @child can be used to show data if the page has children.

 

 

pluginkey

(error)

n/a

The key of a plugin which must be enabled for the content to be shown

 

 

hastitle

(error)

n/a

Only show the content if the current page has a specific title

 

 

label

(error)

n/a

Only show the content if the the current location (page, news, etc) has the specified label(s), eg. "my:favourite", "meetings", etc.

 

 

spacelabel

(error)

n/a

Only show the content if the the current space has the specified label(s), eg. "meetings", etc.

 

 

teamlabel

(error)

n/a

Only show the content if the the current space has the specified team label(s), eg. "sales,marketing", etc.

 

 

metadata

(error)

n/a

Metadata associated with the current location in the format: "myKey1:myValue1, myKey1:myValue1, etc". when checking for a key with a specific value. To check for the existance of metadata with any value supply a commas separated list of key names, eg: "mykey1, mykey2, mykey3" or mix & match "mykey1, mykey2:myvalue2"

 

 

user

(error)

n/a

Matches against the current user (NB: modified by withuser) - A comma separated list of usernames. Use @anonymous for anonymous users only, @creator for the creator of the current space, @author for the author of the current page.

 

3.0

withuser

(error)

@current

username that user/group/permission checks should be run against. This includes @anonymous, @creator, @author, @current

 

3.2.2

group

(error)

n/a

A comma separated list of user groups that the current user (NB: modified by withuser) should be a member of

 

3.0

permission

(error)

n/a

A comma separated list of permissions:

  • view - user has view permission
  • comment - user can add comments
  • createpage - user can create pages
  • createnews - user can create news
  • edit - user can edit pages or news
  • remove - user can remove (delete) pages, news or comments
  • attach - user can attach files
  • export - user can export pages or the space
  • createspace - user can create spaces
  • spaceadmin - user is a space admin
  • siteadmin - user is a site admin

 

3.0

recurse

(error)

false

Should parent pages (if applicable) be checked for title, labels and metadata?

  • false - only check the current page (default)
  • true - also check parent pages, eg. does the current page or any of it's parents have the specified label, etc.

 

3.0

restriction

(error)

n/a

display content if the page has a restriction in place (none/view/edit/vieworedit/viewandedit - recursable)

 

3.0

useragent

(error)

n/a

A comma separated list of tokens to match against the user agent string of the requesting browser.

(error)

3.2.1

attachment

(error)

n/a

comma separated list of filenames, one of which must be attached to the current page for the content to be displayed.
NB: This parameter is only processed if context is a page or a blogpost.

(error)

3.2.2

olderthan

(error)

n/a

Content is shown if the current page was modified before the given time period from the current date. The date is shown in this format: olderthan=1y6m1d1h (year/month/day/hour)

 

3.3.0

newerthan

(error)

n/a

Content is shown if the current page was modified after the given time period from the current date. The date is shown in this format: newerthan=1y6m1d1h (year/month/day/hour)

 

3.3.0

flag

(error)

 

Content is shown if one or more of the specified flags are set. See Working with Flags for more details.

3.3.6

notflag

(error)

 

Content is shown if none of the specified flags are set. See Working with Flags for more details.

3.3.6

While none of the parameters are mandatory, you must specify at least one of them for this macro to work.

You can specify multiple values for any parameter, for example:

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

In the example above, "stuff to show" would only be shown if the content is being shown in "view" or "edit" mode and is also either a "page" or "blogpost".

Contexts, Modes and Decorators

You can determine the context and mode for any page by viewing the page source using your browser. A HTML comment output at the top of all pages shows the context and mode for each page.

 View example...

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

You can specify multiple contexts and modes by separating them with commas as shown in the usage example earlier. For the macro content to show, all contexts and modes specified must match.

Examples

 Display content on news items

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

{builder-show:context=news}
{menulink:news}Back to News Summary{menulink}
{builder-show}
 Display content on pages and news items

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

{builder-show:context=page,blogpost}
something to show
{builder-show}
 Display content in edit mode

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:

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

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

{builder-show:mode=edit,view}
something to show
{builder-show}
 Specific modes within specific contexts

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

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

{builder-show:mode=view,edit|context=page,blogpost}
something to show
{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" mode.

 Display content based on UserAgent

You can use the useragent parameter to check for certain sub-strings such as browser names and operating systems in the user agent string. This could be used to tailor content to specific devices such as mobile phones.
Notice in the following code that you can provide a comma separated list of tokens to be tested for. This acts like an OR, if any of the tokens match then the enclosed code will be rendered.

{builder-show:useragent=Firefox,Opera}
You are using FireFox or Opera!
{builder-show}

By combining with the use-layout macro you can switch to a specific layout.
For example suppose you have created a layout for the iPhone.
Do the following on your home page and subsequent page will use your layout:

{builder-show:useragent=iphone}
{use-layout:IPHONE_LAYOUT|latch=true}
{builder-show}
 Display content based on labels

You can display content if the current location has one or more of the specified labels:

{builder-show:label=my:favourite,meetings}
This stuff is either in my favourites list or something to do with meetings!
{builder-show}

Beware! Most people assume that only pages and news articles can have labels, but this is not the case. When viewing space-level pages that aren't normal content pages or news articles, for example when viewing the space labels or even space admin, this macro uses any defined space labels and even team labels.

 Displaying content if a space exists

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

{builder-show:space=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}

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

 Display content based on existence of a page

You can display content only if a specific page exists:

{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.

 Display content if the page has a parent

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

{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)
 Display content for specific page titles

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

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

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

{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!

 Displaying content based on metadata

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.

 Displaying content based on attachments

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

{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}
 Displaying content based on modification date
{builder-show:olderthan=1y6m1d1h}
show this if the current page was modified more than one year, six months, one day and one hour ago.
{builder-show}

CSS Customisation

Not applicable for this macro.

Hints and Tips

You can use this macro, and the associated builder-hide macro to customise navigation and panel content depending on what the user is looking at.

When using either the mode, context or decorator parameters, remember that they only work if used within a panel of the Builder theme. If you put them inside a normal page, etc., they won't work. Even if you use the move-to macro to move something from a page in to a panel, it still won't work - the mode, context and decorator settings will only work if the macro is actually in the panel notation in the theme cofiguration settings.

If you need to show or hide content with more complex conditions, there are extra aliases builder-show2 -> builder-show9 which may be used for nesting.

Multiple conditions are combined in AND mode, so all of the applied conditions need to be true for the content to be shown.
To apply conditions in an OR mode you should use several copies of the show macro, each with separate conditions.

Frequently Asked Questions

None at present.

See Also

  • No labels

10 Comments

  1. Unknown User (jbrown@interthinx.com)

    So I am trying to show a button based on whether the user is on a News/Blog page or a regular Page. I have the following code. The first one works correctly and only shows the create new page button if they are on a regular page. The second one I can't get to work at all. I have tried a context of both "news" and "blogpost". I have tried it without the builder-show tag and the button does show up, but it shows up in all contexts (which I don't want). I only want it showing up if the user is anywhere within the blog/news. Below is my code. What am I dong wrong?

    {builder-show:mode=view|context=page}{compound-menuitem:newpage|caption=New Page}{builder-show}
    {builder-show:context=news}{compound-menuitem:newnews|caption=New News}{builder-show}
    1. When in doubt view the source of the page with the default layout, the mode, context & decorator are shown in a comment at the top.

  2. Unknown User (orgetex)

    How can I arrange to show content only if a user is a member of group1 and group2 but not if a user is only member of group1 or group2?

    1. For AND conditions you can use nesting, eg:

      {builder-show:group=foo}
        {builder-show2:group=bar}
          User is a member of both foo AND bar
        {builder-show2}
      {builder-show}
      

      or flag logic

      {builder-show:group=foo}{set-flag:foomember}{builder-show}
      {builder-show:group=bar|flag=foomember}
        User is a member of both foo AND bar
      {builder-show}
      
      1. Unknown User (orgetex)

        Ahh...nesting and flag... OK.

        I thought it should go using +group2, but using nesting and set-flag provides an tremendous amount of individuality.

        Thanks a lot, cheers.

  3. Unknown User (nestabrook)

    So, I am trying to change the Dashboard Theme so that the site looks more like a website using themebuilder. However, prior to a user logging in, they see all of the "broken" elements in the theme. Is there a way to use this macro, or another one, to show only certain menu items, etc. based on whether someone is looking at the confluence site pre or post login?

    1. This is probably the code you want:

      {builder-hide:user=@anonymous}This content will be hidden from anonymous (aka not logged in) users{builder-hide}
      

      Also when 'dressing' the layout with images, ensure that you use 'builder resources' rather than images attached to pages, since this will allow those images to be accessed by anonymous users even when they do not have 'can use confluence' permission.

      1. Unknown User (nestabrook)

        OK, thanx. Can you point me in the right direction for "builder resources"? I've never used those for image use.

      2. Unknown User (nestabrook)

        I should also mention that I'm using TB 3.2.1.

        1. Ah ... you need Builder 4 for resources.