{builder-hide} Macro

Description

The builder-hide macro is

Excerpt
used to hide content in specific contexts, modes and other filters

...

Usage

Code Block
{builder-hide:mode=view\|context=page\|label=meetings\|metadata=mykey:myvalue} stuff to hide {builder-hide}

...

Property	Required	Default	Notes	Theme Panels Only	Ver
decorator	all decorators	n/a	Only hide the content when a specific decorator us being used, eg. "printable", etc.
contextaction	all contexts	n/a	Only hide the content for specific contextaction(s), eg. "page", "global", etcviewpage". NB: The ".action" part of the action name should not be included.		3.0
modecontext	all modes	n/a	Only hide the content for specific modescontext(s), eg. "viewpage", "editglobal", "dashboard", etc.
spacemode	n/a	all modes	Only hide the content if a specific space (referred to by the Space Key) exists.for specific modes, eg. "view", "edit", etc.
pagespace		n/a	Only hide the content if a specific page space (referred to by the page titleSpace Key) exists.
titlespacekey		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	n/a	Only hide the content if the current page has a specific title
labelpage		n/a	Only hide the content if the the current location (page, news, etc) has the specified label(s), eg. "my:favourite", "meetings", etca specific page (referred to by the page title) exists. @parent can be used to hide data if the page is not at the root level, @child can be used to hide data if the page has children.
metadatapluginkey		n/a	Metadata associated with the current location in the frormat: "myKey1:myValue1", etc.		The key of a plugin which must be enabled for the content to be shown
title	3.0	action		n/a	A comma separated list of actions (eg: viewpage/login/logout) where the content should be hidden		3.0
spacekey		current space	The space against which checks will be made		3.0
pagetitle		current page	The page against which checks will be made		3.0
Only hide the content if the current page has a specific title
label	pluginkey		n/a	The key of a plugin which must be enabled for the content to be hidden		Only hide the content if the the current location (page, news, etc) has the specified label(s), eg. "my:favourite", "meetings", etc.		3.0
spacelabel		n/a	A comma separated list of labels applied to the space for which the content should be hidden		3.0	Only hide the content if the the current space has the specified label(s), eg. "meetings", etc.
teamlabelmetadata		n/a	comma separated list of metadata name:value pairs where the content should be hidden (recursable)		3.0	Only hide the content if the the current space has the specified team label(s), eg. "sales,marketing", etc.
metadatateam		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	A comma separated list of team-labels applied to the space for which the content should be hidden		3.0	user		All users	A comma separated list of usernames. Use `@anonymous` for anonymous users only .	3.0
asuserrestriction		@current	n/a	hide content if the page has a restriction in place (none/view/edit/vieworedit/viewandedit - recursableUsername that user/group/permission checks should be run against (inc @anonymous, @creator, @author, @current)		3.0
permissionuseragent	Any 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		All groups	hide 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
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 hidden. NB: This parameter is only processed if context is a page or a blogpost.		3.2.2
olderthan		n/a	Content is hidden 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 hidden 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 hidden if one or more of the specified flags are set. See Working with Flags for more details.	3.3.6
notflag			Content is hidde if none of the specified flags are set. See Working with Flags for more details.	3.3.6	attachment		n/a	Hides content if page or news item contains specified attachments		3.2.2

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:

Code Block
{builder-hide:mode=view,edit\|context=page,blogpost} stuff to hide {builder-hide}

...

Expand

	View example...
	View example...

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

No Format

<!-- main.vmd
  themebuilder : 'com.adaptavist.confluence.sitebuilder.SiteBuilderVelocityHelper@524c9770'/'$themebuilder.initialise'
  spaceKey : 'USERGUIDE'
  pageId : '10578'
  currentURL : '/pages/viewpage.action?spaceKey=USERGUIDE&title=builder-hide+macro'
  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 hiden in the usage example earlier. For the macro content to hide, all contexts and modes specified must match.

...

Expand

	Hide content on news items
	Hide content on news items

To hide some content only on news items (blogposts), you must use the macro within a panel in the Builder theme:
Code Block
{builder-hide:context=news}
This text will not be shown on news items
{builder-hide}

Expand

	Hide content on pages and news items
	Hide content on pages and news items

To hide something in multiple contexts, simply separate them with commas:
Code Block
{builder-hide:context=page,blogpost}
something to hide on pages and news items
{builder-hide}

Expand

	Hide content in edit mode
	Hide 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 hide something when it's being edited (eg. editing a page or news item), use the following:
Code Block
{builder-hide:mode=edit}
something to hide
{builder-hide}
You can hide something in multiple modes by separating them with commas:
Code Block
{builder-hide:mode=edit,view}
something to hide
{builder-hide}

Expand

	Specific modes within specific contexts
	Specific modes within specific contexts

If you only want to hide something in view mode within the context of a page, use the following:
Code Block
{builder-hide:mode=view|context=page}
something to hide
{builder-hide}
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-hide:mode=view,edit|context=page,blogpost}
something to hide
{builder-hide}
In the example above, the content would be hiden 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.

Expand

	Hide content based on UserAgent
	Hide 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 hide incompatible content from devices such as mobile phones.
Useragent will accept 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 not be rendered.
For example you could hide Flash content from iPhones like this:
Code Block
{builder-hide:useragent=iphone}
This content won't be rendered on iphone.
{builder-hide}

Expand

	Hide content based on labels
	Hide content based on labels

You can hide content if the current location has one or more of the specified labels:
Code Block
{builder-hide:labels=my:favourite,meetings}
don't show this on content labelled as the users' favourite or meetings
{builder-hide}
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.

Expand

	Hiding content if a space exists
	Hiding content if a space exists

You can hide content if a space exists by specifying it's space key as follows:
Code Block
{builder-hide:space=ACCOUNTS}
The space with key "ACCOUNTS" does not exist!
{builder-hide}
As you can see, this is ideal for customising content based on which spaces a user has privilegs to access. If the user doesn't have access to a space, it's as if the space doesn't exist.

Expand

	Hide content based on existence of a page
	Hide content based on existence of a page

You can hide content if a specific page (within the current space) exists:
Code Block
{builder-hide:page=My Page}
The page "My Page" does not exist!
{builder-hide}
This is really useful because you can show warnings or links, etc., if pages don't exist. For example, you might want a legal disclaimer in a space and you could warn users if it doesn't exist.

Expand

	Hide content if the page has a parent
	Hide content if the page has a parent

You can hide content if the current page has a parent page using the following notation:
Code Block
{builder-hide:page=@parent}
This page does not have a parent page!
{builder-show}
This is useful because you often want to include specific navigation on pages that do not have a parent page, for example you might want to include the pagetree macro on your home page to ease navigation.
Pages which don't have a parent are:
The space homepage
Orphan pages (pages within a space that don't have a parent)

Expand

	Hide content for specific page titles
	Hide content for specific page titles

You can hide content if the current page has a specific title, for example:
Code Block
{builder-hide:title=My Homepage}
This is not my home page!
{builder-hide}
This can come in handy if you are using templates to generate content and want to hide something based on the page title.
Alternatively, you might want a specific page title to be used whenever a certain template is used, for example:
Code Block
{builder-hide:title=Meeting}
(!) Please rename this page to "Meeting" to aid consistency throughout this site.
{builder-hide}
Another use is to add labels to pages based on their title:
Code Block
{builder-hide:title=Home}{add-label:not-home-page}{builder-hide}
Simply add that to the Header panel in theme config and any page that is not called "Home" will get a label of "not-home-page" added to it thanks to the add-label macro. This is useful because it allows you to search all pages that aren't a home page within the site!

Expand

Hiding content based on metadata

Alain to fill this bit in as I have no idea how it works! Also note the hierarchical nature of the checking on this.is useful because it allows you to search all pages that aren't a home page within the site!

Expand

	Hiding content based on attachments
	Hiding content based on attachments

This works if used in a page or a news item.

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

This works if used in a page or a news item.

Expand

	Displaying content based on modification date
	Displaying content based on modification date

Wiki Markup

Code Block

{builder-hide:

attachment=foo.jpg,bar.png

olderthan=1y6m1d1h}
hide this if

either foo.jpg or bar.png are attached to the current page/news

 the current page was modified more than one year, six months, one day and one hour ago.
{builder-hide}

CSS Customisation

Not applicable for this macro.

...

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 based on the privileges within a space, use the show-if or hide-if macros that be found in the Visibility Pluginpanel, 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-hide2 -> builder-hide9 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 hidden.
To apply conditions in an OR mode you should use several copies of the hide macro, each with separate conditions.

Frequently Asked Questions

...

Page tree

Versions Compared

Old Version 25

New Version Current

Key

{builder-hide} Macro

Description

Usage

CSS Customisation

Frequently Asked Questions

See Also

Page tree

Page History

Versions Compared

Old Version 25

New Version Current

Key

{builder-hide} Macro

Description

Usage

CSS Customisation

Frequently Asked Questions

See Also