Download

Get Loom

Rating

The rating tag component is a visual component that renders plain HTML content that is further enhanced using javascript to display the typical rating stars:

Example of rating tag in use

The component may be used to introduce data in a form or to display read-only data.

Rating inside a form

To use inputRating inside a form, just use it as any other field-bound component:

The action class:

public class VoteAction extends AbstractActionImpl {

  /** the vote casted by the user */
  @NumberValidation(max="5", on="vote")
  private Integer vote;

  /** the total sum of votes */
  private BigDecimal total;

  /** the number of casted votes */
  private int numVotes;

}

<l:form action="Vote" event="vote">
  <addons:inputRating id="vote" name="vote" total="${action.total}" numVotes="${action.numVotes}"/>
</form>

This example will extract the current total amount and number of votes (to calculate the average value) and store the user-submitted vote in VoteAction.vote.

Generated HTML

InputRating will render an enhanced <l:select> tag. The list of possible values can be injected using the options attribute, but the usual way is to just inject a max value and let it calculate the options automatically. It set using NumberValidation, the scale (number of decimals) applied when calculating the average will be the same of the field, default 1.

If the field is set to translate the labels, the messages.properties file should contain the corresponding entries:

child.results.0=none
child.results.1=lame
child.results.2=poor
child.results.3=average
child.results.4=good
child.results.5=great

With this JSP content:

<addons:rating name="child.results" />

Will generate the following HTML snippet:

<label class="rating required">
<span>Child results:</span>
<select name="child.results" class="rating fouc">
	<option value="0">none</option>
	<option value="1">lame</option>
	<option value="2">poor</option>
	<option value="3">average</option>
	<option value="4">good</option>
	<option value="5">great</option>
</select>
<span class="message">5 out of 1 votes</span>
</label>

Plain HTML generated

To add the javascript component, refer to the Rating javascript component page.

Read-only rating

When the name property is not set, inputRating will only display the current rating value and the user cannot cast a new vote. This is different of setting disabled to true, as it will not render a select field:

<div class="fouc rating" data-numVotes="2" data-average="3.0" max="5" id="rating3"> </div>
<span class="message">3 out of 2 votes</span>

After adding javascript, this will render the same as a normal, disabled rating component.

Adding javascript

To replace a select field with the typical stars, add the following to the end of your JSP page:

<l:css resource="rating"/>
<l:script resource="rating"/>

<script>
new loom.ui.Rating($('vote'), { voteOnce: false });
</script>

The component can be enhanced with optional arguments, such as set submitOnVote to true to automatically submit the form after voting.

When moving the mouse over a rating component, the message will display the label of the corresponding selected option.