Access Keys:
Skip to content (Access Key - 0)

Adaptavist Documentation Move

This documentation is deprecated. Adaptavist's documentation has moved to a new location where it is maintained and updated. Please visit Adaptavist's new Documentation area.

builder-show macro

The builder-show macro is used 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 n/a Only show the content when a specific decorator us being used, eg. "printable", etc.  
action n/a Only show the content for specific action(s), eg. "viewpage". NB: The ".action" part of the action name should not be included.   3.0
context n/a Only show the content for specific context(s), eg. "page", "global", etc.  
mode all modes Only show the content for specific modes, eg. "view", "edit", etc.  
space n/a Only show the content if a specific space (referred to by the Space Key) exists.    
spacekey current space The space against which permission checks will be made. Default is current space.    
pagetitle current page the page against which permission checks will be made. Default is current page    
exists 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 n/a The key of a plugin which must be enabled for the content to be shown    
hastitle n/a Only show the content if the current page has a specific title    
label 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 n/a Only show the content if the the current space has the specified label(s), eg. "meetings", etc.    
teamlabel n/a Only show the content if the the current space has the specified team label(s), eg. "sales,marketing", etc.    
metadata 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 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 @current username that user/group/permission checks should be run against. This includes @anonymous, @creator, @author, @current   3.2.2
group 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 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 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 n/a display content if the page has a restriction in place (none/view/edit/vieworedit/viewandedit - recursable)   3.0
useragent n/a A comma separated list of tokens to match against the user agent string of the requesting browser. 3.2.1
attachment 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.
3.2.2
olderthan 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 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   Content is shown if one or more of the specified flags are set. See Working with Flags for more details. 3.3.6
notflag   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...

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

Display content on pages and news items

Display content in edit mode

Specific modes within specific contexts

Display content based on UserAgent

Display content based on labels

Displaying content if a space exists

Display content based on existence of a page

Display content if the page has a parent

Display content for specific page titles

Displaying content based on metadata

Displaying content based on attachments

Displaying content based on modification date

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



View old comments


Adaptavist Theme Builder Powered by Atlassian Confluence