| |||||||
FRAMES NO FRAMES |
Use the webuijsf:checkbox
tag to display a checkbox
in the rendered HTML page. The tag can be used as a single checkbox or
as one checkbox among a group of checkboxes. A group of checkboxes
represents a multiple selection list which can have any number of
checkboxes selected, or none selected. A checkbox 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 checkbox 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 values for checkbox selections made in the
interface. An application defined Object
value or class
instance can be used to hold more information related to a checkbox
selection.
A single checkbox can be used to represent several types of data:
A group of checkboxes can be used to represent:
Note: Another tag for rendering checkboxes is webuijsf:checkboxGroup
,
which imposes a grid layout on a group of checkboxes. The checkbox
tag is useful in situations where the checkboxGroup
tag
layout is not desirable, such as in a table row.
The checkbox
tag uses both the selected
and selectedValue
attributes to pass information about
the checkbox's selection status. The selected
attribute
is used to indicate that the checkbox is selected, and should have a
check mark displayed in the page. The selectedValue
attribute is used to pass a data value for the checkbox. A checkbox 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 checkbox 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 checkbox behaves like a
boolean control. If the checkbox is selected, the value of the selected
attribute is a true Boolean
instance. If the checkbox 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 value can be assigned to the selected
and selectedValue
attributes.
When checkboxes are part of a group, an ArrayList
of
selected checkboxes is maintained. If any checkboxes within a group are
selected, a request attribute whose name is the value of the name
attribute is created and added to the RequestMap
. The
request attribute value is an ArrayList
containing the
value of the selectedValue
attribute of each selected
checkbox. If no checkboxes are selected, no request attribute is
created. The selected
attribute of each selected checkbox
within the group will also contain the value of the selectedValue
attribute of the respective selected checkbox.
Checkbox
class provides a convenience method for
obtaining the selected checkboxes in a group:
public static ArrayList 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 an ArrayList of
class instances and not primitive values.
checkbox
tag as a boolean control If the selectedValue
attribute is not specified or
its value is null
then the checkbox behaves like a
boolean control.
To use the checkbox
tag as a boolean control, do not
specify a value for the selectedValue
attribute. The
checkbox is selected if the selected
attribute is not
null and has the value of a true Boolean
instance or a boolean
primitive value. If the checkbox 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
checkbox is behaving as a boolean control the value of the
<input> element is the clientId
of the checkbox.
Note that using a boolean checkbox in a group and referencing
the request attribute for the selected checkboxes is not useful, since
the value of the request attribute will be an ArrayList
of indistinguishable true
values.
checkbox
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
checkbox. If the checkbox 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 checkbox value as the value of the HTML <input>
element and to decode the submitted value in a request. The
object must also 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 checkbox.
checkbox
tag as one control in a group The name
attribute determines whether a checkbox is
part of a group. A checkbox is treated as part of a group of checkboxes
if the name
attribute of the checkbox is assigned a value
equal to the name
attribute of the other checkboxes in
the group. In other words, all checkboxes of a group have the same name
attribute value. The group behaves like a multiple selection list,
where zero or more checkboxes can be selected. The value of the name
attribute must be unique within the scope of the <form> element
containing the checkboxes.
The following facets are supported:
A checkbox
is rendered as at least one HTML
<span> element and one <input> element of type checkbox.
Each checkbox may consist of the following elements and components:
imageURL
attribute or an image
facet is specified. If the imageURL
is specified and no
image facet exists, then a com.sun.webui.jsf.component.ImageComponent
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
and no label facet exists, then a com.sun.webui.jsf.component.Label
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 and components are constructed
as follows, where cid is the clientId
of the
component being rendered.
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>
<Node>.event.refresh.beginTopic | Event topic is published before asynchronously refreshing the
component. Supported properties include:
|
<Node>.event.refresh.endTopic | Event topic is 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:checkbox id="cb1"
selected="#{tldRbCbExample.selectedCb1}"/>
The value binding #{tldRbCbExample.selectedCb1}
implies that there are two methods implemented in the tldRbCbExample
managed bean.
getSelectedCb1
method will be called to determine the
checked state of the checkbox during rendering.getSelectedCb1
. If it returns true
the checkbox will be checked on the HTML page and not checked if it
returns false
setSelectedCb1
method will be called with a boolean
argument equal to true
.
When it is unchecked the method will be called with a boolean
argument equal to false
.No image or label will be displayed by this example.
<webuijsf:checkbox id="cb2"
selected="#{tldRbCbExample.selectedCb2}" imageURL="tree_server.gif
label="Server"/>
The behavior of this checkbox is the same as example one.
In this example an image and a label are displayed next to the
checkbox. Both the imageURL
and label
attributes may be assigned value binding expressions instead of literal
values.
<webuijsf:checkbox id="cb3" label="Printer"
selectedValue="Printer" selected="#{tldRbCbExample.selectedCb3}"/>
The value binding #{tldRbCbExample.selectedCb3}
implies that there are two methods implemented in the tldRbCbExample
managed bean. Because the selectedValue
attribute is a String
the expected method signatures will be:
getSelectedCb3
method will be called to determine the
checked state of the checkbox during rendering.getSelectedCb3
. With a String
valued checkbox, this checkbox will be checked only if the getSelectedCb3
method returns "Printer", since that is the value of the checkbox as
dictated by the selectedValue="Printer"
attribute. If the
getSelectedCb3
method returns anything else, the checkbox
will not be checked.setSelectedCb3
method will be called with a String
argument equal to
"Printer". When it is unchecked the method will be called with a null String
argument.
<webuijsf:checkbox id="cb4" label="Printer"
selectedValue="#{tldRbCbExample.selectedValueCb4}"
selected="#{tldRbCbExample.selectedCb4}"
converter="#{tldRbCbExample.printerConverter}"/>
The value bindings #{tldRbCbExample.selectedCb4}
and #{tldRbCbExample.selectedValueCb4}
imply the following methods are implemented in the tldRbCbExample
managed bean. If the object value is an instance of the
"Printer" class, then the expected method signatures will be:
public static class Printer {
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 boolean equals(Printer p) {
return this.name.equals(p.getName()) &&
this.location.equals(p.getLocation());
}
};
Since this is an application defined object value, the application
must supply a converter, as indicated in the example. The converter
attribute's value binding expression implies a method in the tldRbCbExample
managed bean called
public Converter getPrinterConverter();
.
public class PrinterConverter implements javax.faces.convert.Converter {
public PrinterConverter() {
}
public String getAsString(FacesContext context,
UIComponent component, Object value) {
if (!(value instanceof Printer)) {
throw new ConverterException("Not a Printer value");
}
return ((Printer)value).getName();
}
public Object getAsObject(FacesContext context,
UIComponent component, String value) {
if (!value.equals("printer1")) {
throw new ConverterException("Unrecognized printer: " + value);
}
return printerDb.getPrinter("printer1");
}
};
The getSelectedCb4
method will be called to determine
the checked state of the checkbox during rendering.
When the tag is first rendered, its initial state is determined by the
return value of getSelectedCb4
. With an Object
valued checkbox, this checkbox will be checked only if the getSelectedCb4
method returns a Printer instance that equals the Printer instance
returned by the getSelectedValueCb4
method.
If the getSelectedCb4
method returns a Printer instance
that is not equal as determined by getSelectedValueCb4().equals(getSelectedCb4())
, then
the checkbox will not be checked.
When the checkbox is checked by the user the setSelectedCb4
method will be called with the Printer instance returned by the
converter.
The following example shows a common use case for checkboxes in a
table. The checkboxes are used to select zero or more rows for
processing. The checkbox state does not need to be stored. The selected
row indexes can be obtained directly as Integer
values
from the ArrayList
of selected checkboxes maintained by
the checkbox in the action callback #{tldRbCbExample.table5process}
.
The markup in bold is how you would specify a checkbox tag for this
purpose. The selectedValue
value binding, #{tldRbCbExample.currentRow1}
is implemented to return the current row in the table5row1
tableRow tag.
<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="cb5"/>
</f:facet>
<webuijsf:checkbox id="cb5" name="cb5Grp"
selectedValue="#{tldRbCbExample.currentRow1}">
</webuijsf:checkbox>
</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 checkboxes 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
checkbox 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 the rows just need to be selected for processing. Once the
processing is complete, the checkbox no longer needs to be checked.
The following code shows how the table5process
action
method obtains the selected checkbox values from the request map. It
calls a static member on Checkbox
to return the ArrayList
public static ArrayList getSelected(String groupName)
public void table5process() {
// Checkbox.getSelected(String groupName) is
// a static convenience method that obtains the
// ArrayList of selected checkboxes from the request map
// ONLY when the checkboxes are part of a group.
//
ArrayList al = Checkbox.getSelected("cb5Grp");
if (al != null) {
ListIterator li = al.listIterator();
while (li.hasNext()) {
processRow(((Integer)li.next()).intValue());
}
}
}
This example is similar to Example 5, but it maintains the state of checkboxes across requests, by specifying a value binding for the selected attribute. A simple way to store the checkbox state is to store the state with the row data.
<webuijsf:checkbox id="cb6"
selected="#{table6data.selected}"> </webuijsf:checkbox>
The value binding
#{table6data.selected}
references a
boolean member in the row data for storing and retrieving the checkbox
state. Notice also that it is not necessary to group the checkboxes by
specifying a value for the name
attribute. It is not
useful to specify boolean checkboxes in a group, in order to obtain the
list of selected checkboxes from the request map. The list will consist
of indistinguishable true
values; one for each selected
checkbox. This example shows how to toggle the disabled state of a checkbox client side using the getProps and setProps functions.
<webuijsf:checkbox id="cb1" name="cb1" label="My Checkbox"/>
<webuijsf:button id="button1" text="Toggle Checkbox Disabled" onClick="toggleDisabled(); return false"/>
<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:cb1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>
<webuijsf:checkbox id="cb1" name="cb1" label="#{MyBean.label}"/>
<webuijsf:button id="button1" text="Refresh Checkbox" onClick="refreshCheckbox(); return false;"/>
<webuijsf:script>
function refreshCheckbox() {
var domNode =
document.getElementById("form1:cb1"); // Get checkbox
return domNode.refresh(); //
Asynchronously refresh checkbox
}
</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:checkbox id="cb1" name="cb1" label="#{MyBean.label}"/>
<webuijsf:textField id="field1" text="#{MyBean.label}" label="Change Radio Button Label"
onKeyPress="setTimeout('refreshCheckbox();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
function
refreshcheckbox
()
{
var domNode =
document.getElementById("form1:cb1"); // Get radio checkbox
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 on the server-side: refresh("form1:id1,form2:id2,...")Tag Information | |
Tag Class | com.sun.webui.jsf.component.CheckboxTag |
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 the Checkbox 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. |
onSelect | false | false | java.lang.String | Scripting code that is executed when some text in this component value is selected. |
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 |