NetUI Tag Library Documentation (Version 1.0.1)

netui
netui:checkBoxGroup Tag

Renders a collection of checkbox options as <input type="checkbox"> and handles the data binding.

Syntax

<netui:checkBoxGroup
    dataSource="string_dataSource"
    [defaultValue="string_or_expression_default"]
    [disabled="boolean_disabled"]
    [labelStyle="string_labelStyle"]
    [labelStyleClass="string_labelStyleClass"]
    [optionsDataSource="expression_optionsDataSource"]
    [orientation="string_orientation"]
    [repeater="boolean_repeater"]
    [style="string_style"]
    [styleClass="string_styleClass"] >
    ... JSP content ...
</netui:checkBoxGroup>

Description

Renders a collection of checkbox options as <input type="checkbox"> and handles the data binding.

Submitting Data

The <netui:checkBoxGroup> submits data in the form of a String[] object. For example, if the <netui:checkBoxGroup> submits data to a Form Bean field...

    <netui:checkBoxGroup
            dataSource="actionForm.userSelections"
            optionsDataSource="${pageFlow.availableSelections}" />
...then the Form Bean field must be a String[] object...
    public static class SubmitForm extends FormData
    {
        private String[] userSelections;

        public void setUserSelections(String[] userSelections)
        {
            this.userSelections = userSelections;
        }

        public String[] getUserSelections()
        {
            return this.userSelections;
        }
    }

Dynamically Defined Checkboxes

You can dynamically define a set of checkboxes by pointing the optionsDataSource attribute at a String[] object. When the <netui:checkBoxGroup> is rendered in the browser, a corresponding set of checkboxes will be genereated from the String[] object.

For example, if you define a String[] object and get method in the Controller file...

    public String[] availableOptions = {"option1", "option2", "option3"};

    public String[] getAvailableOptions()
    {
        return this.availableOptions;
    }
...and reference this String[] from the optionsDataSource attribute...
    <netui:checkBoxGroup
            dataSource="actionForm.userSelections"
            optionsDataSource="${pageFlow.availableSelections}" />
...then the appropriate checkboxes will be rendered in the browser.
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.userSelections}" value="option1">option1</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.userSelections}" value="option2">option2</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.userSelections}" value="option3">option3</input>
For checkboxes to be rendered, either the optionsDataSource attribute must be provided (and point to a String[] object) or the <netui:checkBoxGroup> must have children <netuiCheckBoxOption> tags.

Setting Default Options

The defaultValue attribute can be used to determine which checkboxs are checked when they are first rendered in the browser. The defaultValue attribute should point to a String, if only one checkbox should appear checked, or to a String[] object, if multiple checkboxes should appear checked.

Attributes
dataSource
Required: Yes  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: No

An expression to be evaluated. It determines the source of populating data for the tag
defaultValue
Required: No  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: Yes

The String literal or expression to be used as the default value.
disabled
Required: No  |   Type: boolean  |   Supports runtime evaluation / JSP Expression Language: Yes

Set the disable state either with the literal "true" or "false" or with an expression.
labelStyle
Required: No  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: Yes

Set the label style for each contained CheckBoxOption.
labelStyleClass
Required: No  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: Yes

Set the label style class for each contained CheckBoxOption.
optionsDataSource
Required: No  |   Type: Object  |   Supports runtime evaluation / JSP Expression Language: Yes

Sets the options datasource value (an expression).
orientation
Required: No  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: Yes

Set the orientation of the resulting options group.
repeater
Required: No  |   Type: boolean  |   Supports runtime evaluation / JSP Expression Language: Yes

Set whether repeating of contained options is on.
style
Required: No  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: Yes

Specifies style information for the current element.
styleClass
Required: No  |   Type: String  |   Supports runtime evaluation / JSP Expression Language: Yes

The style class (a style sheet selector).

Example

In this first sample, the <netui:checkBoxGroup> submits data to the Form Bean field preferredColors.

    <netui:checkBoxGroup
            dataSource="actionForm.preferredColors"
            optionsDataSource="${pageFlow.colors}" />
The optionsDataSource attribute points to a get method for a String[] on the Controller file:
    String[] colors = new String[] {"Red", "Blue", "Green", "Yellow", "White", "Black"};

    public String[] getColors()
    {
        return colors;
    }
This automatically renders the appropriate set of checkbox options within the <checkBoxGroup>:
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Red">Red</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Blue">Blue</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Green">Green</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Yellow">Yellow</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="White">White</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Black">Black</input>
The defaultValue attribute may point to a String or a String[].
    <netui:checkBoxGroup
            dataSource="actionForm.preferredColors"
            optionsDataSource="${pageFlow.colors}"
            defaultValue="${pageFlow.defaultColor}" />
And in the Controller:
    String defaultColor = new String ("Blue");
    ...
or
    String[] defaultColor = new String[] {"Red", "Blue"};
    ...
In either case, the appropriate checkbox options will appear checked in the browser.
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Red" checked="true">Red</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Blue" checked="true">Blue</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Green">Green</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Yellow">Yellow</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="White">White</input>
    <input type="checkbox" name="wlw-checkbox_group_key:{actionForm.preferredColors}" value="Black">Black</input>


Tag Information
Tag Classorg.apache.beehive.netui.tags.html.CheckBoxGroup
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone