webuijsf
Tag radioButtonGroup


Use the webuijsf:radioButtonGroup tag to display two or more radio buttons in a grid layout in the rendered HTML page. The webuijsf:radioButtonGroup tag attributes that you specify determine how the radio buttons are displayed.

If the label attribute is specified a com.sun.webui.jsf.component.Label component is rendered before the first radio button and identifies the radio button group. The label component's for attribute is set to the id attribute of the first radio button in the rendered HTML page.

The radio buttons are laid out in rows and columns in an HTML <table> element. The number of rows is defined by the length of the items array. The number of columns is defined by the columns attribute. The default layout is a single vertical column.

The items attribute must be a value binding expression. The value binding expression assigned to the items property evaluates to an Object array of com.sun.webui.jsf.model.Option instances. Each instance represents one radio button. The value property of an Option instance represents the value of a selected radio button. If the items array is empty nothing is rendered.

At least one radio button should be selected by the application. The selected attribute must also be a value binding expression that is evaluated to read and write an Object. When an Object value is read from the value binding expression, it identifies the selected radio button. The Object value must be equal to the value property of at least one Option instance specified in the array obtained from the value binding expression assigned to the items attribute.

The write method of the selected attribute value binding expression is called during the UPDATE_MODEL_PHASE of the JSF lifecyle. If a radio button is selected an Object value is passed as an argument to the write method. The Object value is the value of the selected radio button.

HTML Elements and Layout

A webuijsf:radioButtonGroup renders one com.sun.webui.jsf.component.RadioButton component for each element in the items array. See webuijsf:radioButton for details on the HTML elements and components rendered for a radio button.

The value of the name attribute of each RadioButton component rendered is assigned the clientId of the RadioButtonGroup component instance associated with this tag. The id attribute of each RadioButton component rendered is formed as follows, where rbgrpid is the id of the RadioButtonGroup instance and N is the nth radio button.

See webuijsf:radioButton for details on how the id properties of the components that make up the radio button are defined.

Theme Identifiers

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM id, to disable the component, invoke document.getElementById(id).setProps({disabled: true}).

getProps() Use this function to get widget properties. Please see setProps() function for a list of supported properties.
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. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • align
  • className
  • contents
  • dir
  • disabled
  • id
  • label
  • lang
  • name
  • readOnly
  • style
  • tabIndex
  • title
  • visible

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. Using the Dojo event system, listen for the refresh event topic using:

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

    // Subscribe to refresh event.
    dojo.subscribe(webui.suntheme.widget.rbcbGroup.event.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.

webui.suntheme.widget.rbcbGroup.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
webui.suntheme.widget.rbcbGroup.event.refresh.endTopic Event topic published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage

Examples

Example 1: Create a radio button group

 <webuijsf:radioButtonGroup items="#{rbcbGrp.selections}"
    label="#{rbcbGrp.rbGrpLabel}"
    toolTip="rbgrp-tooltip"
    tabIndex="1"
    columns="3"
    labelLevel="2"
    selected="#{rbcbGrp.selection}">
 </webuijsf:radioButtonGroup>

This example creates a radio button group with an identifying label for the group before the first radio button. The data for the radio buttons is obtained from the value binding expression #{rbcbGrp.selections} where rbcbGrp is an application defined managed bean. The bean provides the values for other attributes such as selected to receive the value of the selected radio button in the group.

Example 2: Update radioButtonGroup client side using the getProps and setProps functions

This example shows how to toggle the disabled state of a radioButtonGroup client side using the getProps and setProps functions.

<webuijsf:radioButtonGroup id="rb1" name="rb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:button id="button1" text="Toggle radioButtonGroup Disabled" onClick="toggleDisabled(); return false"/>

<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:rb1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>

Example 3: Asynchronously update radioButtonGroup using refresh function

This example shows how to asynchronously update a radioButtonGroup using the refresh function. When the user clicks on the button, the radioButtonGroup is asynchronously updated with new data.
<webuijsf:radioButtonGroup id="rb1" name="rb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:button id="button1" text="Refresh radioButtonGroup" onClick="refreshGroup(); return false;"/>
<webuijsf:script>
    function refreshGroup() {
        var domNode = document.getElementById("form1:cb1"); // Get radioButtonGroup
        return domNode.refresh(); // Asynchronously refresh radioButtonGroup
    }
</webuijsf:script>

Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,..."). When no parameter is given, the refresh function acts as a reset. That is, the component will be redrawn using values set server-side, but not updated.

Example 4: Asynchronously update radioButtonGroup using refresh function

This example shows how to asynchronously update a radioButtonGroup using the refresh function. The execute property of the refresh function is used to define the client id which is to be submitted and updated server-side. As the user types in the text field, the input value is updated server-side and the radioButtonGroup label is updated client-side -- all without a page refresh.
<webuijsf:radioButtonGroup id="rb1" name="rb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:textField id="field1" text="#{rbcbGrp.cbGrpLabel}" label="Change radioButtonGroup Label"
onKeyPress="setTimeout('refreshRadioButtonGroup();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
    function
refreshRadioButtonGroup() {
        var domNode = document.getElementById("form1:cb1"); // Get radioButtonGroup
        return domNode.refresh("form1:field1"); // Asynchronously refresh while submitting field value
    }
</webuijsf:script>


Note that the refresh function can optionally take a list of elements to execute. Thus, a comma-separated list of ids can be provided to update components server-side: refresh("form1:id1,form2:id2,...")



Tag Information
Tag Classcom.sun.webui.jsf.component.RadioButtonGroupTag
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 binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
htmlTemplatefalsefalsejava.lang.String Alternative HTML template to be used by this component.
visiblefalsefalsejava.lang.String

Indicates 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 true, so HTML for the component HTML is included and visible to the user. If the component is not visible, it can still be processed on subsequent form submissions because the HTML is present.

columnsfalsefalsejava.lang.String Defines how many columns may be used to layout the radio buttons. The value must be greater than or equal to one. The default value is one. Invalid values are ignored and the value is set to one.
onDblClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse double-click occurs over this component.

onKeyPressfalsefalsejava.lang.String

Scripting code that is executed when the user presses and releases a key while the component has the focus.

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.
idfalsetruejava.lang.StringNo Description
onKeyUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a key while the component has the focus.

onMouseUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

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

itemsfalsefalsejava.lang.String

Specifies the options that the web application user can choose from. The value must be one of an array, Map or Collection whose members are all subclasses ofcom.sun.webui.jsf.model.Option.

stylefalsefalsejava.lang.String

CSS style or styles that are applied to the outermost HTML element when the component is rendered.

onClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse click occurs over the component.

toolTipfalsefalsejava.lang.String

Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element.

onMouseDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses a mouse button while the mouse pointer is on the component.

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.
disabledfalsefalsejava.lang.String

Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form.

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.

onMouseOutfalsefalsejava.lang.String

Scripting code that is executed when a mouse out movement occurs over this component.

onMouseOverfalsefalsejava.lang.String

Scripting code that is executed when the user moves the mouse pointer into the boundary of this component.

onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

selectedfalsefalsejava.lang.String

The object that represents the selections made from the available options. If multiple selections are allowed, this must be bound to an Object array, or an array of primitives.

labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

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.
onKeyDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses down on a key while the component has the focus.

labelLevelfalsefalsejava.lang.String

Sets the style level for the generated label, provided the label attribute has been set. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2.

readOnlyfalsefalsejava.lang.String

If true, the value of the component is rendered as text, preceded by the label if one was defined.

@deprecated The attribute is deprected starting from version 4.1
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.
tabIndexfalsefalsejava.lang.String

Describes the 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.


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.