{builder-hide} Macro
Description
The builder-hide macro is used to hide content in specific contexts, modes and other filters...
Usage
{builder-hide:mode=view|context=page|label=meetings|metadata=mykey:myvalue}
stuff to hide
{builder-hide}
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 |
 |
all decorators |
Only hide the content when a specific decorator us being used, eg. "printable", etc. |
 |
|
| context |
|
all contexts |
Only hide the content for specific context(s), eg. "page", "global", etc. |
|
|
| mode |
|
all modes |
Only hide the content for specific modes, eg. "view", "edit", "dashboard", etc. |
|
|
| space |
|
n/a |
Only hide the content if a specific space (referred to by the Space Key) exists. |
|
|
| page |
|
n/a |
Only hide the content if a specific page (referred to by the page title) exists. |
|
|
| title |
|
n/a |
Only hide the content if the current page has a specific title |
|
|
| label |
|
n/a |
Only hide the content if the the current location (page, news, etc) has the specified label(s), eg. "my:favourite", "meetings", etc. |
|
|
| metadata |
|
n/a |
Metadata associated with the current location in the frormat: "myKey1:myValue1", etc. |
|
3.0 |
| user |
|
All users |
A comma separated list of usernames. Use @anonymous for anonymous users only. |
|
3.0 |
| group |
|
All groups |
A comma separated list of user groups. Use @anonymous for anonymous users only. |
|
3.0 |
| permission |
|
Any permission |
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 |
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-hide:mode=view,edit|context=page,blogpost}
stuff to hide
{builder-hide}
In the example above, "stuff to hide" would only be hiden if the content is being hiden in "view" or "edit" mode and is also either a "page" or "blogpost".
Contexts and Modes
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 hides the context and mode for each page.
View example...
If you view the HTML source of this web page you'll see the following:
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.
Examples
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:
{builder-hide:context=news}
This text will not be shown on news items
{builder-hide}
Hide content on pages and news items
To hide something in multiple contexts, simply separate them with commas:
{builder-hide:context=page,blogpost}
something to hide on pages and news items
{builder-hide}
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:
{builder-hide:mode=edit}
something to hide
{builder-hide}
You can hide something in multiple modes by separating them with commas:
{builder-hide:mode=edit,view}
something to hide
{builder-hide}
Specific modes within specific contexts
If you only want to hide something in view mode within the context of a page, use the following:
{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:
{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.
Hide content based on labels
You can hide content if the current location has one or more of the specified labels:
{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.
Hiding content if a space exists
You can hide content if a space exists by specifying it's space key as follows:
{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.
Hide content based on existence of a page
You can hide content if a specific page (within the current space) exists:
{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.
Hide content if the page has a parent
You can hide content if the current page has a parent page using the following notation:
{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)
Hide content for specific page titles
You can hide content if the current page has a specific title, for example:
{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:
{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:
{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!
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.
CSS Customisation
Not applicable for this macro.
Hints and Tips
You can use this macro, and the associated builder-show 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 based on the privileges within a space, use the [USERGUIDE:show-if] or [USERGUIDE:hide-if] macros that be found in the Visibility Plugin.
Frequently Asked Questions
None at present.
See Also
Added by
Hi,
We are using the following notation in the Builder Theme footer to hide children and attachments on the Home page of a space as well as hide children for pages labeled "category":
{builder-show:context=page,blogpost}{div:class=page-footer}{builder-hide:title=Home}{children}{builder-hide}{menuitem:flat=true}{builder-hide:label=category}{children}{builder-hide}{menuitem:flat=true}{builder-hide:label=hide-attachments}{attachments}{builder-hide}{menuitem:flat=true}{builder-comments}{div}{builder-show}
We can't get this to work. We are using Builder Theme 2.0.9 and Confluence 2.5.1. Any pointers are appreciated!
You had a menuitem closing tag missing and also a menuitem closing tag that had parameters.
For readability, I've split the notation on to several lines with indentation to illustrate:
{builder-show:context=page,blogpost} {div:class=page-footer} {builder-hide:title=Home} {children} {builder-hide} {menuitem:flat=true} {builder-hide:label=category} {children} {builder-hide} {menuitem} <--- missing {menuitem:flat=true} {builder-hide:label=hide-attachments} {attachments} {builder-hide} {menuitem} <-- closing tag has no params {builder-comments} {div} {builder-show}Thanks for the quick reply, Guy. I made those changes but the children are still shown. I've verified that the page label and title are correct. Is it meaningful that we wrap some items in menuitem but some not? I removed those but it didn't seem to make a difference.
Could something at the global theme level be overriding this perhaps?
I'd like to say:
"Hide this menu option if the group is NOT 'such and such group' AND the title is 'one of these titles'." ... is that possible right now.. I know the Approval Workflow plugin has implemented exclamation points so you can do stuff like this. With builder-hide and builder-show, maybe what I'd want to do could be done with something like this (if implemented):
{builder-hide:!group=groupname|title=title1,title2}whatever{builder-hide}Thoughts?
I would like to hide a menu item if I'm within a personal space - can I use the builder-hide macro or do I have to define a certain layout for personal spaces?