webuijsf
Tag rating


Use the webuijsf:rating tag to present a row of stars indicating a rating assigned to an item. When the user assigns a new rating to an item, an Ajax request transmits the rating to the server.

Facets

None.

Theme Identifiers

None.

Client Side Javascript Functions

When the rating component is rendered, a DOM object corresponding to the rating component is created. To manipulate the component on the client side, you can call functions on the DOM object. For example, with reference to the DOM ID, to deny the user from selecting a grade, invoke document.getElementById(id).setProps({"gradeReadOnly": true}).

Function Description
domNode.getProps() Use this function to get widget properties. See setProps() function for a list of supported properties. 
domNode.refresh(execute) Use this function to asynchronously refresh the component.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run.
domNode.setProps(props) Use this function to change any of the following supported properties:
  • autoSubmit
  • averageGrade
  • clearAcknowledgedText
  • clearHoverText
  • grade
  • gradeAcknowledgedText
  • gradeHoverTexts
  • gradeReadOnly
  • inAverageMode
  • includeClear
  • includeModeToggle
  • includeNotInterested
  • includeText
  • maxGrade
  • modeReadOnly
  • modeToggleAcknowledgedTexts
  • modeToggleHoverTexts
  • notInterestedAcknowledgedText
  • notInterestedHoverText
  • tabIndex
  • id
  • visible
domNode.submit(execute) Use this function to asynchronously submit the selected grade.
  • [optional] execute: Comma separated string containing a list of client ids against which the execute portion of the request processing lifecycle must be run.
domNode.subscribe(topic, obj, func) Use this function to subscribe to an event topic.
  • topic: The event topic to subscribe to
  • obj: The object in which a function will be invoked, or null for default scope
  • func: The name of a function on context, or a function reference to invoke when event topic is published

Client Side JavaScript Events

When the component is manipulated on the client side, some functions might publish event topics for custom AJAX implementations to listen for. For example, you can listen for the submit event topic by using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
	    // Do something...
        }
    }

    // Subscribe to submit event.
    var domNode = document.getElementById("form1:rating");
    domNode.subscribe(domNode.event.submit.endTopic, processEvents, "update");

</webuijsf:script>

The following events are supported.


Event Description
<Node>.event.refresh.beginTopic Event topic published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id to process the event for
<Node>.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include:
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage.
<Node>.event.submit.beginTopic Event topic published before asynchronously submitting the selected grade. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client id of the rating component
  • value - The value (grade) of the rating component
<Node>.event.submit.endTopic Event topic published after asynchronously submitting the selected grade. Supported properties include:
  • id - The client id of the rating component
  • averageGrade - The updated average grade of the rating component
<Node>.event.state.beginTopic Event topic published before changing the state of the rating component due to the user clicking on the component. Supported properties include:
  • id - The client id of the rating component
<Node>.event.state.endTopic Event topic published after changing the state of the rating component due to the user clicking on the component. Supported properties include:
  • id - The client id of the rating component

Code Examples

Example 1:

In this example, the component includes the clear and not interested controls, but not mode toggle. Hover text displays over all controls. The initial grade is cleared. The selected grade is automatically submitted asynchronously.
    <webuijsf:rating id="rating"
        autoSubmit="true"
        averageGrade="#{RatingBean.averageGrade}"
        clearHoverText="Clear Rating"
        grade="#{RatingBean.grade}"
        gradeHoverTexts="#{RatingBean.gradeHoverTexts}"
        notInterestedHoverText="Not Interested"
        maxGrade="5">
    </webuijsf:rating>

The corresponding backing bean would be something like this:

    import com.sun.webui.jsf.component.Rating;
    
    public class RatingBackingBean {
    
        private double averageGrade = 0.0;
        private int grade = Rating.CLEAR_GRADE;
        private String[] gradeHoverTexts = {
            "Hate It",
            "Below Average",
            "Average",
            "Above Average",
            "Love It"
        };
        private int gradeSum = 0;
        private int numGrades = 0;
        private int numNotInterested = 0;
        
        public RatingBackingBean() {
        }
    
        public int getNumNotInterested() {
            return this.numNotInterested;
        }
    
        public void setNumNotInterested(int numNotInterested) {
            this.numNotInterested = numNotInterested;
        }
        
        public int getGrade() {
            return grade;
        }
        
        public void setGrade(int grade) {
            this.grade = grade;
    
            // Not interested grade does not factor into average grade
            if (this.grade == Rating.NOT_INTERESTED_GRADE) {
                this.numNotInterested++;
                return;
            }
    
            // Clear grade does not factor into average grade
            if (this.grade == Rating.CLEAR_GRADE) {
                return;
            }
    
            gradeSum += grade;
            numGrades++;
        }
        
        public double getAverageGrade() {
            if (numGrades == 0)
                return 0.0;
    
            // Compute average grade, rounded to neaest .001
            averageGrade = (double)gradeSum / numGrades;
            averageGrade = Math.rint(averageGrade * 1000) / 1000;
            return averageGrade;
        }
        
        public void setAverageGrade(double averageGrade) {
            this.averageGrade = averageGrade;
        }
            
        public String[] getGradeHoverTexts() {
            return this.gradeHoverTexts;
        }
    
        public void setGradeHoverTexts(String[] gradeHoverTexts) {
            this.gradeHoverTexts = gradeHoverTexts;
        }
    }

Example 2:

In this example, the component includes the clear, not interested, and mode toggle controls. Hover text displays over all controls. Initial displayed grade is cleared. Initially renders in average mode with average grade of 2.5. Acknowledgements appear in text area when clicking on controls. autoSubmit is disabled, but widget state change is tracked and the grade is asynchronously submitted from the jsp only if the selected grade changes.
    <webuijsf:rating id="rating"
        averageGrade="#{RatingBean.averageGrade}"
        clearHoverText="Clear Rating"
        clearAcknowledgedText="Rating cleared"
        grade="#{RatingBean.grade}"
        gradeAcknowledgedText="Thank you!"
        gradeHoverTexts="#{RatingBean.gradeHoverTexts}"
        inAverageMode="true"
        includeModeToggle="true"
        modeToggleAcknowledgedTexts="#{RatingBean.modeToggleAcknowledgedTexts}"
        modeToggleHoverTexts="#{RatingBean.modeToggleHoverTexts}"
        notInterestedAcknowledgedText="Sorry to hear"
        notInterestedHoverText="Not Interested"
        maxGrade="5">
    </webuijsf:rating>

The corresponding backing bean would be similar to the one in Example 1 but with the following changes:

        private int gradeSum = 5;
        private int numGrades = 2;
    
        private String[] modeToggleHoverTexts = {
           "Show user's rating",
           "Show average rating"
        };
    
        private String[] modeToggleAcknowledgedTexts = {
           "Normal rating shown",
           "Average rating shown"
        };
        
        public String[] getModeToggleHoverTexts() {
            return this.modeToggleHoverTexts;
        }

        public String[] getModeToggleAcknowledgedTexts() {
            return this.modeToggleAcknowledgedTexts;
        }

The application's javascript to manage the submit might look like this:

    <webuijsf:script type="text/javascript">
        function RatingListener(id) {
            this.ratingID = id;
            this.previousGrade = null;
        }

        // Callback for after state change
        function AfterStateChange(props) {
            if (props.id != this.ratingID)
                return;

            // Get rating node
            var ratingNode = document.getElementById(this.ratingID);
            if (ratingNode == null)
                return;

            // Get properties for the node
            props = ratingNode.getProps();

            // Submit only if the grade has changed from it's previous value.
            if ((this.previousGrade != null) && (this.previousGrade != props.grade)) {
                ratingNode.submit();
                this.previousGrade = null;
            }
        }
        RatingListener.prototype.afterStateChange = AfterStateChange;

        // Callback for start of state change.  We save off the current grade
        // before it changes.
        // 
        function StartStateChange(props) {
            if (props.id != this.ratingID)
                return;
            var ratingNode = document.getElementById(this.ratingID);
            if (ratingNode == null)
                return;
            props = ratingNode.getProps();
            this.previousGrade = props.grade;
        }
        RatingListener.prototype.startStateChange = StartStateChange;

        function rating_init() {
            var domNode = document.getElementById("rating");
            if (domNode == null || domNode.event == null) {
                return setTimeout('rating_init();', 10);
            }
            var listener = new RatingListener("rating");

            // Subscribe to pre/post state change events
            domNode.subscribe(domNode.event.state.beginTopic, listener, listener.startStateChange);
            domNode.subscribe(domNode.event.state.endTopic, listener, listener.afterStateChange);
        }
    </webuijsf:script>

    <webuijsf:body onLoad="rating_init();">
    ...


Tag Information
Tag Classcom.sun.webui.jsf.component.RatingTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This attribute allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
notInterestedAcknowledgedTextfalsefalsejava.lang.String

The acknowledged text for the "not interested" control. There is no default.

averageGradefalsefalsejava.lang.String

The average grade the general user population has assigned to the item. Must be between 0.0 and the maximum grade. This attribute should be set to a value binding expression that corresponds to a property of a managed bean so it will be updated whenever a grade is clicked and the grade property is updated asynchronously.

modeToggleAcknowledgedTextsfalsefalsejava.lang.String

The acknowledged texts to be used for the mode toggle control. The attribute's value must be a JavaServer Faces EL expression that evaluates to an array of java.util.String. The first element of the returned array is the acknowledged text displayed after clicking the mode toggle control to preview the user's rating (normal mode). The second element is the text displayed after clicking to preview the average rating (average mode). Null can be specified as a member of the array. There are no defaults.

maxGradefalsefalsejava.lang.String

The maximum grade (number of "stars") this rating instance allows. There is no default, and so must be set.

clearHoverTextfalsefalsejava.lang.String

The hover text for the clear control. There is no default.

inAverageModefalsefalsejava.lang.String

Indicates whether the component will be rendered displaying the average grade. The default is false, the component will be rendered showing the user's rating (normal mode).

includeTextfalsefalsejava.lang.String

Indicates whether an area for hover or post-click acknowledeged text should be rendered. The default is true.

clearAcknowledgedTextfalsefalsejava.lang.String

The acknowledged text for the clear control. There is no default.

modeReadOnlyfalsefalsejava.lang.String

Indicates whether the mode of this rating component can be changed by the user. The default is false - it is NOT read-only, and therefore can be changed by the user.

gradefalsefalsejava.lang.String

The grade (number of "stars") the user has assigned the item. This attribute should be set to a value binding expression that corresponds to a property of a managed bean so it will be updated whenever a grade is clicked. A managed bean can set the value to Rating.NOT_INTERESTED_GRADE for a not interested grade and Rating.CLEAR_GRADE for a cleared (effectively, set it to 0) grade.

gradeReadOnlyfalsefalsejava.lang.String

Indicates whether the grade of this rating component can be changed by the user. The default is false - it is NOT read-only, and therefore can be changed by the user.

notInterestedHoverTextfalsefalsejava.lang.String

The hover text for the "not interested" control. There is no default.

autoSubmitfalsefalsejava.lang.String

Indicates whether the grade is automatically submitted to the server via an Ajax request immediately after the grade is selected. The default is false - it is NOT automatically submitted.

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

gradeAcknowledgedTextfalsefalsejava.lang.String

The acknowledged text for the grade controls. There is no default.

gradeHoverTextsfalsefalsejava.lang.String

The hover texts that will be used for the grade controls, ordered from lowest to highest rating. The attribute's value must be a JavaServer Faces EL expression that evaluates to an array of java.util.String. The first element will be the hover text associated with the lowest rating; the last element with the highest rating. Null can be specified as a member of the array. There are no defaults.

stylefalsefalsejava.lang.String

CSS style or styles to be applied to the outermost HTML element when this component is rendered.

visiblefalsefalsejava.lang.String

Use to indicate whether the component should be viewable by the user in the rendered HTML page. If set to false, the HTML code for the component is present in the page, but the component is hidden with style attributes. By default, visible is set to false, so HTML for the component HTML is included and not visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

modeToggleHoverTextsfalsefalsejava.lang.String

The hover texts to be used for the mode toggle control. The attribute's value must be a JavaServer Faces EL expression that evaluates to an array of java.util.String. The first element of the returned array is the hover text displayed when hovering over the mode toggle control to preview the user's rating (normal mode). The second element is the text displayed when hovering to preview the average rating (average mode). Null can be specified as a member of the array. There are no defaults.

includeNotInterestedfalsefalsejava.lang.String

Indicates whether a control to allow the user to assign a "not interested" rating should be rendered. The default is true.

includeClearfalsefalsejava.lang.String

Indicates whether a control to clear the user's rating should be displayed. The default is true.

tabIndexfalsefalsejava.lang.String

Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767.

includeModeTogglefalsefalsejava.lang.String

Indicates whether a control to toggle the mode (to show the average rating or the user's rating) should be rendered. The default is false.

converterfalsefalsejava.lang.String Specifies a method to translate native property values to String and back for this component. The converter attribute value must be one of the following:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
requiredfalsefalsejava.lang.String Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
immediatefalsefalsejava.lang.String Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase.
validatorExpressionfalsefalsejava.lang.String Used to specify a method in a backing bean to validate input to the component. The value must be a JavaServer Faces EL expression that resolves to a public method with return type void. The method must take three parameters:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

renderedfalsefalsejava.lang.String Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission.
valueChangeListenerExpressionfalsefalsejava.lang.String Specifies a method to handle a value-change event that is triggered when the user enters data in the input component. The attribute value must be a JavaServer Faces EL expression that resolves to a backing bean method. The method must take a single parameter of type javax.faces.event.ValueChangeEvent, and its return type must be void. The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.
idfalsetruejava.lang.StringNo Description

Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.