The {rate} macro allows visitors to rate various aspects of your content and even themselves...

If you want to get feedback - on just about anything - then this macro is idea. It's a customisable rating panel with the following features:

• Very clean interface
• Two "themes" to choose from
• When rating, there is no page refresh
• Ratings can be cleared
• Ability to have multiple ratings on one page
• Ability to use ratings just about anywhere: Pages, News, User Profiles, etc
• Ability to retract your vote should you change your mind
• Ability to view results before casting your vote

Note: This macro is currently only compatible with Confluence 2.0 and requires JavaScript to function correctly.

This macro is used as shown below:

{rate:title=t|theme=m|key=k|display=mode}

Parameters

Parameter	Required	Default	Notes
title		Article Rating	An optional custom title to use, for example: User Rating
theme		builder	The theme (look and feel) to use for the ratings panel: builder (default) - The default theme using emoticons and coloured stars, designed for more "glossy" looking sites such as those using the Builder theme dynamic - A more conventional looking theme with dynamic feedback when voting.
key		Content ID	If you are including more than one rating in the same piece of content (such as a single page), you need to supply a unique "key" for each one (otherwise they'll all display the same results). The key must consist only of numbers and letters (no spaces or other characters).
display		default	The display mode to use, which can be: default (default, supprisingly) - shows the rating panel if the user hasn't yet voted, or the results if they have results - displays the results panel (doesn't allow voting) percentage - display the average rating value (which is the same as the percentage)

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 PayPal. No account sign-up is required for credit or debit card payments.

This software is released under a BSD License

© 2005 Adaptavist.com Limited

This macro has been tested by Adaptavist with Confluence 2.0.

It does not currently work with Confluence 1.4.x or earlier.

For download and installation instructions, please see the online 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:

• rate-table macro
• [USERGUIDE:vote macro]
• [USERGUIDE:rating macro]

Standard Rating Panel

To display a rating panel, using the builder theme and a default title of "Rate Article", use the following:

{rate}

Before voting, the panel will look like this:

When you move your mouse over an emoticon, while voting, it will light up like this:

The small chart button () on the left allows the user to see the current rating (or "score") before casting their vote as shown below:

Clicking the green arrow () will take them back to the voting panel as shown earlier.

After casting their vote, the panel will change to show the new score, as shown below:

The blue curved arrow () allows them to retract their vote should they have made a mistake or change their mind at a later date.

You will also have noticed the delete button () - if you have sufficient privileges to edit the content in which the macro is used, you will see this button which allows you to clear down all votes. If you don't have sufficient privileges, that button will not appear.

Changing the title

The default "Rate Article" title is useful when rating pages or news items, but if you are rating a user, comments or something else you'll need a custom title:

{rate:title=User Rating}

The title will appear prior to voting:

And also after voting (or if you display the results prior to voting):

Because the same title is used for the voting panel and the results panel, you should make sure it works both as a question (eg. "User Rating?") and as a statement (eg. "User Rating:"). The "?" and ":" are automatically appended to the title by the macro.

Changing the theme

By default, the ratings panel uses the builder theme - emoticons are used for voting and coloured stars are used for results. You can however use the dynamic theme as follows:

{rate:theme=dynamic}

When voting, stars will be shown instead of emoticons:

As you move the mouse over the stars, while voting, each star up to and including the one the mouse is over will light up, for example:

After voting, the results will be shown as follows:

Display Types

By default the macro will show either a rating panel (where you can cast your vote) or the results panel (if you have already voted).

There are, however, a few additional display types...

The results display will only ever show the results, and will not allow voting:

{rate:display=results}

Resulting in:

There is also a percentage display that shows the current average value of the rating as a percentage:

{rate:display=percentage}

Resulting in:

73

This is useful if you want to put the value in to a table or within text explaining the rating, for example:

The current article rating is {rate:display=percentage}%.

Resulting in:

The current article rating is 73%.

Multiple Rating Panels

If you want to display multiple rating panels on one page (or any other type of content), you need to specify uniqe keys for each rating panel.

If you do not specify a unique key, or use the same key more than once, only the first rating panel with a specific key (or no key) will allow voting - all the rest will display in results mode.

Specify a key as follows:

{rate}
{rate:key=Readability|title=Readability Rating}
{rate:key=Usability|title=Usability Rating}

The first rating panel would use a default key (taken from the internal object database ID in case you are interested), while the following panels would use the specified keys.

Keys are case sensitive. If you change a key (even it's capitalisation, e.g. from "usability" to "Usability") then the old results will not be shown.

The on-screen result would be:

The rate keys are unique to the content in which they are being stored. That is to say, you can use the same rate key - of "Usability" for example - on multiple pages, etc.

Restrict voting to registered users

By default, the ratings panel allows anyone to vote but there may be cases where you only want registered users to vote, etc.

To do this, use the show-to macro and hide-from macro (you can also use the [USERGUIDE:show-if macro] or [USERGUIDE:hide-if macro] should you wish to restrict options based on where the ratings panel is displayed):

{show-to:groups=confluence-users}{rate}{show-to}
{hide-from:groups=confluence-users}{rate:display=results}{hide-from}

In the example above, anyone in the confluence-users user group (i.e. anyone with a user account) will see the macro in a form where they can vote. Anyone who is not in that user group (i.e. anonymous users) will merely see the results for the rating and will not be able to vote.