|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.CheckboxBase
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 group of checkboxes can be used to represent:
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.
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. 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.
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:
<ui: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.
<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.
<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:
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.
<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 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())
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.
<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());
}
}
}
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.
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
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.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.
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 | |
CheckboxBase()
Construct a new CheckboxBase . |
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 |
public CheckboxBase()
Construct a new CheckboxBase
.
Method Detail |
public java.lang.String getFamily()
Return the family for this component.
getFamily
in class RbCbSelectorBase
public int getLabelLevel()
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.
getLabelLevel
in class Selector
public void setLabelLevel(int labelLevel)
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.
setLabelLevel
in class SelectorBase
getLabelLevel()
public void restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)
Restore the state of this component.
restoreState
in interface javax.faces.component.StateHolder
restoreState
in class RbCbSelectorBase
public java.lang.Object saveState(javax.faces.context.FacesContext _context)
Save the state of this component.
saveState
in interface javax.faces.component.StateHolder
saveState
in class RbCbSelectorBase
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |