Using Spry Widgets: Rating Widget Overview

About Spry Widgets

A Spry widget is a page element containing built-in behaviors and functions that provide a richer user experience by enabling user interaction. These behaviors can include functionality that lets users show or hide content on the page, change the appearance (such as color of the input) in the page, interact with menu items, and much more.

The Spry framework supports a set of re-usable widgets, written in standard HTML, CSS, and JavaScript. You can easily insert these widgets — the code is HTML and JavaScript at its simplest — and then style the widget according to your liking.

Each widget in the Spry framework is associated with unique CSS and JavaScript files. The CSS file contains everything necessary for styling the widget, and the JavaScript file gives the widget its functionality. You must link both of these files to the page on which you want the widget to function and appear styled. For more information, see the appropriate sections about linking associated files in the topics that follow.

The CSS and JavaScript files associated with a given widget are named after the widget, so it’s easy for you to know which files correspond to which widgets. (For example, the files associated with the Rating widget are called SpryRating.css and SpryRating.js).

• Anatomy of the Rating widget
• Rating widget degrades gracefully when Java Script is off
• CSS for the Rating widget
• Building a Rating widget
• Adding Options to the Rating widget
• Constructor options list

See the Rating widget reference file and sample.

Anatomy of the Rating widget

The Rating Widget can be used to display a rating of something and also to submit a new rating for the object.

This widget can be used in two different cases: as a static rating widget that will not allow the users to submit their own rating or as a dynamic rating widget where the user can add their own rating.

All widgets have a constructor script that follows the widget markup. This constructor has one required value - the container element ID, and a set of optional values.

<span id="spryrating1" class="ratingContainer">
	<span class="ratingButton"></span>
	<span class="ratingButton"></span>
	<span class="ratingButton"></span>
	<span class="ratingButton"></span>
	<span class="ratingButton"></span>
    <!--Add a custom message-->
	<span class="ratingRatedMsg">Thanks for voting !</span>
</span>



<script type="text/javascript">
	var spryrating1 = new Spry.Widget.Rating("spryrating1");
</script>

Each widget element has a set of CSS classes attached in order to control the widget appearance and some behavior. The widget behavior is set from js file using the classes defined in the css file.

In the above code sample the first span tag is the container tag containing other five span tags each which represent the placeholders for the rating images. These placeholders are populated via css with star images which comprise the heart of the rating widget. By calling the "ratingButton" class on each span tag a background image is set. The number of the span tags that have this class attached defines the maximum number of the rating widget stars.

You can change the look of the Rating widget by editing the appropriate classes in the SpryRating.css file. If you want to remove a given behavior, you can delete the CSS rules that correspond to that behavior. For example if you want to use other images in place of the default stars, you can simply set another background-image in the corresponding CSS class.

The span container tag must have an ID attached.

You can add custom messages to a Rating widget by creating a span tag (or any other type of tag) to hold the text of the error message. Then, by applying a CSS class to it, you can hide or show the message, depending on the widget state.

In the script tags, the new JavaScript operator initializes the Rating widget object, and transforms the span content with the ID of 'spryrating1' from static HTML code into an interactive page element.

You can use any HTML tag as container and placeholders for stars, the only thing that is important is to be followed the widget structure: a main container that has inside it the placeholders for rating widget.

Container SPAN
	Star placeholder SPAN
	Error message SPAN

You can, however, use almost any container tag to create the widget:

Container DIV
	Star placeholder DIV
	Error Message P

Rating widget degrades gracefully when Java Script is off

The Rating widget supports graceful degradation when Java Script is off.

To have the Rating widget work when Java Script is off, you have to add a few more HTML tags. The HTML elements needed for graceful degradation are by default hidden from CSS when Java Script is enabled.

In the main widget container, add a text input element which will be the replacement code for the Rating widget stars. To be able to send the rating to the server, you should have a form element that contains the text input element and a submit button to send the data.

The HMTL mark-up for the Rating widget when the page degrades gracefully should look as in the below code sample:

<form method="get" name="form1" action="SpryRating.php">


	<span id="spryrating1" class="ratingContainer">

             <span class="ratingButton"></span>
             <span class="ratingButton"></span>
             <span class="ratingButton"></span>
             <span class="ratingButton"></span>
             <span class="ratingButton"></span>
             
             <input type="text" name="elementName" value="3.5" />
             <input type="submit" value="Vote"/>
             
	</span>

</form>
	

Depending on requirements,you can use text input, select input or radio input elements for graceful degradation.

CSS for the Rating widget

The SpryRating.css file contains the rules that style the Rating widget. You can edit these rules to style the widget look and feel. The names of the rules in the CSS file correspond directly to the names of the classes specified in the Rating widget’s HTML code.

The following is the CSS code for the SpryRating.css file.

/* top-level container for rating widget */

.ratingContainer{
	float: left;	
}
/* star */
.ratingButton{
 	 background-repeat: no-repeat;
	 background-position: center center;
	 display: none;
}  
.ratingInitialState .ratingButton,
.ratingReadOnlyState .ratingButton,
.ratingRatedState .ratingButton
{
	display: block;
	width: 20px;
	height: 20px;
	float: left;
}
/* Hide the input fields that are used for graceful degradation when JavaScript is enabled. */
.ratingInitialState input,
.ratingReadOnlyState input,
.ratingRatedState input
{
	display: none;
}
.ratingFull{
	 background-image: url('SpryStarFull.png');
} 
.ratingEmpty{
	 background-image: url('SpryStarEmpty.png');
} 
.ratingHalf{
	 background-image: url('SpryStarHalf.png');
}
.ratingHover{
	 background-image: url('SpryStarHover.png');
	 cursor: pointer;
}
.ratingReadOnlyState .ratingFull{
 	background-image: url('SpryStarFullRO.png');
}
.ratingReadOnlyState .ratingHalf{
 	background-image: url('SpryStarHalfRO.png');
}
.ratingReadOnlyErrMsg, .ratingRatedMsg{	
	display: none;
}
.ratingReadOnlyErrState .ratingReadOnlyErrMsg{
	display: inline;
	color: #CC3333;
	border: 1px solid #CC3333;	
}
.ratingRatedState .ratingRatedMsg{
	display: inline;
	color: green;	
}
/* Customize the appearance of the rating counter */
.ratingCounter{
	color: green;
}

Building a Rating Widget

1. In your page, attach the Rating javascript and css files: SpryRating.js and SpryRating.css. Recall that javascript is case sensitive.

   <script language="JavaScript" type="text/javascript" src="includes/SpryRating.js"></script>
   <link href="includes/SpryRating.css" rel="stylesheet" type="text/css" />
   

2. To the document body, add a container tag <SPAN> and give it a unique ID. Add to this container also the "ratingContainer" class to prevent possible layout issues. This class floats the container itself.

   <span id="spryrating1" class="ratingContainer"></span>

3. Add the placeholders for widget stars and attach on each one the "ratingButton" class. In this example we add five span tags to have a rating widget with five stars.
   

   <span id="spryrating1" class="ratingContainer">
   
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   </span>

4. Now that the markup is complete, we will add the constructor script. Below the markup, add a script tag and write the constructor within. The values are case sensitive.
   

   <span id="spryrating1" class="ratingContainer">
   
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   	<span class="ratingButton"></span>
   </span>
   
   
   <script type="text/javascript">
   	var rating = new Spry.Widget.Rating("spryrating1");
   </script>
   

5. Save the page. The complete code looks as follows:
   

   <head>
   ...
   	<script language="JavaScript" type="text/javascript" src="includes/SpryRating.js"></script>
   	<link href="includes/SpryRating.css" rel="stylesheet" type="text/css" />
   ...
   </head>
   
   <body>
   	<span id="spryrating1" class="ratingContainer">
   
   		<span class="ratingButton"></span>
   		<span class="ratingButton"></span>
   		<span class="ratingButton"></span>
   		<span class="ratingButton"></span>
   		<span class="ratingButton"></span>
   	</span>
   
   
   <script type="text/javascript">
   	var rating = new Spry.Widget.Rating("spryrating1");
   </script>
   
   </body>

As it is described above, the Rating widget that we just created is a dynamic widget which allows you to give your rate. You can add more behaviors to this widget depending on your needs.

The next section presents the options you can add to make this Rating widget more powerful.

Adding Options to the Rating widget

If you want to add some optional functionality to this widget, add the options that fit your requests to the widget constructor. Options are contained within {}.

make the rating widget read only

By adding the "readOnly" option set on true in the widget constructor, the user can't rate, the Rating widget behaves as an disabled element having only an informative role.

<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {readOnly:true});
</script>

set an initial value for rating widget

You can specify a static initial value for the Rating widget by adding the "ratingValue" option in the widget constructor.

<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {ratingValue:2.5});
</script>

The code above will instantiate a new Rating widget having the initial value 2.5. This value will change the default appearance of the Rating widget, showing two and a half stars colored in yellow.

The initial value for the Rating widget can be also dynamic, retrieved form server and not only static, hard-coded in the widget constructor. To extract the initial value for the Rating widget from a server, you have to add in page an input element that will store the value and use the "ratingValueElement" option for passing the input element id.

The HTML element that will provide the data from server can be any input element: text input, hidden input, select input and has to be inside the widget container. By default, we hide this input element from CSS. It's mandatory to add an ID attribute to this HTML element because the "ratingValueElement" option will take as parameter this ID value.

The complete code when we extract the initial data from a input hidden element, will look like this:

<body>
	<span id="spryrating1" class="ratingContainer">

		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
       
		<input type="hidden" id="ratingValue" name="dynamic_rate" value="2"/>

	</span>


<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {ratingValueElement:"ratingValue"});
</script>

</body>

send the rated value to the server

The Rating widget has a mechanism to send the user selected rating value to the server. You can choose the method to send data: GET or POST. The default method used to send the data is GET. If you want to send the data via POST you should add "postData" option in the widget constructor.

When sending via GET method you only have to provide the "saveURL" option which takes the real URL for saving data. The widget constructor will look like:

<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {saveURL:'SpryRating.php?id=spryrating5&val=@@rw_Rating@@'});
</script>

If you need to send the data via POST, you should add in the widget constructor the "postData" option- a string containing the url encode and the "saveURL" - url for saving data. The "postData" string can contain the placeholder for the rated value, in this format @@ratingValue@@. It is always send in conjunction with saveURL.
The widget constructor in this case:

<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {postData: 'id=spryrating2&val=@@ratingValue@@', saveURL:'SpryRating.php});
</script>

Update the Ratings Value Dynamically

Using the "afterRating" option, you can specify the new value of the widget: the current voted value, or the value returned from the server after rating. You have to add an input element inside the widget container which will store the updated value. The id of the input element will be provided as value for "ratingValueElement" option. It may contain the placeholder for the rated value, in the form @@ratingValue@@. It is always send in conjunction with saveURL.The complete code for a real case when you want to display an average value coming from the server looks like this:

<body>
	<span id="spryrating1" class="ratingContainer">

		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<span class="ratingButton"></span>
		<input type="text" id="ratingValue" name="dynamic_rate" value="2"/>

	</span>


<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {ratingValueElement:"ratingValue", afterRating:'serverValue', saveURL:'SpryRating.php?id=spryrating5&val=@@rw_Rating@@'});
</script>

</body>

In case you only want to display the voted value, is need to specify in the widget constructor only the option "afterRating" with a value of: "currentValue".

keyboard navigation

Making widgets accessible for keyboard navigation is an important part of every widget. Keyboard navigation lets the user control the widget with arrow keys and custom keys. The keyboard navigation is enabled by default for the Rating widget, but it can be disabled by passing the "enableKeyboardNavigation" option on false.

If you want to not use the default keys for navigation/voting, you can use specify which keys you want using the following options: "moveNextKeyCode", "movePreviousKeyCode", "doRatingKeyCode".

<script type="text/javascript">
	var rate = new Spry.Widget.Rating("spryrating1", {moveNextKeyCode:34 /* PgUp key */, movePrevKeyCode: 33 /* PgDn key */, doRatingKeyCode:32 /*Space key*/});
</script>

Constructor options list

Copyright © 2008. Adobe Systems Incorporated. All rights reserved.