[All Adaptavist Apps]
The builder-hide macro is used to hide content within panels only in specific contexts, modes and other filters, essentially customising the panel content to the location within your site being viewed by the end-user.
{builder-hide:mode=view|context=page|label=meetings|metadata=mykey:myvalue} stuff to hide {builder-hide}
Note:
Some parameters, marked "Theme Only", can only be used within Builder theme panels, ie. you cannot use them within pages, etc.
Property |
Required |
Default |
Notes |
Theme Only |
---|---|---|---|---|
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", 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. |
|
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".
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.
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.
Some common contexts and modes are listed below, along with the associated menulink macro settings to create links to them.
All of these modes have a context of page and apply when working with content pages (including the Space home page):
Mode |
Notes |
Menulink |
---|---|---|
view |
Normal view of a page, including when adding comments to a page |
|
edit |
Edit view of an existing page (see space-pages context for details of adding or copying pages). |
|
view-attachments |
Viewing attachments on a page. |
|
view-information |
Displaying page information. |
|
This mode relates to the view of recent blogposts in a space:
Mode |
Notes |
Menulink |
---|---|---|
view-blogposts |
List of recent blogposts in a space. |
|
All of these modes have a context of space-labels and relate to the label views within spaces.
Mode |
Notes |
Menulink |
---|---|---|
view-labels-popular |
View popular labels |
|
view-labels-all |
View all labels |
|
This mode applies to the index of attachments within a space:
Mode |
Notes |
Menulink |
---|---|---|
view-attachments |
Index of space attachments. |
|
All space administration pages have a single mode as far as we can tell:
Mode |
Notes |
Menulink |
---|---|---|
view-space-administration |
Any page within space admin area, regardless of whether you are viewing or editing, etc. |
|
All of these modes have a context of space-pages and apply to standard space features such as the alphabetical index and site map.
Mode |
Notes |
Menulink |
---|---|---|
create-page |
Applies when creating a new page or copying an existing page. |
|
list-recently-updated |
List of recently updated pages. |
|
list-alphabetically |
Alphabetical page index. |
|
list-content-tree |
Site map (i.e. pages tree view). |
|
These modes relate to global (outside a space) locations:
Mode |
Notes |
Menulink |
---|---|---|
rss |
RSS Feed Builder |
|
more to follow
To display some content only on news items (blogposts), you must use the macro within a panel in the Builder theme:
{builder-hide:context=news} {menulink:news}Back to News Summary{menulink} {builder-hide}
To hide something in multiple contexts, simply separate them with commas:
{builder-hide:context=page,blogpost} something to hide {builder-hide}
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}
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.
You can display content if the current location has one or more of the specified labels:
{builder-hide:labels=my:favourite,meetings} This stuff is either in my favourites list or something to do with 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 and even team labels.
You can hide content only if a space exists by specifying it's space key as follows:
{builder-hide: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-hide}As you can see, this is ideal for customising content based on which spaces a user has privilegs to access.
You can display content only if a specific page exists:
{builder-hide:page=My Page} {include:My Page} {builder-hide}In the example hiden 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 hide 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 hide content or links if a specific page exists within the current space.
You can display content if the current page has a specific title, for example:
{builder-hide:title=My Homepage} Hi all, this must be my home page because it's title is "My Homepage"! {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.
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-hide: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-hide}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-hide:title=Home}{add-label:home-page}{builder-hide}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!
Alain to fill this bit in as I have no idea how it works! Also note the hierarchical nature of the checking on this.
Not applicable for this macro.
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 or context 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.
If you need to hide or hide content based on the privileges within a space, use the hide-if or hide-if macros that be found in the Visibility Plugin.
None at present.