RadioButtonBase

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sun.rave.web.ui.component
Class RadioButtonBase

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          javax.faces.component.UIOutput
              javax.faces.component.UIInput
                  com.sun.rave.web.ui.component.SelectorBase
                      com.sun.rave.web.ui.component.Selector
                          com.sun.rave.web.ui.component.RbCbSelectorBase
                              com.sun.rave.web.ui.component.RbCbSelector
                                  com.sun.rave.web.ui.component.RadioButtonBase

All Implemented Interfaces:: javax.faces.component.EditableValueHolder, SelectorManager, javax.faces.component.StateHolder, javax.faces.component.ValueHolder

Direct Known Subclasses:: RadioButton

public abstract class RadioButtonBase
extends RbCbSelector

Use the ui:radioButton tag to display a radio button in the rendered HTML page. The tag can be used as a single radio button or as one radio button among a group of radio buttons. A group of radio buttons represents a single selection list. A radio button can represent a value of a class type such as Boolean, Byte, Character, Double, Float, Integer, Long, Short, String or the primitive form of one of these class types. A radio button may also represent an application defined object value.

A Boolean value is useful for indicating whether an item, such as a table row, is selected. A String value is useful for passing a value for the radio button selection made in the interface. An application defined Object value or class instance can be used to hold more information related to the radio button selection.

A group of radio buttons is the common way to use the the radioButton tag. It can be used to represent different types of data:

a group of boolean controls where only one control is selected at a time.
string values that are related to the radio button selection
object values defined by the application

Note: It is not common to use a radioButton tag that is not in a group. If a single radio button is not in a group, once it is selected by the user in the interface, the user cannot deselect it. This is because a radio button is defined to be a single selection among several where one radio button is always selected. Since there are no other radio buttons grouped with the single radio button, the user cannot select an alternative, to cause the selected radio button to be deselected.

Note: Another tag for rendering radio buttons is ui:radioButtonGroup, which imposes a grid layout on a group of radio buttons. The radioButton tag is useful in situations where the radioButtonGroup tag layout is not desirable, such as in a table row where only one row among several may be selected.

Detecting a selected radio button

The radioButton tag uses both the selected and selectedValue attributes to pass information about the radio button's selection status. The selected attribute is used to indicate that the radio button is selected, and should have a check mark displayed in the page. The selectedValue attribute is used to pass a data value for the radio button. A radio button is considered to be selected when the value of the selected attribute is equal to the value of the selectedValue attribute. You can display a radio button as selected on the initial viewing of the page by assigning the same value to the selectedValue and the selected attributes.

If the selectedValue attribute is not specified or its value is null then the radio button behaves like a boolean control. If the radio button is selected, the value of the selected attribute is a true Boolean instance. If the radio button is not selected, the value of the selected attribute will be a false Boolean instance.

Note that a value binding expression that evaluates to a primitive boolean value can be assigned to the selected and selectedValue attributes.

When a radio button is part of a group, the value of the selected radio button is maintained as a request attribute value in the RequestMap. The attribute name is the value of the name attribute. The value of the request attribute is the value of the selectedValue attribute of the selected radio button. The value of the selected attribute will also be equal to the selectedValue attribute of the selected radio button. If no radio button is selected, no request attribute will be created.
The RadioButton class provides a convenience method for obtaining the selected radio button in a group:

public static Object getSelected(String groupName);

where groupName is the value of the name attribtue. Note that unlike the selected and selectedValue attributes, the return value of this method is always a class instance and not a primitive value.

Note that the radioButton does not enforce that at least one radio button is always be selected. The application must ensure this behavior if necessary.

Using a `radioButton` tag as a boolean control

If the selectedValue attribute is not specified or its value is null then the radio button behaves like a boolean control.

To use the radioButton tag as a boolean control, do not specify a value for the selectedValue attribute. The radio button is selected if the selected attribute is not null and has the value of a true Boolean instance or boolean primitive. If the radio button is not selected, then the value of the selected attribute is a false Boolean instance or boolean primitive.

Normally the value of the selectedValue attribute is specified as the value of the <input> HTML element. When a radio button is behaving as a boolean control the value of the <input> element is the clientId of the radio button.

Note that using a boolean radio button in a group and referencing the request attribute for the selected radio button is not useful, since the value of the request attribute will be an indistinguishable Boolean true value.

Using a `radioButton` tag to represent an application defined value

The selectedValue attribute can be assigned an application defined object value to represent the value of a selected radio button. If the radio button is selected, the value of the selected attribute is assigned the value of the selectedValue attribute.

If the value of the selectedValue attribute is an application defined object, a converter must be registered to convert to and from a String value. The converter is used to encode the radio button value as the value of the HTML <input> element and to decode the submitted value in a request. In addition the object must support an equals method that returns true when the value of the selectedValue attribute is compared to the selected attribute value in order to detect a selected radio button.

Using a `radioButton` tag as one control in a group

The name attribute determines whether a radio button is part of a group. A radio button is treated as part of a group of radio buttons if the name attribute of the radio button is assigned a value equal to the name attribute of the other radio buttons in the group. In other words, all radio buttons of a group have the same name attribute value. The group behaves like a single selection list, where only one radio button can be selected. The value of the name attribute must be unique within the scope of the <form> element containing the radio buttons.

Facets

The following facets are supported:

image If the image facet exists, it is rendered to the immediate right hand side of the radio button.
label If the label facet exists, it is rendered to the immediate right of the image, or to the immediate right of the radio button if no image is rendered.

Examples

Example 1: Two grouped boolean radio buttons with value bindings.


 <ui:radioButton id="rb0" name="rb1grp"
     selected="#{tldRbCbExample.selectedRb0}"/>

 <br/>

 <ui:radioButton id="rb1" name="rb1grp"
     selected="#{tldRbCbExample.selectedRb1}"/>

The value bindings imply that there are two methods implemented in the tldRbCbExample managed bean for each value binding.

public void setSelectedRb0(boolean selected)
public boolean getSelectedRb0()
public void setSelectedRb1(boolean selected)
public boolean getSelectedRb1()

No image or label will be displayed by this example.

Example 2: Two grouped boolean radio buttons with value bindings, that display an image and a label.


 <ui:radioButton id="rb2" name="rb2grp" 
     imageURL="tree_server.gif" label="Server"
     selected="#{tldRbCbExample.selectedRb2}"/>

 <br/>

 <ui:radioButton id="rb3" name="rb2grp"
     imageURL="pool_tree.gif" label="Pool"
     selected="#{tldRbCbExample.selectedRb3}"/>

The behavior of these radio buttons is the same as example one.
In this example an image and a label are displayed next to both radio buttons. Both the imageURL and label attributes may be assigned value binding expressions instead of literal values.

Example 3: Two grouped String valued radio buttons with value bindings and labels.


 <ui:radioButton id="rb4" name="rb3grp" 
 	label="Print" selectedValue="Print"
 	selected="#{tldRbCbExample.selectedRb4}"/>

 <br/>

 <ui:radioButton id="rb5" name="rb3grp"
 	label="Fax" selectedValue="Fax"
 	selected="#{tldRbCbExample.selectedRb5}"/>

The value bindings imply that there are two methods implemented in the tldRbCbExample managed bean for each value binding. Because the selectedValue attribute is a String the expected method signatures will be:

public void setSelectedRb4(String selected)
public String getSelectedRb4()
public void setSelectedRb5(String selected)
public String getSelectedRb5()

When the radio button is checked by the user the "setSelected" methods will be called with a String argument equal to the value of the selectedValue attribute of the radio button.
When it is unchecked the method will be called with a null String argument.
For example if radio button "rb4" is checked by the user setSelectedRb4 will be called with "Print" as the argument and setSelectedRb5 will be called with a null argument.

Example 4: Two grouped object valued radio buttons with value bindings and labels.


 <ui:radioButton id="rb6" name="rb4grp" label="Print"
 	selectedValue="#{tldRbCbExample.selectedValueRb6}"
 	selected="#{tldRbCbExample.selectedRb6}"
 	converter="#{tldRbCbExample.rbConverter}"/>

 <br/>

 <ui:radioButton id="rb7" name="rb4grp" label="Fax"
 	selectedValue="#{tldRbCbExample.selectedValueRb7}"
 	selected="#{tldRbCbExample.selectedRb7}"
 	converter="#{tldRbCbExample.rbConverter}"/>

The value bindings imply that there are two methods implemented in the tldRbCbExample managed bean for each value binding. Let's say the object value for "rb6" is an instance of the "Printer" class, and "rb7" an instance of the "Fax" class, then the expected method signatures will be:

public void setSelectedRb6(Printer selected)
public Printer getSelectedRb6()
public void setSelectedValueRb7(Fax selected)
public Printer getSelectedValueRb7()

A Printer class might look like:

     public class Printer implements Device {
 	private String name;
 	private String location;
 	
 	public Printer(String name, String location) {
 	    this.name = name;
 	    this.location = location;
 	}
 	public String getName() {
 	    return name;
 	}
 	public String getLocation() {
 	    return location;
 	}
 	public int getType() {
 	    return Device.PRINTER;
 	}
 	public boolean equals(Printer p) {
 	    return this.name.equals(p.getName()) &&
 		    this.location.equals(p.getLocation()) &&
 		    p.getType() == Device.PRINTER;
 	}
     };

A Fax class might look like:

     public class Fax implements Device {
 	private String name;
 	private String phoneNumber;
 	
 	public Printer(String name, String phoneNumber) {
 	    this.name = name;
 	    this.phoneNumber = phoneNumber;
 	}
 	public String getName() {
 	    return name;
         }
 	public String getPhoneNumber() {
 	    return phoneNumber;
 	}
 	public int getType() {
 	    return Device.FAX;
 	}
 	public boolean equals(Fax f) {
 	    return this.name.equals(f.getName()) &&
 		    this.phoneNumber.equals(f.getPhoneNumber()) &&
 		    f.getType() == Device.FAX;
 	}
     };

Since this radio button represents an application defined object value, the application must provide a converter instance. The converter attribute's value binding expression implies a method in the tldRbCbExample managed bean called

public Converter getRbConverter();

The converter class might look like:

     public class RbConverter implements javax.faces.convert.Converter {
 	public RbConverter() {
 	}
 	public String getAsString(FacesContext context, 
 		UIComponent component, Object value) {
 	    if (!value instanceof Device) {
 		throw new ConverterException("Not a Device value");
 	    }
 	    return String.valueOf(((Device)value).getType());
 	}
 	public Object getAsObject(FacesContext context, 
 		UIComponent component, String value) {
 	    if (value == null) {
 		return null;
 	    }
 	    // value is the String representation of "getType"
 	    //
 	    int type = Integer.parseInt(value);
 	    switch (type) {
 	    case Device.PRINTER:
 		return deviceDb.getClosestPrinter();
 	    break;
 	    case Device.FAX:
 		return deviceDb.getFax();
 	    break;
 	    default:
 		throw new ConverterException("No such device : " + value);
 	    break;
 	    }
 	}
     };

The "getSelected" methods will be called to determine the checked state of the radio buttons during rendering.
When the tags are first rendered, the initial checked state is determined by the return value of the "getSelected" methods.
With Object valued radio buttons, a radio button will be checked only if the "getSelected" method returns an object instance that equals the object instance returned by the "getSelectedValue" method.
For example if getSelectedRb6 returns the Printer instance value of "rb6"'s selectedValue attribute, then "rb6" will be checked. getSelectedRb7 should return null. If the getSelectedRb6 method returns a Printer instance that is not equal as determined by getSelectedValueRb6().equals(getSelectedRb6()) the radio button will not be checked.
When the radio button is checked by the user the "setSelectedValue" methods will be called with the object instance returned by the converter.
For example if "rb6" is checked by the user, setSelectedRb6 will be called with a Printer instance returned by the converter. setSelectedRb7 will be called with a null argument.

Note that when radio buttons are part of a group the value of the selected radio button can be obtained directly from the request map. For example, processing the selection could take place in the action method of a submit button tag:

     public void submit() {
 
 	// RadioButton.getSelected(String groupName) is
 	// a static convenience method that obtains the 
 	// selected radio button value from the request map
 	// ONLY when the radio button is part of a group.
 	//
 	Object selection = RadioButton.getSelected("rb4grp");
 
 	// Assume at least one radio button will be selected.
 	//
 	processSelection((Device)selection);
     }

Example 5: Grouped Integer valued radio buttons in a table.

The following example shows a common use case for radio buttons in a table. The radio buttons are used to select at most one row for processing. The radio button state does not need to be stored. The selected row index can be obtained directly in the #{tldRbCbExample.table5process} method, using the RadioButton.getSelected(String groupName) convenience method. The markup in bold is how you would specify a radio button tag for this purpose. The selectedValue value binding, #{tldRbCbExample.currentRow1} is implemented to return the current row in the table5row1 tableRow tag.

Note that this example will not initially select a radio button which is normally not the way radio buttons are used; one is usually always checked.

     <ui:table id="table5">
 	<ui:tableRow id="table5row1"
 	    sourceData="#{tldRbCbExample.table5row1data}"
 	    sourceVar="table5data"
 	    binding="#{tldRbCbExample.table5row1}">
 	    <ui:tableColumn id="col1">
 
 		<f:facet name="header">
 		    <ui:tableHeader id="header1"
 			deselectAllButton="true"
 			selectAllButton="true"
 			selectId="rb5"/>
 		</f:facet>
 
 		
 		<ui:radioButton id="rb8" name="rb5grp" 
 			selectedValue="#{tldRbCbExample.currentRow1}">
 		</ui:radioButton>
 		
 
 	    </ui:tableColumn>
 	    <ui:tableColumn id="col2">
 		<f:facet name="header">
 		    <ui:staticText text="Application Data"/>
 		</f:facet>
 
 		<ui:staticText text="#{table5data.text}"/>
 
 	    </ui:tableColumn>
 	</ui:tableRow>
 	<f:facet name="tableActionsBottom">
 	   <ui:button id="table5process"
 		action="#{tldRbCbExample.table5process}"
 		text="Process Checked"/>
 	</f:facet>
     </ui:table>

See ui:table for details on using the <ui:table> tag and other table child tags and facets.

Normally when radio buttons are contained within a ui:tableRow the application MUST provide a value binding for the selected attribute and any attribute that is expected to maintain its state. This is because the table only creates a single instance of the radio button for all rows. It depends on a model to provide the storage for the attribute values, as it iterates over the rows in the dataset.
In this example, we don't need to maintain the state across requests because a row is only selected for processing. Once the processing is complete, the radio button no longer needs to be checked.

The following code shows how the table5process action method obtains the selected radio button value from the request map. It calls a static member on RadioButton to return the Integer row index.

     public void table5process() {
 
 	// RadioButton.getSelected(String groupName) is
 	// a static convenience method that obtains the 
 	// selected radio button value from the request map
 	// ONLY when the radio button is part of a group.
 	//
 	Integer row = (Integer)RadioButton.getSelected("rb5grp");
 	if (row != null) {
 	    processRow(row.intValue());
 	}
     }

Example 6: Grouped boolean radio buttons in a table, using value bindings to maintain the state.

This example is similar to Example 5, but it maintains the state of the radio buttons across requests, by specifying a value binding for the selected attribute. A simple way to store the radio button state, is to store the state with the row data. The following code replaces the "ui:radioButton" code in the previous example.


 	<ui:radioButton id="rb6" name="rb6grp"
 		selected="#{table6data.selected}">
 	</ui:radioButton>

The value binding #{table6data.selected} references a boolean member in the row data for storing and retrieving the radio button state.

HTML Elements and Layout

A radioButton is rendered as at least one HTML <span> element and one <input> element of type radio. Each radio button may consist of the following elements:

a <span> element
an <input> element of type radio
an optional image if the imageURL attribute or an image facet is specified. If the imageURL attribute is specified a com.sun.rave.web.ui.component.ImageComponent component is created and rendered. If an image facet is specified then the component specified by the facet is rendered.
an optional label if a label attribute or a label facet is specified. If the label attribute is specified a com.sun.rave.web.ui.component.Label component is created and rendered. If a label facet is specified then the component specified by the facet is rendered.

The id attributes for HTML elements are constructed as follows, where rid is the clientId of the component being rendered.

rid_span for the <span> element
rid for the <input element
rid_image for the image component if created.
rid_label for the label component if created.

Note that the value of the style and styleClass attributes of a radio button will be assigned to the containing <span> HTML element's style and class attributes respectively.

Client Side Javascript Functions

radioButton_setChecked(elementId, checked): Set the checked property for a radio button with the given element id, elementId. If checked is true the radio button is checked. If checked is false the radio button is unchecked.

Auto-generated component class. Do NOT modify; all changes will be lost!

Field Summary

Fields inherited from class com.sun.rave.web.ui.component.RbCbSelector

IMAGE_FACET, LABEL_FACET

Fields inherited from class com.sun.rave.web.ui.component.Selector

valueTypeEvaluator

Fields inherited from class javax.faces.component.UIInput

COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID

Constructor Summary
`RadioButtonBase()` Construct a new `RadioButtonBase`.

Method Summary
`java.lang.String`	`getFamily()` Return the family for this component.
`int`	`getLabelLevel()` Sets the style level for the generated label, provided the label attribute has been set.
`void`	`restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)` Restore the state of this component.
`java.lang.Object`	`saveState(javax.faces.context.FacesContext _context)` Save the state of this component.
`void`	`setLabelLevel(int labelLevel)` Sets the style level for the generated label, provided the label attribute has been set.

Methods inherited from class com.sun.rave.web.ui.component.RbCbSelector

addToRequestMap, createImageComponent, createLabelComponent, encodeBegin, getConvertedValue, getConvertedValue, getImageComponent, getLabelComponent, getSelectedValue, isChecked

Methods inherited from class com.sun.rave.web.ui.component.RbCbSelectorBase

getImageURL, getName, getSelected, getValueBinding, setImageURL, setName, setSelected, setSelectedValue, setValueBinding

Methods inherited from class com.sun.rave.web.ui.component.Selector

compareValues, getRendersChildren, getValueAsReadOnly, isMultiple, setMultiple, toString

Methods inherited from class com.sun.rave.web.ui.component.SelectorBase

getItems, getLabel, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getStyle, getStyleClass, getTabIndex, getToolTip, isDisabled, isReadOnly, isVisible, setDisabled, setItems, setLabel, setOnBlur, setOnChange, setOnClick, setOnDblClick, setOnFocus, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setOnSelect, setReadOnly, setStyle, setStyleClass, setTabIndex, setToolTip, setVisible

Methods inherited from class javax.faces.component.UIInput

addValidator, addValueChangeListener, broadcast, decode, getSubmittedValue, getValidator, getValidators, getValueChangeListener, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, setImmediate, setLocalValueSet, setRequired, setSubmittedValue, setValid, setValidator, setValue, setValueChangeListener, updateModel, validate, validateValue

Methods inherited from class javax.faces.component.UIOutput

getConverter, getLocalValue, getValue, setConverter

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.sun.rave.web.ui.component.SelectorManager

getClientId, getOnChange, getStyle, getStyleClass, getTabIndex, isDisabled, isReadOnly

Methods inherited from interface javax.faces.component.ValueHolder

getConverter, getLocalValue, getValue, setConverter

Constructor Detail