RatingContrib

Rating widget for TWiki forms

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

Usage

In TWiki < 4.2

The rating widget can be used with the VotePlugin. The widget is like the JSCalendarContrib in that once it is installed, it can be used with any plugin that requires a line - of - stars rating bar.

In TWiki 4.2 and later

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,

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

To use it in a TWiki 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:

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 where TWiki is running.

Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.

• If you have TWiki 4.1 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • The webserver user has to have permission to write to all areas of your installation for this to work.
• If you have a permanent connection to the internet, you are recommended to use the automatic installer script
  • Just download the RatingContrib_installer perl script and run it.
• Notes:
  • The installer script will:
    • Automatically resolve dependencies,
    • Copy files into the right places in your local install (even if you have renamed data directories),
    • check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
    • If the $TWIKI_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
    • (Developers only: the script will look for twikiplugins/RatingContrib/RatingContrib.tgz before downloading from TWiki.org)
  • If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
    • Point the environment variable $TWIKI_PACKAGES to this directory, and the installer script will look there first for required TWiki packages.
      • $TWIKI_PACKAGES is actually a path; you can list several directories separated by :
    • If you are behind a firewall that blocks access to CPAN, you can pre-install the required CPAN libraries, as described at http://twiki.org/cgi-bin/view/TWiki/HowToInstallCpanModules
• If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
  1. Download and unpack one of the .zip or .tgz archives to a temporary directory.
  2. Manually copy the contents across to the relevant places in your TWiki installation.
  3. Check in any installed files that have existing ,v files in your existing install (take care not to lock the files when you check in)
  4. Manually edit LocalSite.cfg to set any configuration variables.
  5. Run configure and enable the module, if it is a plugin.
  6. Repeat from step 1 for any missing dependencies.

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:

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

where

• $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"},
       TWiki::Contrib::RatingContrib::renderRating('rating', 5, 0, 0, {})
      .CGI::submit("OK"));

Say instead that we want to generate an alert when a line of stars has its value changed:

$html = TWiki::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

Contrib Author(s):	Crawford Currie http://c-dot.co.uk
Copyright:	© 2007 C-Dot Consultants
License:	GPL (Gnu General Public License)
Contrib Version:	14295 (27 Jun 2007)
Change History:
27 Jun 2006:	First version
Dependencies:	None
Contrib Home:	http://twiki.org/cgi-bin/view/Plugins/RatingContrib
Feedback:	http://twiki.org/cgi-bin/view/Plugins/RatingContribDev
Appraisal:	http://twiki.org/cgi-bin/view/Plugins/RatingContribAppraisal

Related Topics: TWikiContribs, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences