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.WebMarkupContainerWithAssociatedMarkup
                  org.apache.wicket.markup.html.panel.Panel
                      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.