| |||||||
FRAMES NO FRAMES |
Use the webuijsf: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.
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:
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 webuijsf: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.
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.
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.
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.
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.
The following facets are supported:
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:
imageURL
attribute or an image
facet is specified. If the imageURL
attribute is
specified a com.sun.webui.jsf.component.ImageComponent
component is created and rendered. If an image
facet is
specified then the component specified by the facet is rendered.label
attribute or a label
facet is specified. If the label
attribute is specified a
com.sun.webui.jsf.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.
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.
document.getElementById(id).setProps({disabled:
true})
.getInputElement() |
Use this function to access the HTML <input>
element that is rendered by the component. |
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.
|
setProps(props) |
Use this function to change any of the following supported
properties:
|
submit(execute) |
Use this function to
asynchronously submit the component.
|
subscribe(topic, obj, func) |
Use this function to subscribe
to an event topic.
|
When the component is manipulated client side, some functions may
publish event topics for custom AJAX implementations to listen for.
For example, you can listen for the refresh event topic using:
<webuijsf:script>
var processEvents =
{
update: function(props) {
//
Do something...
}
}
// Subscribe to refresh event.
var domNode = document.getElementById("form1:test1");
domNode.subscribe(domNode.event.refresh.endTopic,
processEvents, "update");
</webuijsf:script>
The following events are supported.
<Node>.event.refresh.beginTopic | Event topic published before asynchronously refreshing the
component. Supported properties include:
|
<Node>.event.refresh.endTopic | Event topic published after asynchronously refreshing the
component. Supported properties include: See setProps() function.
|
<Node>.event.submit.beginTopic | Event topic published before asynchronously submitting the
component. Supported properties include:
|
<Node>.event.submit.endTopic |
Event topic published after asynchronously submitting the component. Supported properties include:
|
<webuijsf:radioButton id="rb0" name="rb1grp"
selected="#{tldRbCbExample.selectedRb0}"/>
<br/>
<webuijsf: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.
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, only one
of which should return true. The radio button whose "getSelected"
method returns true
will be checked in the HTML page and
not checked if it returns false
. When one of the radio
buttons is checked by the user its "setSelected" method will be called
with a boolean
argument equal to true
. The
other radio button's "setSelected" method will be called with a boolean
argument equal to false
.
No image or label will be displayed by this example.
<webuijsf:radioButton id="rb2" name="rb2grp"
imageURL="tree_server.gif" label="Server"
selected="#{tldRbCbExample.selectedRb2}"/>
<br/>
<webuijsf: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.
<webuijsf:radioButton id="rb4" name="rb3grp" label="Print"
selectedValue="Print" selected="#{tldRbCbExample.selectedRb4}"/>
<br/>
<webuijsf: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:
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 a String
valued radio button, a radio button will be
checked only if the "getSelected" method returns the value of its selectedValue
attribute.
For example if getSelectedRb4
returns "Print", the radio
button "rb4" will be checked. getSelectedRb5
must not
return "Fax" and should return null
in order for "rb4" to
remain checked.
Alternatively if getSelectedRb4
returns null
getSelectedRb5
should return "Fax", and radio button "rb5"
will be checked.
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.
<webuijsf:radioButton id="rb6" name="rb4grp" label="Print"
selectedValue="#{tldRbCbExample.selectedValueRb6}"
selected="#{tldRbCbExample.selectedRb6}"
converter="#{tldRbCbExample.rbConverter}"/>
<br/>
<webuijsf: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 class Printer implements Device {A Fax class might look like:
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;
}
};
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();
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);
}
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.
<webuijsf:table id="table5">
<webuijsf:tableRow id="table5row1"
sourceData="#{tldRbCbExample.table5row1data}"
sourceVar="table5data"
binding="#{tldRbCbExample.table5row1}">
<webuijsf:tableColumn id="col1">
<f:facet name="header">
<webuijsf:tableHeader id="header1"
deselectAllButton="true"
selectAllButton="true"
selectId="rb5"/>
</f:facet>
<webuijsf:radioButton id="rb8" name="rb5grp"
selectedValue="#{tldRbCbExample.currentRow1}">
</webuijsf:radioButton>
</webuijsf:tableColumn>
<webuijsf:tableColumn id="col2">
<f:facet name="header">
<webuijsf:staticText text="Application Data"/>
</f:facet>
<webuijsf:staticText text="#{table5data.text}"/>
</webuijsf:tableColumn>
</webuijsf:tableRow>
<f:facet name="tableActionsBottom">
<webuijsf:button id="table5process"
action="#{tldRbCbExample.table5process}"
text="Process Checked"/>
</f:facet>
</webuijsf:table>
See webuijsf:table for
details on using the <webuijsf:table>
tag and other
table child tags and facets.
Normally when radio buttons are contained within a webuijsf: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());
}
}
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 "webuijsf:radioButton" code in the previous example.
<webuijsf:radioButton id="rb6" name="rb6grp"
selected="#{table6data.selected}"> </webuijsf:radioButton>
The value binding #{table6data.selected}
references a
boolean member in the row data for storing and retrieving the radio
button state.
This example shows how to toggle the disabled state of a radio button client side using the getProps and setProps functions.
<webuijsf:radioButton id="rb1" name="rb1" label="My Radio Button"/>
<webuijsf:button id="button1" text="Toggle Radio Button Disabled" onClick="toggleDisabled(); return false"/>
<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:rb1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>
<webuijsf:radioButton id="rb1" name="rb1" label="#{MyBean.label}"/>
<webuijsf:button id="button1" text="Refresh Radio Button" onClick="refreshRadioButton(); return false;"/>
<webuijsf:script>
function refreshRadioButton() {
var domNode =
document.getElementById("form1:rb1"); // Get radio button
return domNode.refresh(); //
Asynchronously refresh button
}
</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.<webuijsf:radioButton id="rb1" name="rb1" label="#{MyBean.label}"/>
<webuijsf:textField id="field1" text="#{MyBean.label}" label="Change Radio Button Label"
onKeyPress="setTimeout('refreshRadioButton();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
function
refreshRadioButton
()
{
var domNode =
document.getElementById("form1:rb1"); // Get radio button
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 Class | com.sun.webui.jsf.component.RadioButtonTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.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. |
htmlTemplate | false | false | java.lang.String | Alternative HTML template to be used by this component. |
labelLevel | false | false | java.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 3. |
onDblClick | false | false | java.lang.String | Scripting code that is executed when a mouse double-click occurs over this component. |
imageURL | false | false | java.lang.String |
A context relative path of an image to be displayed with
the control. If you want to be able to specify attributes
for the image, specify an |
onKeyPress | false | false | java.lang.String | Scripting code that is executed when the user presses and releases a key while the component has the focus. |
onFocus | false | false | java.lang.String | Scripting code that is executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse. |
rendered | false | false | java.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. |
id | false | true | java.lang.String | No Description |
onKeyUp | false | false | java.lang.String | Scripting code that is executed when the user releases a key while the component has the focus. |
onMouseUp | false | false | java.lang.String | Scripting code that is executed when the user releases a mouse button while the mouse pointer is on the component. |
styleClass | false | false | java.lang.String | CSS style class or classes to be applied to the outermost HTML element when this component is rendered. |
style | false | false | java.lang.String | CSS style or styles that are applied to the outermost HTML element when the component is rendered. |
onClick | false | false | java.lang.String | Scripting code that is executed when a mouse click occurs over the component. |
name | false | false | java.lang.String |
Identifies the control as participating as part
of a group. The |
onBlur | false | false | java.lang.String | Scripting code that is executed when this element loses the focus. |
onMouseDown | false | false | java.lang.String | Scripting code that is executed when the user presses a mouse button while the mouse pointer is on the component. |
toolTip | false | false | java.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. |
converter | false | false | java.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:
|
disabled | false | false | java.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. |
validatorExpression | false | false | java.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:
The backing bean where the method is defined must implement
The method is invoked during the Process Validations Phase. |
selectedValue | false | false | java.lang.String | Return the value of the selectedValue property.
If selectedValue is null, then a Boolean
true instance is returned and the control will behave as a
boolean control.
|
onMouseOut | false | false | java.lang.String | Scripting code that is executed when a mouse out movement occurs over this component. |
onMouseOver | false | false | java.lang.String | Scripting code that is executed when the user moves the mouse pointer into the boundary of this component. |
onMouseMove | false | false | java.lang.String | Scripting code executed when the user moves the mouse pointer while over the component. |
selected | false | false | java.lang.String | The object that represents the selections made from the available options. If multiple selections are allowed, this must be bound to ArrayList, an Object array, or an array of primitives. |
immediate | false | false | java.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. |
label | false | false | java.lang.String | If set, a label is rendered adjacent to the component with the value of this attribute as the label text. |
onChange | false | false | java.lang.String | Scripting code executed when the element value of this component is changed. |
visible | false | false | java.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. |
onKeyDown | false | false | java.lang.String | Scripting code that is executed when the user presses down on a key while the component has the focus. |
readOnly | false | false | java.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 |
valueChangeListenerExpression | false | false | java.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 .
|
tabIndex | false | false | java.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. |
| |||||||
FRAMES NO FRAMES |