cross is now running Foswiki 2.1.3 Beta 1. Please open a task for any issues. Happy Holidays!
TIP RatingContrib is not installed on


Rating widget for forms

This is a rating widget that can support a "line of stars" style input field.


You can use the new rating type in form fields. The result of the rating is captured as an integer, and displayed as a line of stars. For example,

example stars.gif

Install the contrib. You can immediately use the rating type in your forms. Rating values are stored as integers.

To use it in a form, use the type rating, with the optional modified +small for small stars. The size field dictates how wide the rating is e.g. 5 means a 5 star range. The value field specifies the initial value. For example, the form definition:

| *Name*     | *Type*       | *Size* | *Values* |
| Supplier   | text         | 40     |          |
| Quality    | rating+small | 10     | 5        |
| Order Date | date         |        |          |
looks like this when it is edited:

edit example.gif

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See for more help.

Using the Contrib in a Plugin

A typical application of this widget is its use to capture a rating under the control of a plugin. It is straightforward to use in this role. The API to the contrib is:

Foswiki::Contrib::RatingContrib::renderRating($name, $size, $small, $value, $input_attrs) -> $html

  • $name is the name you want to give to the input element that will get the rating value
  • $size is the total width of the rating bar, typically 5 or 10
  • $small is a boolean; if true, use small (10px) stars in place of the default (25px) stars
  • $value is the current value of the rating. This may be a floating-point value, but should be in the range 0..$size
  • $input_attrs is a hash that contains additional attributes to be assigned to the input element used to capture the rating value. Typically the only attribute callers will need to use is onchange, which should be set to a callback that will be invoked when the value in the input is changed. If you pass undef for this parameter, then the line of stars will be "read only".
The contrib will automatically look after the CSS and Javascript it needs to load to work.

For example, let's say we want to generate a conventional form that contains a line of stars prompt. We want the value of the rating bar to be submitted along with everything else in the form.
my $html =
   CGI::form({action="some url", method=>"post"},
       Foswiki::Contrib::RatingContrib::renderRating('rating', 5, 0, 0, {})

Say instead that we want to generate an alert when a line of stars has its value changed:
$html = Foswiki::Contrib::RatingContrib::renderRating('rating', 5, 0, 0,
        {onchange=>'javascript: alert("Rated")'})
Of course, when you use the onchange event, you don't need a form. This model is good if you want (for example) to update values using a REST handler.

Contrib Info

Author(s): Crawford Currie
Copyright: © 2007 C-Dot Consultants
License: GPL (Gnu General Public License)
Version: 4083 (2009-06-10)
Change History:  
10 Jun 2009: Foswikitask:1258: port to Foswiki
27 Jun 2006: First version
Dependencies: None

Related Topics: Contribs, DeveloperDocumentationCategory, AdminDocumentationCategory, DefaultPreferences, SitePreferences

PackageForm edit

ExtensionClassification Interface and Visualisation
ExtensionType PluginPackage
Compatibility Tested with VotePlugin on 1.0.5., WARNING: RatingContrib is incompatible with latest JQueryPlugin which comes with a rating formfield of its own.
ImageUrl edit_example.gif
DemoUrl http://
SupportUrl RatingContrib
ModificationPolicy PleaseFeelFreeToModify
Topic attachments
I Attachment Action Size Date Who Comment
RatingContrib.md5md5 RatingContrib.md5 manage 162 bytes 10 Jun 2009 - 19:40 WillNorris  
RatingContrib.sha1sha1 RatingContrib.sha1 manage 186 bytes 10 Jun 2009 - 19:40 WillNorris  
RatingContrib.tgztgz RatingContrib.tgz manage 24 K 10 Jun 2009 - 19:40 WillNorris  
RatingContrib.zipzip manage 29 K 10 Jun 2009 - 19:39 WillNorris  
RatingContrib_installerEXT RatingContrib_installer manage 4 K 10 Jun 2009 - 19:40 WillNorris  
edit_example.gifgif edit_example.gif manage 7 K 10 Jun 2009 - 19:39 WillNorris  
example_stars.gifgif example_stars.gif manage 1 K 10 Jun 2009 - 19:39 WillNorris  
Topic revision: r5 - 02 May 2015, MichaelDaum - This page was cached on 25 Dec 2016 - 08:33.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License