Module org.apache.wicket.extensions
Package org.apache.wicket.extensions.rating

Class RatingPanel

java.lang.Object
org.apache.wicket.Component
org.apache.wicket.MarkupContainer
org.apache.wicket.markup.html.WebMarkupContainer
org.apache.wicket.markup.html.panel.Panel
org.apache.wicket.extensions.rating.RatingPanel
All Implemented Interfaces:
Serializable, Iterable<Component>, IEventSink, IEventSource, IFeedbackContributor, IConverterLocator, IMetadataContext<Serializable,Component>, IQueueRegion, IHeaderContributor, IRequestableComponent, IHierarchical<Component>, IClusterable
public abstract class RatingPanel extends Panel
Rating component that generates a number of stars where a user can click on to rate something. Subclasses should implement onRated(int, Optional) to provide the calculation of the rating, and onIsStarActive(int) to indicate whether to render an active star or an inactive star.

Active stars are the stars that show the rating, inactive stars are the left overs. E.G. a rating of 3.4 on a scale of 5 stars will render 3 active stars, and 2 inactive stars (provided that the onIsStarActive(int) returns true for each of the first three stars).

Use this component in the following way: 

 add(new RatingPanel("rating", new PropertyModel(rating, "rating"), 5)
 {
        protected boolean onIsStarActive(int star)
        {
                return rating.isActive(star);
        }
 
        protected void onRated(int rating, AjaxRequestTarget target)
        {
                rating1.addRating(rating);
        }
 });
The user of this component is responsible for creating a model that supplies a Double (or Float) value for the rating message, however the rating panel doesn't necessarily have to contain a float or number rating value.

Though not obligatory, you could also supply a value for the number of votes cast, which allows the component to render a more complete message in the rating label.

Customizing the rating value and label

To customize the rating value, one should override the newRatingLabel(String, IModel, IModel) method and create another label instead, based on the provided models. If you do so, and use another system of rating than returning a Float or Double, then you should also customize the rating resource bundle to reflect your message. The default resource bundle assumes a numeric value for the rating.

Resource bundle

This component uses two types of messages: rating.simple and rating.complete. The first message is used when no model is given for the number of cast votes. The complete message shows the text 'Rating xx.yy from zz votes'. 
       rating.simple=Rated {0,number,#.#}
       rating.complete=Rated {0,number,#.#} from {1,number,#} votes

Customizing the star images

To customize the images shown, override the getActiveStarUrl(int) and getInactiveStarUrl(int) methods. Using the iteration parameter it is possible to use a different image for each star, creating a fade effect or something similar.
Author:
Martijn Dashorst
See Also:

  • Field Details

  • Constructor Details

    • RatingPanel

      public RatingPanel(String id)
      Constructs a rating component with 5 stars, using a compound property model as its model to retrieve the rating.
      Parameters:
      id - the component id.

    • RatingPanel

      public RatingPanel(String id, IModel<? extends Number> rating)
      Constructs a rating component with 5 stars, using the rating for retrieving the rating.
      Parameters:
      id - the component id
      rating - the model to get the rating

    • RatingPanel

      public RatingPanel(String id, int nrOfStars)
      Constructs a rating component with nrOfStars stars, using a compound property model as its model to retrieve the rating.
      Parameters:
      id - the component id
      nrOfStars - the number of stars to display

    • RatingPanel

      public RatingPanel(String id, IModel<? extends Number> rating, int nrOfStars, boolean addDefaultCssStyle)
      Constructs a rating component with nrOfStars stars, using the rating for retrieving the rating.
      Parameters:
      id - the component id
      rating - the model to get the rating
      nrOfStars - the number of stars to display
      addDefaultCssStyle - should this component render its own default CSS style?

    • RatingPanel

      public RatingPanel(String id, IModel<? extends Number> rating, int nrOfStars, IModel<Integer> nrOfVotes, boolean addDefaultCssStyle)
      Constructs a rating panel with nrOfStars stars, where the rating model is used to retrieve the rating, the nrOfVotes model to retrieve the number of casted votes. This panel doens't keep track of whether the user has already voted.
      Parameters:
      id - the component id
      rating - the model to get the rating
      nrOfStars - the number of stars to display
      nrOfVotes - the number of cast votes
      addDefaultCssStyle - should this component render its own default CSS style?

    • RatingPanel

      public RatingPanel(String id, IModel<? extends Number> rating, IModel<Integer> nrOfStars, IModel<Integer> nrOfVotes, IModel<Boolean> hasVoted, boolean addDefaultCssStyle)
      Constructs a rating panel with nrOfStars stars, where the rating model is used to retrieve the rating, the nrOfVotes model used to retrieve the number of votes cast and the hasVoted model to retrieve whether the user already had cast a vote.
      Parameters:
      id - the component id.
      rating - the (calculated) rating, i.e. 3.4
      nrOfStars - the number of stars to display
      nrOfVotes - the number of cast votes
      hasVoted - has the user already voted?
      addDefaultCssStyle - should this component render its own default CSS style?

  • Method Details

    • renderHead

      public void renderHead(IHeaderResponse response)
      Description copied from class: Component
      Render to the web response whatever the component wants to contribute to the head section.
      Specified by:
      renderHead in interface IHeaderContributor
      Overrides:
      renderHead in class Component
      Parameters:
      response - Response object

    • newRatingStarBar

      protected Component newRatingStarBar(String id, IModel<Integer> nrOfStars)
      Creates a new bar filled with stars to click on.
      Parameters:
      id - the bar id
      nrOfStars - the number of stars to generate
      Returns:
      the bar with rating stars

    • newRatingLabel

      protected Component newRatingLabel(String id, IModel<? extends Number> rating, IModel<Integer> nrOfVotes)
      Creates a new rating label, showing a message like 'Rated 5.4 from 53 votes'.
      Parameters:
      id - the id of the label
      rating - the model containing the rating
      nrOfVotes - the model containing the number of votes (may be null)
      Returns:
      the label component showing the message.

    • getActiveStarUrl

      protected String getActiveStarUrl(int iteration)
      Returns the url pointing to the image of active stars, is used to set the URL for the image of an active star. Override this method to provide your own images.
      Parameters:
      iteration - the sequence number of the star
      Returns:
      the url pointing to the image for active stars.

    • getInactiveStarUrl

      protected String getInactiveStarUrl(int iteration)
      Returns the url pointing to the image of inactive stars, is used to set the URL for the image of an inactive star. Override this method to provide your own images.
      Parameters:
      iteration - the sequence number of the star
      Returns:
      the url pointing to the image for inactive stars.

    • setRatingLabelVisible

      public RatingPanel setRatingLabelVisible(boolean visible)
      Sets the visibility of the rating label.
      Parameters:
      visible - true when the label should be visible
      Returns:
      this for chaining.

    • onIsStarActive

      protected abstract boolean onIsStarActive(int star)
      Returns true when the star identified by its sequence number should be shown as active.
      Parameters:
      star - the sequence number of the star (ranging from 0 to nrOfStars)
      Returns:
      true when the star should be rendered as active

    • onRated

      protected abstract void onRated(int rating, Optional<AjaxRequestTarget> target)
      Notification of a click on a rating star. Add your own components to the request target when you want to have them updated in the Ajax request. NB the target may be null when the click isn't handled using AJAX, but using a fallback scenario.
      Parameters:
      rating - the number of the star that is clicked, ranging from 1 to nrOfStars
      target -