org.apache.wicket.extensions.rating
Class RatingPanel

java.lang.Object
  extended by org.apache.wicket.Component
      extended by org.apache.wicket.MarkupContainer
          extended by org.apache.wicket.markup.html.WebMarkupContainer
              extended by org.apache.wicket.markup.html.WebMarkupContainerWithAssociatedMarkup
                  extended by org.apache.wicket.markup.html.panel.Panel
                      extended by org.apache.wicket.extensions.rating.RatingPanel
All Implemented Interfaces:
Serializable, IClusterable, IConverterLocator, IHeaderPartContainerProvider

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, AjaxRequestTarget) 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

Nested Class Summary
 
Nested classes/interfaces inherited from class org.apache.wicket.Component
Component.ComponentModelChange, Component.EnabledChange, Component.IVisitor<T extends Component>, Component.VisibilityChange
 
Field Summary
static ResourceReference STAR0
          Star image for no selected star
static ResourceReference STAR1
          Star image for selected star
 
Fields inherited from class org.apache.wicket.Component
ENABLE, FLAG_CONFIGURED, FLAG_INITIALIZED, FLAG_REMOVING_FROM_HIERARCHY, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED6, FLAG_RESERVED7, FLAG_RESERVED8, PATH_SEPARATOR, RENDER
 
Constructor Summary
RatingPanel(String id)
          Constructs a rating component with 5 stars, using a compound property model as its model to retrieve the rating.
RatingPanel(String id, IModel<? extends Number> rating)
          Constructs a rating component with 5 stars, using the rating for retrieving the rating.
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.
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.
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.
RatingPanel(String id, int nrOfStars)
          Constructs a rating component with nrOfStars stars, using a compound property model as its model to retrieve the rating.
 
Method Summary
 void addDefaultCssStyle()
          Will let the rating panel contribute a CSS include to the page's header.
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.
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.
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'.
protected  Component newRatingStarBar(String id, IModel<Integer> nrOfStars)
          Creates a new bar filled with stars to click on.
protected abstract  boolean onIsStarActive(int star)
          Returns true when the star identified by its sequence number should be shown as active.
protected abstract  void onRated(int rating, AjaxRequestTarget target)
          Notification of a click on a rating star.
 RatingPanel setRatingLabelVisible(boolean visible)
          Sets the visibility of the rating label.
 
Methods inherited from class org.apache.wicket.markup.html.panel.Panel
onComponentTag, onComponentTagBody, renderHead
 
Methods inherited from class org.apache.wicket.markup.html.WebMarkupContainerWithAssociatedMarkup
newHeaderPartContainer, renderHeadFromAssociatedMarkupFile
 
Methods inherited from class org.apache.wicket.markup.html.WebMarkupContainer
getMarkupType, getWebPage, getWebRequest
 
Methods inherited from class org.apache.wicket.MarkupContainer
add, addOrReplace, autoAdd, autoAdd, contains, findMarkupStream, get, get, getAssociatedMarkupStream, getMarkupStream, hasAssociatedMarkup, internalAdd, isTransparentResolver, iterator, iterator, newMarkupResourceStream, onAfterRenderChildren, onRender, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderComponentTagBody, renderNext, replace, setDefaultModel, setMarkupStream, size, swap, toString, toString, visitChildren, visitChildren
 
Methods inherited from class org.apache.wicket.Component
add, addStateChange, afterRender, beforeRender, callOnBeforeRenderIfNotVisible, checkComponentTag, checkComponentTagAttribute, checkHierarchyChange, configure, continueToOriginalDestination, debug, detach, detachBehaviors, detachModel, detachModels, determineVisibility, error, exceptionMessage, fatal, findPage, findParent, findParentWithAssociatedMarkup, getApplication, getBehaviors, getBehaviors, getBehaviorsRawList, getClassRelativePath, getComponentBorder, getConverter, getConverter, getDefaultModel, getDefaultModelObject, getDefaultModelObjectAsString, getDefaultModelObjectAsString, getEscapeModelStrings, getFeedbackMessage, getFlag, getFlag, getId, getInnermostModel, getInnermostModel, getLocale, getLocalizer, getMarkupAttributes, getMarkupId, getMarkupId, getMarkupIdImpl, getMetaData, getModelComparator, getOutputMarkupId, getOutputMarkupPlaceholderTag, getPage, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getResponse, getSession, getSizeInBytes, getStatelessHint, getString, getString, getString, getStyle, getVariation, hasBeenRendered, hasErrorMessage, hasFeedbackMessage, info, initModel, internalAttach, internalDetach, internalOnAttach, internalOnDetach, internalOnModelChanged, isActionAuthorized, isAncestorOf, isAttached, isBehaviorAccepted, isEnableAllowed, isEnabled, isEnabledInHierarchy, isIgnoreAttributeModifier, isRenderAllowed, isStateless, isVersioned, isVisibilityAllowed, isVisible, isVisibleInHierarchy, locateMarkupStream, markAttached, markRendering, modelChanged, modelChanging, onAfterRender, onAttach, onBeforeRender, onBeginRequest, onConfigure, onDetach, onEndRequest, onInitialize, onModelChanged, onModelChanging, onRemove, prepareForRender, prepareForRender, redirectToInterceptPage, remove, remove, render, render, renderComponent, renderComponent, renderComponentTag, rendered, renderPlaceholderTag, replaceComponentTagBody, replaceWith, sameInnermostModel, sameInnermostModel, setAuto, setComponentBorder, setDefaultModelObject, setEnabled, setEscapeModelStrings, setFlag, setFlag, setIgnoreAttributeModifier, setMarkupId, setMarkupIdImpl, setMetaData, setOutputMarkupId, setOutputMarkupPlaceholderTag, setRedirect, setRenderBodyOnly, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisibilityAllowed, setVisible, urlFor, urlFor, urlFor, urlFor, urlFor, urlFor, visitParents, warn, wrap
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STAR0

public static final ResourceReference STAR0
Star image for no selected star


STAR1

public static final ResourceReference STAR1
Star image for selected star

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

addDefaultCssStyle

public final void addDefaultCssStyle()
Will let the rating panel contribute a CSS include to the page's header. It will add RatingPanel.css from this package. This method is typically called by the class that creates the rating panel.


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,
                                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 - the request target, null if the request is a regular, non-AJAX request.


Copyright © 2004-2011 Apache Software Foundation. All Rights Reserved.