Difference between revisions of "Group Element (Data)"

Revision as of 00:01, 25 November 2008

Context: HL Kit … Kit Reference … Structural File Reference 

The "group" Element

One of the cornerstone mechanisms used for describing objects is tags. All tags belong to named tag groups, with each tag group having a defined set of valid tag values that can be used. Tag groups also have a number of characteristics which dictate how the tags within that group are handled. Each tag group is specified through the use of a "group" element. The complete list of attributes for this element is below.

id	Id – Specifies the unique id of the tag group. This id is used in all references to the tag group.
dynamic	(Optional) Boolean – Indicates whether the tags for this group can be dynamically defined "on-the-fly" by specifying the tag directly on a thing. If a tag group is not dynamic, then all tags for the group must be defined within the group prior to their use within data files. If a tag group is dynamic, new tags can be defined throughout the data files by simply including the new tag id within a "tag" element on a thing. Dynamic tag groups cannot be assigned "explicit" sequencing. Default: "no".
sequence	(Optional) Set – Designates the sorting sequence to be used for the tags within the group. When you specify the tag group within a sort set, this sequence is used. Must be one of these values: ascii – Sort using ASCII codes (digits, all upper case, all lower case). nocase – Sort ignoring case (digits, upper case A, lower case A, upper B, etc.). textvalue – Treat the name of each tag as a numeric value (if no value, treated as zero for sorting). idvalue – Treat the id of each tag as a numeric value (if no value, treated as zero for sorting). explicit – Sort on the value of the "order" attribute assigned to each tag. id – Sort on the unique id of each tag as if it were text (allows handling of absolutely any situation). Default: "ascii".
minvalue	(Optional) Integer – Specifies the starting value to use for automatically generating value-based tags (see below). Default: "0".
maxvalue	(Optional) Integer – Specifies the starting value to use for automatically generating value-based tags (see below). Default: "0".
autoassign	(Optional) Boolean – Designates how tags from this group are handled when a thing is copied for use within the Editor. This behavior only applies when the tag group possesses auto-created tags, such as with identity tags. Must be one of the following: yes – Tags from this group are always considered to be auto-assigned and are therefore never copied within the Editor. no – Tags from this group are always copied within the Editor, except for identity tags that reference the thing being copied. This setting enables proper handling of identity tags for other things that are assigned, such as in situations where one things "counts as" another thing. default – Tags from this group are copied within the Editor only when they were not automatically created by the Kit. Default: "default".

NOTE! Tag groups can automatically generate "value" tags for a given integer range via use of the "minvalue" and/or "maxvalue" attributes. Value tags possess a unique id that is simply an integer value, such as "42". Specifying either or both of these attributes as non-zero makes it easy to create a group of tags number X-Y (e.g. 1-42). When value tags are created, the group automatically uses "idvalue" sequencing. You can define explicit tags for the group that are blended with the auto-generated tags, and any author-defined tag takes precedence over whatever would be auto-generated. Lastly, if the group is dynamic, then additional tags can be defined on-the-fly, as needed.

The "bootstrap" element also possesses child elements that pertain to the automatically added things. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

match	An optional "match" element may appear as defined by the given link. This element defines the Match Tag Expression. If omitted, all things are assumed to match. IMPORTANT! This element is only applicable when the bootstrap is defined within a component. In all other cases, this element may not be specified.
container	A single "container" element must appear as defined by the given link. This element defines the Container Tag Expression. IMPORTANT! This element is not applicable when the bootstrap is defined within an entity.
autotag	Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to the added thing.

The "match" Element

The "match" element defines the Match script that determines whether a particular thing receives the specified bootstrap. The tag expression is applied against each thing derived from the component, and the bootstrap is only assigned to things that satisfy the tag expression. The complete list of attributes for this element is below.

PCDATA

TagExpr – Specifies the code comprising the Match tag expression.

The "container" Element

The "container" element defines the Container script that determines whether the bootstrap is made available within the container. The tag expression is applied against the container of the prospective bootstrapped pick. If the container does not satisfy the tag expression, the bootstrapped pick is treated as non-live. The complete list of attributes for this element is below.

PCDATA

TagExpr – Specifies the code comprising the Container tag expression.

Example

The following example demonstrates what a "bootstrap" element might look like. All default values are assumed for optional attributes.

<bootstrap thing="AttrIncr">
  <container phase="Setup" priority="500">
    val:Level.? >= 4
    </container>
  <autotag group="TheGroup" tag="TheTag"/>
  </bootstrap>