|
Use the ui: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 boolean control
- a string value that is related to the checkbox selection
- an object value defined by the application
A group of checkboxes can be used to represent:
- string values that are related to the checkbox selections
- object values defined by the application
Note: Another tag for rendering checkboxes is
ui: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.
Detecting a selected checkbox
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.
The 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.
Using a 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.
Using a 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. 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 checkbox.
Using a 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.
Facets
The following facets are supported:
- image If the image facet exists, it is rendered to the
immediate right hand side of the checkbox.
- label If the label facet exists, it is rendered to the
immediate right of the image, or to the immediate right of the
checkbox if no image is rendered.
Examples
Example 1: Single boolean checkbox with value binding.
<ui:checkbox id="cb1" selected="#{tldRbCbExample.selectedCb1}"/>
The value binding #{tldRbCbExample.selectedCb1} implies that
there are two methods implemented in the tldRbCbExample
managed bean.
- public void setSelectedCb1(boolean selected)
- public boolean getSelectedCb1()
The getSelectedCb1 method will be called to determine the checked
state of the checkbox during rendering.
When the tag is first rendered, its initial checked state is
determined by the return value of getSelectedCb1. If it returns
true the checkbox will be checked on the HTML page and
not checked if it returns false
When the checkbox is checked by the user the 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.
Example 2: Single boolean checkbox with value binding,
that displays an image and a label.
<ui: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.
Example 3: Single String valued checkbox with value binding.
<ui: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:
- public void setSelectedCb3(String selected)
- public String getSelectedCb3()
The getSelectedCb3 method will be called to determine the
checked state of the checkbox during rendering.
When the tag is first rendered, its initial checked state is determined by
the return value of 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.
When the checkbox is checked by the user the 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.
Example 4: Single Object valued checkbox with value bindings and a label.
<ui: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. Let's say
the object value is an instance of the "Printer" class, then the expected
method signatures will be:
- public void setSelectedCb4(Printer selected)
- public Printer getSelectedCb4()
- public void setSelectedValueCb4(Printer selected)
- public Printer getSelectedValueCb4()
A Printer class might look like:
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();.
The converter class might look like:
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()) 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.
Example 5: Grouped Integer valued checkboxes in a table.
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.
<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="cb5"/>
</f:facet>
<ui:checkbox id="cb5" name="cb5Grp"
selectedValue="#{tldRbCbExample.currentRow1}">
</ui:checkbox>
</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 checkboxes 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 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());
}
}
}
Example 6: Grouped boolean checkboxes in a table, using value bindings to
maintain the state.
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.
<ui:checkbox id="cb6" selected="#{table6data.selected}">
</ui: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.
HTML Elements and Layout
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:
- a <span> element
- an <input> element of type checkbox
- an optional image, if the
imageURL
attribute or an image facet is specified. If the
imageURL is specified and no image facet exists
a com.sun.rave.web.ui.component.ImageComponent is created
and rendered. If an image facet is specified then the
component specified by the facet is rendered.
- an optional label, if the
label
attribute or a label facet is specified. If the
label attribute is specified and no label facet exists
a com.sun.rave.web.ui.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.
- cid_span for the <span> element
- cid for the <input> element
- cid_image for the image component if created.
- cid_label for the label component if created.
Client Side Javascript Functions
- checkbox_setChecked(elementId, checked): Set the
checked property for a checkbox with the given element id,
elementId.
If checked is true, the checkbox is checked.
If checked is false, the checkbox is unchecked.
Auto-generated component class.
Do NOT modify; all changes
will be lost!
| 