{rate} Macro
| Use this macro with rate-search macro. |
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:
|
|
| display | default | The display mode to use, which can be:
|
This software is released under a BSD License
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]
Examples
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%.
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.
Hints and Tips
If you are using the Builder theme, you can add ratings panels to all pages on your site by including them in the footer.
To get statistical breakdowns and various charts depicting vote data, use the rate-table macro.
Frequently Asked Questions
None at present.


Comments (46)
Mar 09, 2006
Anonymous says:
This is a great macro at a great price, but when I switch between browsers, my r...This is a great macro at a great price, but when I switch between browsers, my ratings are not displayed on a page even though I am logged into Confluence. I would expect the ratings to be tied to my login in Confluence, not a cookie within the browser I've used.
Mar 09, 2006
Guy Fraser says:
Yup, the macro uses cookies so that it can remeber who's voted. We developed it...Yup, the macro uses cookies so that it can remeber who's voted. We developed it this way as there was a significant requirement for anonymous users to rate content, however the downsides are:
The benefits are:
So... In answer to your question, at present the macro will fail to recognise you if you switch browser or computer. I'll add an issue to our tracker later this evening so that people can comment and vote for various ideas.
May 22, 2006
Michal Szklanowski says:
Guy, one question: How to enable rating macro for all the pages within one spac...Guy,
one question: How to enable rating macro for all the pages within one space? That would be cool. Being forced to place macro for every single page inside a space is rather a tedious task, and macro can easily get deleted from the content.
Is it technically possible to somehow 'enable' macro globally? Maybe via modifying space templates?
Michal.
May 22, 2006
Guy Fraser says:
Hi Michal, It's not currently possible, however we'll test it with Builder 2.0 ...Hi Michal,
It's not currently possible, however we'll test it with Builder 2.0 which has a more flexible theme architecture.
Best Regards,
Guy
Jan 08, 2010
Matthew Shear says:
Add the macro to your layout, not your page.Add the macro to your layout, not your page.
Sep 28, 2006
Anonymous says:
i just installed this plugin thru the confluence repository client and it gives ...i just installed this plugin thru the confluence repository client and it gives me unknown macro when i type in
Nov 14, 2006
Anonymous says:
Hello, I'm currently using Builder 1.6 and wanted to add the rate macro to each...Hello,
I'm currently using Builder 1.6 and wanted to add the rate macro to each page using the theme. I've added it into the custom footer section and although the ratings appear on each page, they can't be used.
Is there any way that this can be achieved using Builder?
Nov 14, 2006
Guy Fraser says:
Unfortunately it's not possible to do that with Builder 1.6. However, we had lot...Unfortunately it's not possible to do that with Builder 1.6. However, we had lots of requests and made it possible in Builder 2.0 and above which includes enhancements to the panels that allow macros (such as the rate macro) to be used.
When using Builder 2.0 or above, it's worth using the following notation to ensure that the macro only appears in suitable places:
{builder-show:context=page,blogpost|mode=view}{rate}{builder-show}The [builder-show macro] is part of the Builder 2.0 and above theme and allows you to chose what types of content (and which display modes) to show content. In the example above, we only show the rating panel on the normal view or pages and blogposts (news articles).
Dec 01, 2006
Anonymous says:
I am trying to use the rate macro for multiple items in a table. The rating show...I am trying to use the rate macro for multiple items in a table. The rating shows up fine, but the only one that can be rated is te first one. Is there a way to get all of them to be rated. This is like a table with several columns of categories that need to be rated against 3 differect columns. So I have about 36 fields to populate with ratings. Only the first one gets rated.
Dec 01, 2006
Guy Fraser says:
You need to use the "key" parameter if you have more than one rating on a page.....You need to use the "key" parameter if you have more than one rating on a page...
The rating gets stored against the key (the default key is the database ID of the page) - if you have several rate macros on a page and none of them specified their own key, they'll all store against the default key and thus all show the same results, etc. By adding a different key to each of them they'll store their results separately.
Feb 08, 2007
Anonymous says:
Hi, there seems to be a small problem with the {rate} macro in IE7 when used wi...Hi,
there seems to be a small problem with the {rate} macro in IE7 when used with a {deck} macro.
When you move between cards the emoticons disappears and you can only view the small chart button.
It works fine in Firefox.
Not sure if this is a bug or if there's a way around this.
Thanks.
Feb 08, 2007
Anonymous says:
Just a small correction. The problem exists when the {rate} macro is used within...Just a small correction. The problem exists when the {rate} macro is used within the {deck} macro.
Mar 22, 2007
Anonymous says:
Is it possible to change the title= value in the dynamic theme?Is it possible to change the title= value in the dynamic theme?
Mar 23, 2007
Anonymous says:
I am currently working on a project where we need to use the Rate Macro. The ver...I am currently working on a project where we need to use the Rate Macro. The version of confluence being used is v2.2.10. The Macro seems to bomb out. Is there a solution for this in place or is there a Rate Macro that is out there for this version of confluence and up? Any help will be greatly appreciated.
Aug 03, 2007
Dhivya Manoharan says:
hi im working in rate macro in this once i voted i could not get the green arr...hi
im working in rate macro
in this once i voted i could not get the green arrow in the rate
but im getting the red undo.how can i vote for the second time
Aug 03, 2007
Guy Fraser says:
We're working on a new version of this plugin - should be released in a month or...We're working on a new version of this plugin - should be released in a month or so. Bug fixes and new features
Aug 06, 2007
Dhivya Manoharan says:
Hai Guy, But even though i have upgraded(version1.1.6) my plugin version still ...Hai Guy,
But even though i have upgraded(version1.1.6) my plugin version still i found the
issue.may i know what is the latest version.If the latest version is v1.1.6,
how can i overcome the issue.
With Regards,
Dhivya.M
Aug 07, 2007
Guy Fraser says:
The most recent version hasn't been released yet. It should be noted that the ma...The most recent version hasn't been released yet. It should be noted that the macro is designed to prevent (within reason) people from making multiple votes.
Dec 27, 2007
Thom W Gray says:
The documentation says that the delete button appears only if you have sufficien...The documentation says that the delete button appears only if you have sufficient privileges to edit the content in which the macro is used. But in our testing all users have the delete button. Is this a bug?
Mar 03, 2008
John Russell says:
Our users have recently noticed this as well and testing confirms it. We are us...Our users have recently noticed this as well and testing confirms it. We are using 1.1.7 of the Rate Plugin.
Mar 05, 2008
Jose Biton says:
I am getting the following error: Error formatting macro: rate: java.lang.Nul...I am getting the following error:
Error formatting macro: rate: java.lang.NullPointerException
When using:
{rate:title=Interest Level}or:
{rate}Any thoughts???
update: I just realized that the macro is not available for version 2.6. Is there an ETA for this macro in the latest confluence version?
Apr 21, 2008
David Bhunnoo says:
Hello, This macro is very useful however I do not want users to be able to del...Hello,
This macro is very useful however I do not want users to be able to delete the ratings.
That would mess up the results and some users might try this function just to play with it.
Any way to do that ?
Thanks.
Jun 19, 2008
Andrew Brister says:
Hi. I've set up a book club at my company. We're intent to use our Wiki as a way...Hi.
I've set up a book club at my company. We're intent to use our Wiki as a way to review books of interest to the employees. I've set up a simple page which I'll place the code below. It's a live template. The template works well except for one conflict. As soon as I put the
{rate} macroalong with the{table-data} macrointo the form I get a very strange error. "TypeError: ${"heratbeatDiv").style has no properties"This only happens when I have the rate macro present within the form. Otherwise this works well.
I need to have each page created under this template be rated. It defeats the purpose of having these pages be created this way if it wont work. Could you please suggest any work-arounds or solutions that may be present.
My company is currently using Confluence 2.7.2, Enterprise Wiki
h3. {color:maroon}{text-data:BookTitle|width=500px}Book Title{text-data}{color}{hidden-data}Insert the formal book title here{hidden-data} h4. {hidden-data:whenEmpty=BookSubTitle}{text-data:BookSubTitle|width=500px}Book Sub-Title{text-data}{hidden-data}{hidden-data}Insert the book sub title here{hidden-data} ---- h5.{text-data:Author}Author(s){text-data} {rate} {hidden-data}add your best .jpg of the book cover here.{attachment-data:BookCover|width=100px}{hidden-data} h2. Links {table-data:BookLinks|intitialRows=3} || Source || Link Type || Link || | {text-data:Source|width=100px}Source Name{text-data} | {list-data:LinkTypes} {list-option:Buy}Purchase{list-option} {list-option:Rev}Review{list-option} {list-option:Edit}Editorial{list-option} {list-option:Misc}Miscellaneous{list-option} {list-data} | {text-data:Link|width=300px}Place http:// link here...{text-data} | {table-data} h2. Reviews Review from Amazon.com... {text-data:AmazonRev|width=800px|height=100px}Place text from favorite amazon.com Review here{text-data} Review from Alibris.com... {text-data:AlibrisRev|width=800px|height=100px}Place text from favorite alibris.com Review here{text-data} Review from Half.Ebay.com... {text-data:HalfRev|width=800px|height=100px}Place text from favorite half.ebay.com Review here{text-data}Any feedback will be much appreciated. Thank you.
Jul 02, 2008
Ronny Roeller says:
How could I get an auto generated list of top rated articles? This would be a g...How could I get an auto generated list of top rated articles?
This would be a great feature on the homepage of a space.
Oct 08, 2008
Thom W Gray says:
We're currently trying the Advanced Search plugin to do this. Not sure if it is ...We're currently trying the Advanced Search plugin to do this. Not sure if it is going to work as advertised, but that's the approach we're trying. The syntax I'm trying is this:
{search-form:autoSubmit=true|hidden=true} {search-input:type=hidden|match=label|value=xyz} {search-submit:Search} {search-form} {search-results:showExcerpts=false|rateThreshold=0|maxResults=500|fields=rating,title,creation,author|sortField=rating|sortDir=desc}Oct 08, 2008
Steve says:
Will there be a new version of the Advanced Search plugin? Can you tell me when...Will there be a new version of the Advanced Search plugin?
Can you tell me when it will become available?
Nov 24, 2008
Rusty says:
we would like a rating mechanism for our site, but this macro doesn't seem to wo...we would like a rating mechanism for our site, but this macro doesn't seem to work with more current versions of confluence & builder (we are running C 2.8.1 and B 3.2.1).
when we install this via the plugin repository,
{rate}simply outputs a small group of 5 simple stars, and runs the results right alongside. is this a problem with the macro being outdated, or are we doing something wrong? none of the parameters seem to work...
Jan 07, 2010
Guillermo Chutrau says:
Did you ever find an answer to your question? I have the same problem. Thanks,Did you ever find an answer to your question? I have the same problem.
Thanks,
Feb 05
Kelly Holmes says:
This is what we're seeing too. Has anyone been able to figure out what's wrong?This is what we're seeing too. Has anyone been able to figure out what's wrong?
May 13, 2009
Kyle says:
This is a tough question: I am making an attempt to use Rate to assign weights t...This is a tough question: I am making an attempt to use Rate to assign weights to questions on a questionnaire. So Question 1, might be 3 starts (so I need to know how to get the value of this particular rate, keeping in mind there might be a few rates per page), once I have the value, stick it into meta-data calculate or put it in scaffold so I can divided it by a weight (say 0.30).
How do I extract the data? In the Confluence Plug-in admin panel, I see "Rate Data Extractor" and "Rate Macro Listener", but I don't see any docs on how to utilize them at all. I know for the Listeners, typically, I can call those in Reporting Plug-in, is that possible here?
(Confluence 2.10.1 , currently utilizing the 2.0.3 Rate plug-in I believe because it was slightly modifed to keep the use of the 'key' param that was not apart of the new plugin.
{rate-table}is not avail, but
{rate-search}is, if this matters). Please help as I am looking for a good solution to this business problem. Thanks in advance and major Kudos to the person who knows this.
Nov 05, 2009
Bruno Blaise says:
I have the same problem concerning rate-table, it is not available (confluence 2...I have the same problem concerning rate-table, it is not available (confluence 2.9.2, rate 2.0.3).
rate-search does not render correctly the url behind the content title (the base url has been correctly defined within the general information), but the url for the space is correct
Do you have a fix for this?
Jul 09, 2009
Steve says:
Is there any data stored on the database?Is there any data stored on the database?
Oct 28, 2009
Eliane Pohl says:
I would very much like to use this macro, but am having some trouble. I want to ...I would very much like to use this macro, but am having some trouble.
I want to have a long list of items, each with their own rating. Like this:
Option 1: Rate this
Option 2: rate this
Option 3: Rate this
The problem is that even when I give them separate keys, the results are all the same. Whenever I rate any option, the results for all options indicate the change.
Am I doing something wrong, or can the macro just not be used this way?
Jan 08, 2010
Matthew Shear says:
I have added the rate macro to my page layout so it shows up on every page. It a...I have added the rate macro to my page layout so it shows up on every page. It also says this macro is compatibhle with the charts plugin macros. How do I see the results of my ratings in Confluence?
Jan 08, 2010
Matthew Shear says:
FYI, I am using confluence v3.0.0_01 and the rate-search macro throws an error.FYI, I am using confluence v3.0.0_01 and the rate-search macro throws an error.
Feb 25
Betsy Walker says:
I'm interested in capitalizing on the Advanced Search macro's ability to show ra...I'm interested in capitalizing on the Advanced Search macro's ability to show ratings within the search results. Rather than having users rate a page by including the Rate macro on each page in a given space, we'd like to 'boost' items in the search results by programatically adding a rating to a page (or all pages within a given space). For instance, to highlight "best practices" or "official" pages in the search results.
Is this possible to add a page's rating programmatically?
Thanks!
Mar 03
Ray Bradley says:
Is there any reason that this macro wouldn't work correctly in the footer of the...Is there any reason that this macro wouldn't work correctly in the footer of the Documentation theme? When I put it into my footers I get this:
===========
only output the .vote td's if they CAN vote, but have NOT yet voted obviously change the URL's on the a tags to reflect the various choices only output the .wait td's if they CAN vote, but haven't already voted always output .results td's - the classes (on, half and off) depict the current avg. rating
Your Rating: Results: 0 rates
script type="text/javascript" language="JavaScript" src="/download/resources/com.adaptavist.confluence.rate:rate/resources/themes/v2/js/rating.js">
===========
When I put it into a page's body, it seems to work fine. Ideas?
Jun 12
Firat Vakiliev says:
I have the same problem into Navigation panel. I really need a solution. I do no...I have the same problem into Navigation panel. I really need a solution. I do not know what to do.
Author, please spill the beans!
PS: Bug report created. See here: #RATE-14
Jun 23
Pete Indelicato says:
Hi Guy, I really love this widget but I can't seem to get it to work. I am t...Hi Guy, I really love this widget but I can't seem to get it to work.
I am trying to get a few Rate macros on one page, Identical to example 5 above. So I put these three tags each in one table row on a single page. Here is the markup.
| h6. Data-driven Tree Widget \\ The data driven tree widget would allow ..... \\ {rate:key=Data-Driven-Tree|title=Data-driven Tree Widget} | \\ !tree example.png|thumbnail! \\ | | h6. Tabbed Panel The tabbed panel widget would... \\ {rate:key=Tabbed-Panel|title=Tabbed Panel Widget} | !tab example.png|thumbnail! | | h6. Slider Input The slider input would... {rate:key=Slider|title=Slider Widget} | !slider example.png! | | | |Yet, when a user votes for any one, their vote applies and show for all three.
What am I doing wrong?
Jun 23
Pete Indelicato says:
I could really use an answer (from anyone). Will that donation that I just made...I could really use an answer (from anyone). Will that donation that I just made to Adaptavist help?
Please?
BTW, I saw the note about the Key being numbers and letters only. But even when I copied this (from above) onto a page it didn't work.
{rate} {rate:key=Readability|title=Readability Rating} {rate:key=Usability|title=Usability Rating}It doesn't work here either! Same result. Oh boy...
Jun 24
Eliane Pohl says:
These macros seem to be incompatible with Confluence 3.2. None of the parameters...These macros seem to be incompatible with Confluence 3.2. None of the parameters have any effect on the Rate macro and the Rate-Search macro throws an error.
Has anyone gotten these to work with 3.2?
Jul 05
Edward Robertshaw says:
@Pete and Eilane. We currently have an offering of the rate macro which works on...@Pete and Eilane. We currently have an offering of the rate macro which works on 3.2 of confluence but we have not yet released the plugin.
To get hold of early releases of plugins like the rate macro and get excellent support on all plugins from the highly skilled Adaptavist team, you need to consider being part of our support service. We no longer accept donations on macros (we have refunded Pete's donation).
Jun 25
Eliane Pohl says:
While I take up the battle for budget approval for your support agreement, can y...While I take up the battle for budget approval for your support agreement, can you tell us when the plugin will be generally available?
Jul 27
Pete Indelicato says:
Hello again, I have some old Rate data that I cannot seem to clear: 1) There i...Hello again,
I have some old Rate data that I cannot seem to clear:
1) There is no "delete" or "clear" button next to the votes, ie no red X as shown above.l
2) When I delete the page that has the rate function, the rate-search macro is still picking it up.
Can you tell me how to remove a "rate" object completely? I.e. not just clear votes...
Thanks,
Pete
Jul 27
Pete Indelicato says:
Scratch that, after a while #2 appears to work.Scratch that, after a while #2 appears to work.
Jul 27
Pete Indelicato says:
The drama continues. Now, in the Rate-search output, I have lines (Rates) that ...The drama continues.
Now, in the Rate-search output, I have lines (Rates) that don't really exist. For example, I have lines pointing to a Space (and a Page therein) that does not have a Rate macro anywhere in it.
I even went as far as deleting one of those spaces (the Demo space thats installed with Confluence), and the Rates search results that were mistakenly pointed to the Demo space were replaced by other false search results pointing to yet another space that has no Rate objects in it.
Frustrated, please help.