datagroup

Provides a way of associating related data items to each other and to certain other items.

There are two ways of using this option. In the first case, it enables you to create a group of data items, called a datagroup. In the second case, this option enables you to reference such a datagroup from button, action, or cell items.

This option is most often used to group file enclosures. For example, you can use this feature to create folders with which users can organize their enclosures. Each enclosed file can belong to several datagroups, and each datagroup can contain several enclosed files.

Syntax

   <datagroup>
      <datagroupref>datagroup reference₁</datagroupref>
      ...
      <datagroupref>datagroup reference_n</datagroupref>
   </datagroup>

Note: Include a datagroup reference entry for each datagroup this item accesses.

Table 1. datagroup parameters
Parameter	Type	Description
datagroup reference	string	Identifies a data group. This can done in one of two formats: datagroup_name for datagroups on the same page. page_sid.datagroup_name for datagroups on a different page.

Available in

action, button, cell, data

Example

If this sample were part of a data item definition, it would mean the data item belonged to the datagroups Business_Letters, Personal_Letters, and Form_Letters.

If this sample were part of an action, button, or cell item, it would mean the user could store the enclosure in one of the three datagroups.

   <datagroup>
      <datagroupref>Business_Letters</datagroupref>
      <datagroupref>Personal_Letters</datagroupref>
      <datagroupref>Form_Letters</datagroupref>
   </datagroup>

In the following example, the Enclose button references the datagroups Business_Letters and Personal_Letters. As a result, when users click this button, they can choose to place the file they are enclosing into one of these folders. Because the datagroup Form_Letters is not specified in the datagroup reference, it is not available to “BUTTON1”.

   <button sid="BUTTON1">
      <value>Click to Enclose File</value>
      <type>enclose</type>
      <datagroup>
         <datagroupref>Business_Letters</datagroupref>
         <datagroupref>Personal_Letters</datagroupref>
      </datagroup>
   </button>

Usage details

Default: none
The grouping of data items into datagroups cannot span multiple pages. That is, all the data items assigned to a given datagroup must belong to the same page. On the other hand, buttons, actions, and cells from one page can reference datagroups from another page, provided that you specify the page sid in the datagroup reference.
Used with items handling enclosures, datagroup lists the datagroups the item can access. Used with a data item, datagroup lists the datagroups to which the enclosure belongs. Enclosures are stored in data items.
Items that handle enclosed files perform enclose, extract, remove, and display actions. These actions types are set using the type option.
When a user selects an item that handles enclosed files, the list of datagroups appears. The user chooses the datagroup (or folder) with which to work. If the action is enclosing, the enclosed file is added to that datagroup. Otherwise, a list of files in the datagroup appears. The user chooses a file from the list.
The action of enclosing a file creates the data item, and stores the user's choice of datagroup (or folder) in the data item's datagroup option.