checkgroup

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.