webuijsf
Tag checkbox


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.

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. 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.

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:

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:

The ID attributes for HTML elements and components are constructed as follows, where cid is the clientId of the component being rendered.

Theme Identifiers

Client Side Javascript Functions

When the component is rendered, a DOM object corresponding to the component is created. To manipulate the component on the client side, you may invoke functions on the DOM object. With reference to the DOM ID, to disable the component, invoke 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.
  • [optional] execute: Comma separated string containing a list of client IDs against which the execute portion of the request processing lifecycle must be run. If omitted, no other components are executed.
setProps(props) Use this function to change any of the following supported properties:
  • accesskey
  • align
  • checked
  • className
  • dir
  • disabled
  • id
  • image
  • label
  • lang
  • name
  • onBlur
  • onChange
  • onClick
  • onFocus
  • onKeyDown
  • onKeyPress
  • onKeyUp
  • onMouseDown
  • onMouseMove
  • onMouseOut
  • onMouseOver
  • onMouseUp
  • onSelect
  • readOnly
  • style
  • tabIndex
  • title
  • value
  • visible
submit(execute)
Use this function to asynchronously submit the component.
  • [optional] execute: Comma separated string containing a list of client IDs against which the execute portion of the request processing lifecycle must be run. If omitted, the component on which the function has been invoked, is submitted.

Client Side JavaScript Events

When the component is manipulated client side, some functions may publish event topics for custom AJAX implementations to listen for. Using the Dojo event system, listen for the refresh event topic using:

<webuijsf:script>
    var processEvents = {                       
        update: function(props) {
            // Do something...
        }
    }

    // Subscribe to refresh event.
    dojo.subscribe(webui.suntheme.widget.checkbox.event.<eventname>.endTopic, processEvents, "update");


</webuijsf:script>

The following events are supported.
 
webui.suntheme.widget.checkbox.event.refresh.beginTopic Event topic is published before asynchronously refreshing the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client ID to process the event for
webui.suntheme.widget.checkbox.event.refresh.endTopic Event topic is published after asynchronously refreshing the component. Supported properties include: See setProps() function.
  • props - JSON object containing properties of the component. See setProps() function for details on properties and their usage
webui.suntheme.widget.checkbox.event.submit.beginTopic Event topic published before asynchronously submitting the component. Supported properties include:
  • [optional] execute - list of the components to be executed along with this component
  • id - The client ID to process the event for
webui.suntheme.widget.checkbox.event.submit.endTopic

Event topic published after asynchronously submitting the component. Supported properties include:

  • props - JSON object containing messages (if any) raised by the server.In particular, valdiation messages will be present here if validation failed

Code Examples

Example 1: Single boolean checkbox with value binding

<webuijsf:checkbox id="cb1" selected="#{tldRbCbExample.selectedCb1}"/>

The value binding #{tldRbCbExample.selectedCb1} implies that there are two methods implemented in the tldRbCbExample managed bean.

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

<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.

Example 3: Single String valued checkbox with value binding

<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:

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

<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:

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()), 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.

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.

     <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());
}
}
}

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.

<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.

Example 7: Update checkbox on the client side using the getProps and setProps functions

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>

Example 8: Asynchronously update a checkbox using the refresh function

This example shows how to asynchronously update a checkbox using the refresh function. When the user clicks the button, the checkbox is asynchronously updated with new data.
<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.

Example 9: Asynchronously update checkbox using refresh function

This example shows how to asynchronously update a checkbox using the refresh function. The execute property of the refresh function is used to define the client ID which is to be submitted and updated on the server-side. As the user types in the text field, the input value is updated on the server-side and the checkbox label is updated on the client-side -- all without a page refresh.
<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 Classcom.sun.webui.jsf.component.CheckboxTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
bindingfalsefalsejava.lang.String A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children.
htmlTemplatefalsefalsejava.lang.String

Alternative HTML template to be used by the Checkbox component.

labelLevelfalsefalsejava.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.

onDblClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse double-click occurs over this component.

imageURLfalsefalsejava.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 image facet instead of the imageURL attribute.

onKeyPressfalsefalsejava.lang.String

Scripting code that is executed when the user presses and releases a key while the component has the focus.

onSelectfalsefalsejava.lang.String

Scripting code that is executed when some text in this component value is selected.

onFocusfalsefalsejava.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.

renderedfalsefalsejava.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.
idfalsetruejava.lang.StringNo Description
onKeyUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a key while the component has the focus.

onMouseUpfalsefalsejava.lang.String

Scripting code that is executed when the user releases a mouse button while the mouse pointer is on the component.

styleClassfalsefalsejava.lang.String

CSS style class or classes to be applied to the outermost HTML element when this component is rendered.

stylefalsefalsejava.lang.String

CSS style or styles that are applied to the outermost HTML element when the component is rendered.

onClickfalsefalsejava.lang.String

Scripting code that is executed when a mouse click occurs over the component.

namefalsefalsejava.lang.String

Identifies the control as participating as part of a group. The RadioButton and Checkbox classes determine the behavior of the group, that are assigned the same value to the name property. The value of this property must be unique for components in the group, within the scope of the Form parent component containing the grouped components.

onBlurfalsefalsejava.lang.String

Scripting code that is executed when this element loses the focus.

onMouseDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses a mouse button while the mouse pointer is on the component.

toolTipfalsefalsejava.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.

converterfalsefalsejava.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:
  • A JavaServer Faces EL expression that resolves to a backing bean or bean property that implements the javax.faces.converter.Converter interface; or
  • the ID of a registered converter (a String).
disabledfalsefalsejava.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.

validatorExpressionfalsefalsejava.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:
  • a javax.faces.context.FacesContext
  • a javax.faces.component.UIComponent (the component whose data is to be validated)
  • a java.lang.Object containing the data to be validated.

The backing bean where the method is defined must implement java.io.Serializable or javax.faces.component.StateHolder.

The method is invoked during the Process Validations Phase.

selectedValuefalsefalsejava.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.
onMouseOutfalsefalsejava.lang.String

Scripting code that is executed when a mouse out movement occurs over this component.

onMouseOverfalsefalsejava.lang.String

Scripting code that is executed when the user moves the mouse pointer into the boundary of this component.

onMouseMovefalsefalsejava.lang.String

Scripting code executed when the user moves the mouse pointer while over the component.

selectedfalsefalsejava.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.

immediatefalsefalsejava.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.
labelfalsefalsejava.lang.String

If set, a label is rendered adjacent to the component with the value of this attribute as the label text.

onChangefalsefalsejava.lang.String

Scripting code executed when the element value of this component is changed.

visiblefalsefalsejava.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.

onKeyDownfalsefalsejava.lang.String

Scripting code that is executed when the user presses down on a key while the component has the focus.

readOnlyfalsefalsejava.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
valueChangeListenerExpressionfalsefalsejava.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.
tabIndexfalsefalsejava.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.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.