{builder-comments} Macro

Description

This macro defines where the page/news comments, if enabled, will be shown within the theme layout.

Users can toggle the display of this macro using the link output from the menulink macro with a destination of comments.

Usage

{builder-comments}

Note:
This macro can only be used inside panels within the theme configuration screen. You cannot use it in pages or news articles, etc.

Parameters

This macro has no parameters.

Examples

Basic Use

Add the macro to any panel in theme configuration to display the comments in that panel:

{builder-comments}

CSS Customisation

To follow.

Hints and Tips

A common requirement is to only show comments to users in a specific group such as content authors. This is really handy because it allows content authors to discuss edits to pages, etc., using comments without cluttering up pages for normal visitors:

{show-to:groups=content-authors}{builder-comments}{show-to}

We've used the show-to macro and set it up so that the comments are only shown to people in a "content-authors" user group (this group doesn't exist by default so you'd have to create it or use a different group).

Ideally you should also include the "confluence-administrators" group (which all administrators are added to automatically on Confluence installations that don't use LDAP):

{show-to:groups=content-authors,confluence-administrators}{builder-comments}{show-to}

Warning:
Remember that comments are searchable - even if they aren't displayed on pages, they may still appear in search results.

If you want a more flexible way of choosing which pages display comments, you can use the builder-show macro in such a way as to only show comments when a specific label is added to the page, etc.

{builder-show:label=showcomments}{builder-comments}{builder-show}

That would only show the comments block on pages that have a "showcomments" label.

Frequently Asked Questions

Why are my comments not shown?

First of all, check that the following wiki notation is included in one of the theme panels:

{builder-comments}

If it's not, then add it

Also, check that the panel which contains the macro is enabled - if the panel isn't shown, it's contents aren't shown.

If you have hidden comments (eg. using the "Hide Comments" link), then they will not be shown on any pages until you re-display them again. There are a few ways you can display comments...

The best way is to use the menulink macro to display a link or menuitem that allows users to show/hide comments ¹ :

{menuitem:flat=true}{menulink:comments}Show comments (%count%){menulink}{menuitem}

Footnotes

Reference	Notes
1	This link is included as default on the View menu for pages that have comments.

Which displays: Show comments (23)

We've wrapped the link in the menuitem macro so that pages which do not have comments will not display an inactive link.

Another alternative is to allow the user to post new comments ² :

{menuitem:flat=true}{menulink:newcomment}Post a comment{menulink}{menuitem}

Footnotes

Reference	Notes
2	If the user has sufficient privileges, they'll see this link on the Edit > New menu

Which displays:

The disadvantage of this second approach is that it doesn't let the user know if there are any existing comments until they click the link. Also, if the user does not have permission to add comments, they won't see the link.

A third approach is to include the showComments=true setting on the page URL. For example, the URL to this page is:

http://www.adaptavist.com/display/USERGUIDE/builder-comments+macro

You would change that to:

http://www.adaptavist.com/display/USERGUIDE/builder-comments+macro?showComments=true

Anyone accessing this link would automatically get the display of comments switched on, regardless of what previous settings they had used.