The {show-to} macro displays content only to specific users or groups...
There may be times when you want to display content on Pages, [USERGUIDE:News], [USERGUIDE:Comments], the Site Welcome Message and even [user profiles] only to particular users or groups of users and that's what the {show-to} macro is designed to do.
Such a feature allows you to, for example, personalise your site to display custom content and/or navigation depending on the logged in user.
The {show-to} macro shows it's contents based on various settings:
{show-to:user=users|group=groups|space=spaces|trim=true/false|match=all/any}Any content to be
shown{show-to}
Parameters
Parameter
Required
Notes
user
A list of one or more users to show the content to.
group
A list of one or more user groups to show the content to.
space
If the user has the specified privileges within the spaces listed, the content will be shown.
To add a privilege to a specific space, use "SpaceKey:Privilege". Valid privileges are:
Privilege
Notes
view
The user can view the space (default).
edit
The user can edit the space.
admin
The user can administrate the space.
news
The user can add news to the space.
match
By default, if any of the criteria match the logged in user, the content will be shown. However, if you set this parameter to all then every single criteria will have to match before the content will be shown.
This macro should only be used as a simple way to personalise content depending on the logged in user and optionally any space-specific privileges they may have.
This macro should not be used as a security mechanism. While it will only show content in specific circumstances when used normally, the content will still be indexed by the search engine and features such as [USERGUIDE:Page Source] will still display the content, regardless of the way you use this macro.
Do not use this macro to hide confidential or sensitive information because the content will still be visible via some views or features of the software.
This plug-in is available without cost for both commercial and non-commercial purposes. However, if you have found it to be useful, particularly within a commercial environment, please consider making a donation to the author. This will encourage continued development of this and other plug-ins, as well as speeding up the response for your latest maintenance request.
If you wish to donate, it can be done easily with a credit card or bank transfer using Paymate. No account sign-up is required for credit card payments.
This macro is compatible with Confluence 1.3.x and 1.4.x. It has been tested by Adaptavist with Confluence 1.4.1, 1.4.3 and 1.4.4. It has been tested by David Peterson with Confluence 1.5-DR2.
This macro is usually pre-installed with Builder accounts. If you wish to install it on your own Confluence install, please download it from the Confluence Extensions page.
Adaptavist maintain a JIRA Project for tracking bug reports and feature requests for this macro. The currently reported items are shown below:
jiraissues: Could not download[ http://jira.adaptavist.com/secure/IssueNavigator.jspa?view=rss&pid=10030&component=10085&statusIds=1&statusIds=3&statusIds=4&statusIds=5&sorter/field=priority&sorter/order=DESC&tempMax=25&reset=true&decorator=none] : caused by : Circular redirect to 'http://jira.adaptavist.com:80/secure/IssueNavigator.jspa'
All registered users are automatically added to the confluence-users[user group] so as soon as they log in, they are seen as being a member of that group. This provides the perfect mechanism for displaying content to any registered user by requiring the user to be logged in before showing the content:
{show-to:group=confluence-users}*Congratulations, you logged in!*{show-to}
Any logged in user would see the following:
Congratulations, you logged in!
Whereas an anonymous user (which includes a registered user that hasn't logged in yet) would see nothing.
Showing to specific users
You can show content to one or more specific users by adding their user names:
{show-to:user=bob,fred}*Only Bob and Fred can see this!*{show-to}
Only Bob and Fred would see the content:
Only Bob and Fred can see this!
However, if they were not logged in the software would not know that they were Bob or Fred and they would not see the message.
Showing to users depending on their Space privileges
If you have content that refers to specific Spaces, or operations that need to be performed within those spaces, you should only display that content if the user can acces the space or perform the required operations within the space:
{show-to:space=Intranet}[Click here to go to the Intranet|Intranet:]{show-to}
If the logged in user can view the Intranet space, they will see the message. If they can't access the Intranet space, they won't see the message.
{show-to:space=Intranet:edit}*Please edit the relevant page in the Intranet.*{show-to}
Anyone who has edit permissions in the Intranet space would see the message:
Please edit the relevant page in the Intranet.
Showing only if all criteria match
Normally the content will be shown if any of the criteria match, however you can force the macro to only show content if all criteria match:
{show-to:group=staff|space=Intranet|match=all}*Content to show.*{show-to}
The above would show the content only if the logged in user was a member of the staff group and has view access to the Intranet space.
{show-to:group=staff,managers|match=all}*Content to show.*{show-to}
The above would show the content only if the logged in user was both a member of the staff group and also the managers group.
Hints and Tips
When showing content to specific users or groups, etc., remember that logged out users will be not be recognised (either by user name, group or space privileges).
You could create an "advanced-users" group in order to show more advanced information to users in that group.
Frequently Asked Questions
Q
Rather than showing content from specific users, etc., I want to hide it from them - how?
That's a general problem with all Confluence macros. Because there is no clear distinction between an opening and closing tag in Confluence macros, any nesting causes lots of problems.
For example, look at this HTML:
<div><div>fish</div></div>
It's obvious that you have two seperate div tags and the one that contains "fish" is inside the outer div. But look what happens when you use wiki notation:
{div}{div}fish{div}{div}
Because the start and end tags are the same, your divs aren't nested any more Whereas "fish" was inside a nested div tag in the HTML example, with wiki notation it's not even inside a single div tag in the example shown!
For some macros, plugin authors duplicate up - so for div macros we've made div2, div3, ... div9. However, for things like show-to, there aren't any aliases that can be used.
One technique we use a lot is to use show-to and hide-from macros together - it's not ideal but allows most scenarios to be accomodated.
It's our understanding that at some point Atlassian may update the rendering engine to allow closing macro tags to be more clearly defined, but that probably won't happen for at least another 6-12 months.
1) could not access the JIRA link above for issue tracking
2) suggest you add a feature for {show-to:anonymous} or {show-to:authenticated-users}. Currently, with LDAP or other federated authentication schemes (which don't use the default confluence group confluence-users) the trick you suggest does not allow easy hiding/showing of content based on if a user is named or anonymous.
Added by
In Example 3 the macro
ie and the end rather than
By the way I tried to leave this comment as a logged in user but the comment link at the end of the page is only visible when I am an anonyous user.
Tim Baker
INSIDE Contactless
I should have used the escape character
Here we go again
In Example 3
{show-to:space=Intranet:edit}*Please edit the relevant page in the Intranet.*{hide-from}
Should read
{show-to:space=Intranet:edit}*Please edit the relevant page in the Intranet.*{show-to}
show-to rather than hide-from at the end
Comment link to post comments only appears before sign in, when I am anonymous!!
The link to "Confluence Extensions page" in the "Availability" tab is broken (be recoverable) and should be directed to :
http://www.randombits.org/display/CONF/Visibility+Plugin#VisibilityPlugin-Downloads
Are there problems with nested show-tos?
As macros don't have open / close markers, the same tag is reused, then you cannot nest any macros as the following:
{div} A {div} B {div} C {div}Doesn't know if it's output should be:
or
So it assumes the latter, meaning you cannot nest.
That's a general problem with all Confluence macros. Because there is no clear distinction between an opening and closing tag in Confluence macros, any nesting causes lots of problems.
For example, look at this HTML:
It's obvious that you have two seperate div tags and the one that contains "fish" is inside the outer div. But look what happens when you use wiki notation:
{div}{div}fish{div}{div}Because the start and end tags are the same, your divs aren't nested any more
Whereas "fish" was inside a nested div tag in the HTML example, with wiki notation it's not even inside a single div tag in the example shown!
For some macros, plugin authors duplicate up - so for div macros we've made div2, div3, ... div9. However, for things like show-to, there aren't any aliases that can be used.
One technique we use a lot is to use show-to and hide-from macros together - it's not ideal but allows most scenarios to be accomodated.
It's our understanding that at some point Atlassian may update the rendering engine to allow closing macro tags to be more clearly defined, but that probably won't happen for at least another 6-12 months.
1) could not access the JIRA link above for issue tracking
2) suggest you add a feature for {show-to:anonymous} or {show-to:authenticated-users}. Currently, with LDAP or other federated authentication schemes (which don't use the default confluence group confluence-users) the trick you suggest does not allow easy hiding/showing of content based on if a user is named or anonymous.
see http://jira.adaptavist.com/browse/VISIB-22
Where can I find the guide on how to create user groups?
Go in to the Confluence administration console then scroll down to bottom of the navigation on the left - there should be a User Groups option there.