Creates a group of check boxes. This is useful if you want
to create a list of options and allow the user to select some of them.
You can configure a checkgroup to allow only one selection, or to
allow any number of selections.
Each check box appears as an empty box
that is filled with a marker, such as a check mark or an X, when selected.
Note that checkgroup items are only valid for XForms
forms. If you are not using XForms, use the check item instead.
Available Options
acclabel, active, bgcolor, border, borderinfo, focused, format, help,
itemlocation, itemnext, itemprevious, label, labelbgcolor, labelborder,
labelfontcolor, labelfontinfo, mouseover, next, previous, printbgcolor,
printlabelbgcolor, printlabelfontcolor, printvisible, readonly, suppresslabel,
value, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid,
xforms:select, xforms:select1
Example
The following code
creates a checkgroup with three choices: US dollars, Canadian dollars,
and Euros. The choices themselves are defined within the xforms:select1
option. Using a checkgroup with xforms:select1 achieves the same
single selection behavior as a radiogroup but with the appearance
of check boxes rather than radio buttons.
<checkgroup sid="currency">
<xforms:select ref="currency" appearance="full">
<xforms:label>Select the currencies you accept:</xforms:label>
<xforms:item>
<xforms:label>US Dollars</xforms:label>
<xforms:value>USD</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>CDN Dollars</xforms:label>
<xforms:value>CDN</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>Euro</xforms:label>
<xforms:value>Euro</xforms:value>
</xforms:item>
</xforms:select>
</checkgroup>
Alternatively, you could create the
choices in your data model as follows:
<xforms:instance xmlns="">
<data>
<currency/>
<choice show="US Dollars">USD</choice>
<choice show="CDN Dollars">CDN</choice>
<choice show="Euros">Euro</choice>
</data>
</xforms:instance>
In this case, you would use the xforms:itemset
option to link to those choices, as illustrated by the following checkgroup:
<checkgroup sid="currency">
<xforms:select ref="currency" appearance="full">
<xforms:label>Select the currencies you accept:</xforms:label>
<xforms:itemset nodeset="instance('currency')/choice">
<xforms:label ref="@show"></xforms:label>
<xforms:value ref="."></xforms:value>
</xforms:itemset>
</xforms:select>
</checkgroup>
Usage details
- To allow the user to select any number of choices
in the checkgroup, use an xforms:select option. To limit the user
to selecting one choice from the checkgroup, use an xforms:select1
option.
- The check boxes in a checkgroup item are arranged
vertically by default (that is, each check appears immediately under
the previous choice).
- To arrange a checkgroup item in another manner,
use the <xforms:extension> element to add an itemlocation to each
check in the group. For example, you might set the checks to appear
one after another horizontally with the following itemlocation:
<xforms:extension>
<itemlocation>
<after compute="itemprevious"/>
</itemlocation>
</xforms:extension>
For more information about the xforms:extension
element, refer to xforms:select (options) or xforms:select1.
- Each check box in a checkgroup can have its own
label. These labels are displayed immediately to the right of each
check box (rather than above each check box, as with the check item).
- The single node binding in the xforms:select or
xforms:select1 option creates a link between the value option for
the checkgroup and the bound element in the data model, so that they
share data. When the user makes a selection, the xforms:value of that
selection is stored in both locations.
- If the user makes multiple selections, those choices
are stored as a space delimited list. Because this list is space delimited,
the choices themselves cannot contain spaces.
- The contents of the value option for the checkgroup
are never serialized.
- The mouseover option is active for each check box
in the group, not for the group as a whole. This means that you can
use the <xforms:extension> element to make changes to individual
check boxes in the group. For example, the following checkgroup changes
the background color of each radio button when the mouse is over it:
<xforms:itemset nodeset="instance('currency')/choice">
<xforms:label ref="@show"></xforms:label>
<xforms:value ref="."></xforms:value>
<xforms:extension>
<bgcolor compute="mouseover == 'on' ? 'blue' : 'green'"/>
</xforms:extension>
</xforms:select>
- The itemlocation of check box buttons in a checkgroup
is interpreted relative to the top-left of the group, not the top-left
of the form. The top-left of the group is set 3 pixels in from the
left edge of the group, and 3 pixels down from the top edge of the
group. This allows room for a border to be added to the group.
- If using relative positioning, you can give each
check an itemlocation of after the itemprevious, as shown:
<xforms:extension>
<itemlocation>
<after compute="itemprevious"/>
</itemlocation>
</xforms:extension>
This will place each check after its
predecessor, except for the first check, which is placed at the top
left corner of the group. For the first check, the after command is
ignored because the checkgroup position is not set until after the
contained check items are positioned, and itemlocation keywords are
ignored when they refer to items that have not been positioned.
- Use the layoutflow option to control if the content
is displayed vertically or horizontally.
- The itemnext is set as follows:
- The checkgroup itself refers to the first check
in the group.
- The last check in the group refers to the item
that follows the checkgroup in the build order.
- The item that precedes the checkgroup in the build
order refers to the checkgroup itself.
- The size of a checkgroup is determined by the size
of the radio items and labels in that group. As such, the extent setting
in the itemlocation option has no affect on the group's sizing.
- You can use the constraint setting in the data
model to limit the number of selections the user can make. To do this,
set the <xforms:value> of each selection to a standard length.
For example, you might have five choices and give them values of 1-5
(each being one character long). When the user makes some selections,
the values of the selections are concatenated into a space delimited
list. You can predict the length of this list based on the length
of your standard values. For example, if the user selects two items,
then the list will be three characters long (1 2), while selecting
three items will create a list that is 5 characters long (1 3 5).
This allows you to set a constraint on the length of that value (which
is stored by the data element that is bound to the <xforms:select>)
that will actually limit the number of selections the user can make.
- You can then set a constraint on the data element
that is bound to the <xforms:select> so that it cannot exceed a
certain length. In this case, limiting it to a length of less than
or equal to five will only allow three selections to be made.
- Do not use itemprevious to compute the location of an item after
a checkgroup. Doing so can break signatures, as the items inside checkgroups
receive random scope identifiers at runtime. If you sign the form
with a compute resolved to a random sid, the compute is locked to
that random sid. If you then re-open the form, the items inside the
checkgroups are assigned new random sids, which do not correspond
with the sid associated with the compute and break the signature.