RatingContrib < TWiki

---+!! !RatingContrib
<!--
   Contributions to this extension are appreciated. Please update the documentation page at
   http://twiki.org/cgi-bin/view/Plugins/RatingContrib or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/RatingContribDev.
   If you are a TWiki contributor please update the extension in the SVN repository.

One line description, required for extensions repository catalog:
   * Set SHORTDESCRIPTION = Rating widget for TWiki forms using "line of stars" style input field
-->
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%

---++ Introduction

This module adds a line-of-stars rating bar to TWiki forms and TWiki applications.

---++ Using the color picker in !TWikiForms

This package adds a =rating= type to %SYSTEMWEB%.TWikiForms. The result of the rating is captured as an integer, and displayed as a line of stars. For example,

<img src="%ATTACHURLPATH%/example_stars.gif" />

To use it in a TWiki form, use the type =rating=, with the optional modified =+small= for small stars:

| *Type* | *Description* | *Size* | *Value* |
| =rating= | <img src='%PUBURLPATH%/%WEB%/RatingContrib/starrating.png' alt='starrating' width='150' height='34' align='right' /> Line-of-stars rating bar. %IF{ "'%BASETOPIC%'='TWikiForms'" then="[[RatingContrib][See details]]." }% | Number of stars for rating | Initial value |
| =rating+small= | <img src='%PUBURLPATH%/%WEB%/RatingContrib/starrating-small.png' alt='starrating-small' width='150' height='30' align='right' /> Like =rating=, but with small stars. %IF{ "'%BASETOPIC%'='TWikiForms'" then="[[RatingContrib][See details]]." }% | | |

Example form definition:

<verbatim>
| *Name*     | *Type*       | *Size* | *Values* |
| Supplier   | text         | 40     |          |
| Quality    | rating+small | 10     | 5        |
| Order Date | date         |        |          |
</verbatim>
A topic with this form looks like this when in edit mode:

<img src="%ATTACHURLPATH%/edit_example.gif" />

---++ 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, such as the the TWiki:Plugins.VotePlugin. 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.
<verbatim>
my $html =
   CGI::form({action="some url", method=>"post"},
       TWiki::Contrib::RatingContrib::renderRating('rating', 5, 0, 0, {})
      .CGI::submit("OK"));
</verbatim>

Say instead that we want to generate an alert when a line of stars has its value changed:
<verbatim>
$html = TWiki::Contrib::RatingContrib::renderRating('rating', 5, 0, 0,
        {onchange=>'javascript: alert("Rated")'})
</verbatim>
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.

---++ Installation Instructions

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the extension home on twiki.org (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory.
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies (if any).


---++ Contrib Info

|  Contrib Author(s): | Crawford Currie http://c-dot.co.uk |
|  Copyright: | &copy; 2007 C-Dot Consultants; %BR% &copy; 2007-2015 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Contrib Version: | 2015-01-07 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2015-01-07: | TWikibug:Item7568: Code refactor |
|  2013-07-25: | TWikibug:Item7151: Fix warning if value is empty -- TWiki:Main.PeterThoeny |
|  2010-12-03: | TWikibug:Item6609: Add screenshots -- TWiki:Main.PeterThoeny |
|  2010-11-27: | TWikibug:Item6609: In %SYSTEMWEB%.TWikiForms type table, automatically list the =rating= form field type defined in this contrib -- TWiki:Main.PeterThoeny |
|  2010-07-27: | TWikibug:Item6530 - doc fixes |
|  2006-07-27: | 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:__ %SYSTEMWEB%.TWikiContribs, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

Attachments

Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
gif	edit_example.gif	r1	manage	7.6 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	example_stars.gif	r1	manage	1.3 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	ie_pick_star.gif	r1	manage	0.4 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	ie_pick_star_small.gif	r1	manage	0.2 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	ie_star.gif	r1	manage	2.0 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	ie_star_small.gif	r1	manage	0.4 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	leftbar.gif	r1	manage	0.2 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	mainbar.gif	r1	manage	0.1 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	pick_star.gif	r1	manage	0.5 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	pick_star_small.gif	r1	manage	0.3 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
css	rating.css	r1	manage	1.6 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
js	rating.js	r1	manage	0.3 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	rightbar.gif	r1	manage	0.2 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	star.gif	r1	manage	2.6 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
gif	star_small.gif	r1	manage	0.6 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
png	starrating-small.png	r1	manage	4.5 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
png	starrating.png	r1	manage	5.7 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script
svg	stars.svg	r1	manage	12.4 K	2015-01-08 - 00:33	TWikiAdminUser	Saved by install script

This topic: TWiki > RatingContrib
Topic revision: r2 - 2020-07-17 - TWikiAdminUser

Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.RatingContrib.