This is a short document that will show you how to use the Check Box Group and Radio Button Group controls to create dynamic content in XPages, in very much the same way that it can be done on a Notes Form.
What are these controls?
The Check Box Group (xp:checkBoxGroup) and Radio Button Group (xp:radioGroup) controls are not currently by default part of the Controls palette in IBM Lotus Domino Designer 8.5. They're accessible from the Create Control dialog box (see Fig. 1a). Both of these controls are basically configured in the same way as the List Box (xp:listBox) control, and like the List Box they use the 'Select Item' (xp:selectItem) and 'Select Items' (xp:selectItems) controls nested within them to generate the available choices (more on this in the 'User Interface workaround' section).
Fig. 1a: Create Control dialog box:
Aren't there Check Box and Radio button controls on the the Core palette?
This is indeed the case (see Fig. 1b). These controls from the Core palette are specific in their nature and not intended to handle a list of choices. The Check Box (xp:checkBox) control is set to handle checked and unchecked values - true or false, 1 and 0 - and it is not setup for multiple select from a list of choices.
Fig. 1b: The Check Box and Radio Button on the Core Control palette:
The same can be said for the Radio Button (xp:radio) control, though you can arrange a number of Radio Buttons, all bound to the same data source, in a group (see Fig. 1c). Here the Radio button property 'groupName' is used to collate all the radio buttons together. But it's very difficult (it may not possible) to use this feature with a dynamic list of choices gathered from a @DbColumn or @DbLookup. So, this is where the Check Box Group and Radio Button Group controls come into their own, that mirror the functionality in a Notes Form.
Fig. 1c: Radio Button group name property:
Dynamic content in Notes:
In Notes with the use of @DbColumn and @DbLookup, we can refresh the options selectable on a Checkbox or Radio button field based on a changed value on another field (see Fig 2a & 2b).
Fig. 2a: Creating dynamic content on a Notes form:
Fig: 2b: Dynamic content at runtime on a Notes client.
The same content in XPages:
In XPages we can recreate this feature using the same @Functions (with some minor syntax changes) and the Checkbox or Radio Button Group controls (see Fig 3).
Fig: 3: XPages dynamic content at runtime on a web browser.
These controls differ slightly from the Check Box and Radio Button that are on the Core Controls palette. These other controls allow for the provision of multiple values, though the core Radio Button control does allow for the a number of controls to be included in a group. The advantage of using the Radio Button Group from the Other Controls palette is that you can compose computed dynamic values more easily.
User Interface workaround:
The disadvantage of using the Other Controls Checkbox group and Radio Button group is that there isn't a full UI in Designer (see Fig 4).
Fig: 4: Current UI for the Checkbox group and Radio button group controls.
But this is not to say you won't be able to use them.
Using the UI of the List Box, the basic content markup can be generated. All that is left to do is to change tags from the List Box to either the Checkbox group or Radio Button group controls (see Fig 5a, 5b & 5c).
Fig: 5a: Typical XPages markup source for a List Box control. see snippets document
<blockquote><pre><htmlblock>
<xp:listBox id="listBox1" value="#{sessionScope.values}">
<xp:selectItem itemLabel="AAA" itemValue="AAA"></xp:selectItem>
<xp:selectItem itemLabel="BBB" itemValue="BBB"></xp:selectItem>
<xp:selectItem itemLabel="CCC" itemValue="CCC"></xp:selectItem>
</xp:listBox></htmlblock></pre></blockquote>
<xp:listBox id="listBox1" value="#{sessionScope.values}">
<xp:selectItem itemLabel="AAA" itemValue="AAA"></xp:selectItem>
<xp:selectItem itemLabel="BBB" itemValue="BBB"></xp:selectItem>
<xp:selectItem itemLabel="CCC" itemValue="CCC"></xp:selectItem>
</xp:listBox>
Change the list box tag to that of the group checkbox in the Source pane like so...
Fig: 5b: Changed source to render a Checkbox Group control. see snippets document
<xp:checkBoxGroup id="checkBoxGroup1"value="#{sessionScope.values}">
<xp:selectItem itemLabel="AAA" itemValue="AAA"></xp:selectItem>
<xp:selectItem itemLabel="BBB" itemValue="BBB"></xp:selectItem>
<xp:selectItem itemLabel="CCC" itemValue="CCC"></xp:selectItem>
</xp:checkBoxGroup>
or
Fig: 5c: Changed source to render a Radio Button Group Control see snippets document
<xp:radioGroup id="radioGroup1"value="#{sessionScope.values}">
<xp:selectItem itemLabel="AAA" itemValue="AAA"></xp:selectItem>
<xp:selectItem itemLabel="BBB" itemValue="BBB"></xp:selectItem>
<xp:selectItem itemLabel="CCC" itemValue="CCC"></xp:selectItem>
</xp:radioGroup>
Similarities between Notes and XPages:
So here is how things match up between Notes Fom and a XPage that composes data with the same functionality (see Fig. 6 and attached sample application
cboxgrp.zip (cboxgrp.nsf)
).
Fig: 6: Comparison table for the above feature (see attached sample app).
|
|
|
|
The @DbColumn lookup for the 'Select Country' option
|
On the Form, the Dialog box generates it's choices using this formula
@Unique(@DbColumn("";"":"";"viewList";1 ))
|
On the XPage, the Combobox control's values will get the same value as used in the Notes form using the following formula...
@Unique(@DbColumn(@DbName(),"viewList",1))
Note the slight change in the syntax of the formula where the comma replaces the colon and semi-colon in most cases
|
What happens when the value for 'Select Country' changes?
|
When an item is selected from this list, all the fields on the document get refreshed
|
When the value of the 'Select Country' is selected or changed, an 'onChange' event gets fired which refreshes the page.
|
Upon refresh, how are the 'Select a City' values generated?
|
A 'Hide When' formula controls when this fields visibility. If the value 'selectCountry' equals null, this field won't appear.
The 'selectCity' field's choices are generated using the following formula
@DbLookup(""; "" :""; "viewList"; selectCountry ; 2 )
This lookup is dependant on the value, key, of the 'selectCountry' field. And this formula is revaluated when there is a document refresh
|
The table row on which the 'Select a City' control sits will not be visible if content of the 'selectCountry' control is null.
The Select a City list items are more or lest generated in the same as they are in the Form.
var ctry = document1.getItemValueString("selectCountry");
var lst1 = @DbLookup(@DbName(),"viewList",ctry,2);
@Explode(lst1,",")
|
Layout property:
There are two choices for layout on the Checkbox group and Radio Button group controls. The default is horizontal layout, 'lineDirection', with vertical layout, 'pageDirection' being the alternative.
Fig: 7a: Layout - Line Direction in the mark-up: see snippets document
<xp:checkBoxGroup id="checkBoxGroup2"value="#{document1.selectCity}" layout="lineDirection"> <xp:selectItems>
<xp:this.value>
<![CDATA[#{javascript:var ctry = document1.getItemValueString("selectCountry");
var lst1 = @DbLookup(@DbName(),"viewList",ctry,2);
@Explode(lst1,",")
}]]>
</xp:this.value>
</xp:selectItems>
</xp:checkBoxGroup>
Fig: 7b: Layout - Page Direction at runtime on a web browser:
Fig: 8a: Layout - Page Direction in the mark-up: see snippets document
<xp:checkBoxGroup id="checkBoxGroup2"value="#{document1.selectCity}" layout="pageDirection"> <xp:selectItems>
<xp:this.value>
<![CDATA[#{javascript:var ctry = document1.getItemValueString("selectCountry");
var lst1 = @DbLookup(@DbName(),"viewList",ctry,2);
@Explode(lst1,",")
}]]>
</xp:this.value>
</xp:selectItems>
</xp:checkBoxGroup>
Fig: 8b: Layout - Page Direction at runtime on a web browser:
Conclusion:
The above demonstrates the many similarities between Notes and XPages, and it shows through using the 'Other Controls' Checkbox and Radio Button group that the skills already used in Notes Domino applications can easily translate to building applications in XPages.