| |||||||
FRAMES NO FRAMES |
Use the webuijsf:checkboxGroup
tag to display two or
more check boxes in a grid layout in the rendered HTML page. The webuijsf:checkboxGroup
tag attributes that you specify determine how the checkboxes are
displayed.
If the label
attribute is specified a com.sun.webui.jsf.component.Label
component is rendered before the first checkbox and identifies the
checkbox group. The label component's for
attribute is
set to the id
attribute of the first checkbox in the
rendered HTML page.
The checkboxes are laid out in rows and columns in an HTML <table> element. The number of rows is defined by the length of the items array. The number of columns is defined by the columns attribute. The default layout is a single vertical column.
The items
attribute must be a value binding
expression. The value binding expression assigned to the items
property evaluates to an Object
array of com.sun.webui.jsf.model.Option
instances. Each instance represents one checkbox. The value
property of an Option
instance represents the value of a
selected checkbox. If the items
array is empty nothing is
rendered.
Zero or more check boxes may be selected. The selected
attribute must also be a value binding expression that is evaluated to
read and write an Object
array. When an array is read
from the value binding expression, it identifies the selected
checkboxes. Each element in the array is an Object
value.
Each Object
value must be equal to the value property of
at least one Option
instance specified in the array
obtained from the value binding expression assigned to the items
attribute.
The write method of the selected
attribute's value
binding expression is called during the UPDATE_MODEL_PHASE
of the JSF lifecyle. If one or more checkboxes are selected an Object
array is passed as an argument to the write method. This array contains
the Object
values of the selected checkboxes.
A webuijsf:checkboxGroup
renders one com.sun.webui.jsf.component.Checkbox
component for each element in the items
array. See webuijsf:checkbox for
details on the HTML elements and components rendered for a checkbox.
The value of the name
attribute of each Checkbox
component rendered is assigned the clientId
of the CheckboxGroup
component instance associated with this tag. The
id
attribute of each Checkbox
component rendered is formed
as follows, where cbgrpid is the ID of the CheckboxGroup
instance and N is the nth checkbox.
See webuijsf:checkbox for details on how the ID properties of the components that comprise checkbox are defined.
checkboxGroup
. document.getElementById(id).setProps({disabled:
true})
.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:
|
When the component is manipulated client-side, some functions might
publish event topics for custom Ajax implementations to listen for.
Using the Dojo event system, you can instruct Ajax to listen for the refresh event topic bye using:
<webuijsf:script>
var processEvents =
{
update: function(props) {
//
Do something...
}
}
// Subscribe to refresh event.
dojo.subscribe(webui.suntheme.widget.rbcbGroup.event.<eventname>.endTopic,
processEvents, "update");
</webuijsf:script>
webui.suntheme.widget.rbcbGroup.event.refresh.beginTopic | Event topic is published before asynchronously refreshing the
component. Supported properties include:
|
webui.suntheme.widget.rbcbGroup.event.refresh.endTopic | Event topic is published after asynchronously refreshing the
component. Supported properties include: See setProps() function.
|
<webuijsf:checkboxGroup
items="#{rbcbGrp.selections}"
label="#{rbcbGrp.cbGrpLabel}"
toolTip="cbgrp-tooltip"
disabled="false"
tabIndex="4"
selected="#{rbcbGrp.cbvalue}">
</webuijsf:checkboxGroup>
This example creates a checkbox group with an identifying label for
the group before the first checkbox. The data for the checkboxes is
obtained from the value binding expression #{rbcbGrp.selections}
.
rbcbGrp
is an application defined managed bean and
provides the values for other attributes such as selected
to receive the value of the selected checkboxes in the group.
This example shows how to toggle the disabled state of a checkboxGroup client-side using the getProps and setProps functions.
<webuijsf:checkboxGroup id="cb1" name="cb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:button id="button1" text="Toggle CheckboxGroup Disabled" onClick="toggleDisabled(); return false"/>
<webuijsf:script>
function toggleDisabled() {
var domNode = document.getElementById("form1:cb1");
domNode.setProps({ disabled: !domNode.getProps().disabled });
}
</webuijsf:script>
<webuijsf:checkboxGroup id="cb1" name="cb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:button id="button1" text="Refresh CheckboxGroup" onClick="refreshGroup(); return false;"/>
<webuijsf:script>
function refreshGroup() {
var domNode =
document.getElementById("form1:cb1"); // Get checkboxGroup
return domNode.refresh(); //
Asynchronously refresh checkboxGroup
}
</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 that have been set
server-side, but not updated.<webuijsf:checkboxGroup id="cb1" name="cb1" items="#{rbcbGrp.selections}" selected="#{rbcbGrp.cbvalue}" label="#{rbcbGrp.cbGrpLabel}"/>
<webuijsf:textField id="field1" text="#{rbcbGrp.cbGrpLabel}" label="Change CheckboxGroup Label"
onKeyPress="setTimeout('refreshCheckboxGroup();', 0);"/> // Field used to asynchronously update label.
<webuijsf:script>
function
refreshCheckboxGroup
()
{
var domNode =
document.getElementById("form1:cb1"); // Get checkboxGroup
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.CheckboxGroupTag |
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. |
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. |
columns | false | false | java.lang.String | Defines how many columns may be used to lay out the check boxes. The value must be greater than or equal to one. The default value is one. Invalid values are ignored and the value is set to one. |
onDblClick | false | false | java.lang.String | Scripting code that is executed when a mouse double-click occurs over this component. |
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. |
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. |
items | false | false | java.lang.String | Specifies the options that the web application user can choose
from. The value must be one of an array, Map or Collection
whose members are all subclasses of |
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. |
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. |
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. |
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:
|
required | false | false | java.lang.String | Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error. |
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. |
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 an Object array, or an array of primitives. |
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. |
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. |
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. |
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 2. |
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 |