QuackFuzed [ Ramblings of a Con..ColdFuzed Mind ]

cfUniForm: "Rate Me"

Posted on February 27, 2010 at 7:56 PM in ColdFusion, Uni-Form Tag Library

jQuery's star rating plugin makes it simple to add a "Rate Me" interface to your application. Combine it with cfUniForm v4.0, and now it's ridiculously simple to add a star rating field (or ten) to any form.

The Defaults

Simple. Ridiculously simple.

1. <uform:field type="rating" label="Rate Me" name="RateMe" />

This one simple line results in a field named "RateMe" being added to your form, with selectable values of 1, 2, 3, 4, and 5. And it looks like this:

The Attributes

Along with a new "type" of "rating", v4.0 introduced five new (optional) attributes on the field tag:

1. starCount
2. starValues
3. starTitles
4. showStarTips
5. starSplit

You can mix and match these attributes to customize your rating field. Let's look at what each one does (and its default value).

starCount is pretty self-explanatory. It determines the number of stars that will show. The default is 5.

starValues provides a way for you to provide cfUniForm with the value attribute of each star. By default, the values will be 1-#starCount#. So, using the default 'starCount' of 5, you end up with the following:

1. <input type="radio" name="RateMe" value="1" />
2. <input type="radio" name="RateMe" value="2" />
3. <input type="radio" name="RateMe" value="3" />
4. <input type="radio" name="RateMe" value="4" />
5. <input type="radio" name="RateMe" value="5" />

The 'starValues' attribute accepts either a comma-delimited list OR an array.

starTitles allows you to provide cfUniForm with the titles that you want displayed in the 'title' attribute of each star input. It defaults to #starValues#.

The 'starTitles' attribute accepts either a comma-delimited list OR an array.

showStarTips accepts either a true or false value, and it tells cfUniForm whether or not to display a "tool tip" as the user hovers over a star. If set to true, the 'title' attribute of the star will be displayed in a <span> next to the stars. It defaults to false.

starSplit allows you to, well, split the stars. So, if you want half-star ratings, you would set this attribute to 2. The default is 0 (whole stars - no split).

In Action

You can see the combination of 'starTitles', 'showStarTips', and 'starSplit' in action at the bottom of the "Kitchen Sink" demo form, right underneath the CAPTCHA image (CTRL+F "Rate the image above").

Read-Only & "Selected" Star

You can also tell cfUniForm to make a rating field read-only. Say you want to show the "Average Rating" of something. Since you're showing a calculated average, you do not want users to be able to select (change) the rating. In this situation you will want to add the 'isDisabled' and 'value' attributes.

1. <uform:field label="Average Rating"
2. name="avgRating"
3. type="rating"
4. isDisabled="true"
5. value="3" />

And it looks like this when rendered:

Thanks!

Thank you to Mary Jo Sminkey for the suggestion and for submitting a basic code example for the star ratings plugin. For more information, be sure to visit the plugin documentation, and, of course, the cfUniForm documentation.

Comments

(Comment Moderation is enabled. Your comment will not appear until approved.)

On 3/7/10 at 6:38 PM, Mary Jo Sminkey said:

Really love what you did with this! This was what I hoped for when I suggested it, it's such a nice add-on, it's awesome you were able to take my basic implementation and go the extra mile with it.

On 12/9/10 at 4:20 PM, erik said:

I would like to have readonly option not by disabling the form elements because I will not be able to pass the value to the next screen . How can I make it readonly

On 12/9/10 at 5:17 PM, Matt Quackenbush said:

@ Erik - If/when I need the value of a disabled field to be passed along with the form, I just use a hidden field for that value. You can add a little bit of jQuery to update its value if it is set by something else. HTH

On 12/9/10 at 5:40 PM, erik said:

Can you give me an example. And is it going to be an option in the future

On 12/9/10 at 5:44 PM, Matt Quackenbush said:

An example of ................... ? It's just a hidden field that you add somewhere within the fieldset.

[Add Comment]