Package org.apache.wicket.extensions.rating

Class 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:
    Serialized Form

    • Constructor Detail

      • 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 Detail

      • 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 -