RatingContrib

<--
One line description, required for extensions repository catalog. 

 Set SHORTDESCRIPTION = 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

In TWiki 4.2 and later

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         |        |          |

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.2 or later, you can install from the configure interface (Go to Plugins->Find More Extensions)
  • See the installation supplement on TWiki.org for more information.
• If you have any problems, then you can still install manually from the command-line:
  1. Download one of the .zip or .tgz archives
  2. Unpack the archive in the root directory of your TWiki installation.
  3. Run the installer script ( perl <module>_installer )
  4. Run configure and enable the module, if it is a plugin.
  5. Repeat for any missing dependencies.
• If you are still having problems, then instead of running the installer script:
  1. Make sure that the file permissions allow the webserver user to access all files.
  2. 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)
  3. Manually edit LocalSite.cfg to set any configuration variables.

Using the Contrib in a Plugin

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".

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")'})

Contrib Info

<-- versions below in reverse order -->

Related Topics: TWikiContribs, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

<-- Do not attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the feedback topic on twiki.org instead. -->