getGroupedItemAdded by IBM on October 10, 2012 | Version 1 (Original)
|Returns a reference to the first item in a group. getGroupedItem can also return a reference to the first item in a group that has a particular characteristic, such as a specific option or setting. Tags: getGroupedItem function, utility
1.4 functions, groups, sid, empty function, value, returning
items with empty values, returning items with empty values, XFDL, 8.0, spec
getGroupedItem returns a reference to any of the following:
- The first item in a given group.
- The first item in a group that has a particular option. For example, the first item with a bgcolor .
- The first item in a group that has a particular option setting. For example, the first item with a value of on.
Table 1. getGroupedItem parameters
getGroupedItem(group, option, literal, groupContext, groupContextType,
|group||String||The name of the group that you want to get an item from. This name can include a page reference, such as PAGE1.myGroup.|
|option||String||Optional. When supplied, the function only searches for items that have this option.|
|literal||String||Optional. When supplied, the function only searches for items that have the specified option set to this value. Use this parameter with theoption parameter. If the empty function is used as this parameter, getGroupedItem searches for an item that has no value set for the specified option.|
|groupContext||String||Optional. The starting point to use to locate the group if the group name is not fully qualified. For example, if the group was on the first page, you would use PAGE1.|
|groupContextType||String||Optional. The level of the group context parameter, such as page, item or option. Currently, only page is valid.|
|referenceType||String||Optional. Sets the scope of the reference that is returned. The reference begins at the level below this. For example, to get a reference that begins at the page level, set this parameter to page Valid settings are form and page. The default reference type is form.|
|scheme||String||Optional. The referencing scheme used. The default scheme is XFDL.|
Returns A reference to the first item matching the search criteria or an empty string if an error occurs.
Usage details getGroupedItem supports the empty function as its third parameter. This support allows getGroupedItem to return items that contain empty values in the specified option.
Example In this example, getGroupedItem gets the scope identifier (sid) of the radio button that is turned on.
<label>The SID of the selected radio button is:</label>
<value compute="getGroupedItem('Page1.radioGroup', 'value','on')"></value>