Group Element (Data): Difference between revisions

From HLKitWiki
Jump to navigationJump to search
New page: {{context|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, wi...
 
Removed autoassign tag.
 
(6 intermediate revisions by one other user not shown)
Line 3: Line 3:
==The "group" Element==
==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.
One of the cornerstones of describing objects in the Kit is the [[Leveraging Tags Via Tag Expressions|tags mechanism]]. 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.


:{| class="infotable"
:{| class="infotable"
Line 14: Line 14:
|sequence
|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:
|(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)
<ul class="sets">
nocase – sort ignoring case (digits, upper case A, lower case A, upper B, etc.)
<li>ascii – Sort using ASCII codes (digits, all upper case, all lower case).</li>
textvalue – treat the name of each tag as a numeric value (if no value, treated as zero for sorting)
<li>nocase – Sort ignoring case (digits, upper case A, lower case A, upper B, etc.).</li>
idvalue – treat the id of each tag as a numeric value (if no value, treated as zero for sorting)
<li>textvalue – Treat the name of each tag as a numeric value (if no value, treated as zero for sorting).</li>
explicit – sort on the value of the "order" attribute assigned to each tag
<li>idvalue – Treat the id of each tag as a numeric value (if no value, treated as zero for sorting).</li>
id – sort on the unique id of each tag (allows handling of absolutely any situation)
<li>explicit – Sort on the value of the "order" attribute assigned to each tag.</li>
Default: "ascii".
<li>id – Sort on the unique id of each tag as if it were text (allows handling of absolutely any situation).</li>
<li>Default: "ascii".</li>
</ul>
|-
|-
|minvalue
|minvalue
Line 27: Line 29:
|maxvalue
|maxvalue
|(Optional) Integer – Specifies the starting value to use for automatically generating value-based tags (see below). Default: "0".
|(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|identity tags]]. Must be one of the following:<br>
yes – Tags from this group are always considered to be auto-assigned and are therefore '''never''' copied within the Editor.<br>
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.<br>
default – Tags from this group are copied within the Editor only when they were not automatically created by the Kit.<br>
Default: "default".
|-
|-
|}
|}


{{note}}Tag groups can automatically generate "value" tags for a given integer range. Value tags are where the unique id of the tag is simply an integer value, such as "42".  
{{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.  


    -Makes it possible to easily create a group with tags numbered 1-42
{{note}}Dynamic tags are processed in the order they are encountered when the data files are compiled, and there is no guarantee of the order in which dynamic tags will be processed. If a dynamic tag has already been defined when it is next encountered, the original definition is used. This means that the first definition of a dynamic tag that happens to be encountered during compilation is the one that will be used for all instances of the tag, so you should strive to ensure that all dynamically defined tags have identical specifications.
    -The "minvalue" and "maxvalue" attributes specify the minimum and maximum
        values to generate tags for (inclusive)
    -Group is automatically set to sort the tags based on their value
    -Dynamic behavior of tag group is fully controlled by author, so the set of
        auto-created tags can either be fixed or extendable
    -If author wants to do something special for a tag in the sequence, he can
        define it as part of the tag group and the author-defined tag will take
        precedence over any auto-created tag


 
The "group" element also possesses child elements that define the individual tags of the group. 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.
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.


:{| class="infotable"
:{| class="infotable"
|class="leftnormal"|[[#match|match]]
|class="leftnormal"|[[#value|value]]
|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.
|Zero or more "value" elements may appear as defined by the given link. This element specifies the tags that exist for the group.
{{important}}This element is only applicable when the bootstrap is defined within a component. In all other cases, this element may not be specified.
{{note}}While it is valid to specify zero tags here, every tag group must have at least one tag defined. You can only specify zero tags here if the group is dynamic and at least one tag is defined directly on a thing.
|-
|[[#container|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 Element (Data)|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{{anchor|match}}==
==The "value" Element{{anchor|value}}==


The "match" element defines the [[Match Script|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.  
The "value" element defines a tag for the containing tag group. The complete list of attributes for this element is below.  


:{| class="infotable"
:{| class="infotable"
|class="leftnormal"|PCDATA
|class="leftnormal"|id
|TagExpr – Specifies the code comprising the Match tag expression.
|Id – Specifies the unique id of the tag within the group. This id is used in all references to the tag.
|-
|-
|}
|name
 
|(Optional) Text – Name assigned to the tag. If empty, the unique id is used as the name. Maximum length is 100 characters. Default: Empty.
==The "container" Element{{anchor|container}}==
|-
 
|order
The "container" element defines the [[Container Script|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.  
|(Optional) Integer – Specifies the explicit order value to be used when sorting this tag against others within the tag group. This attribute only applies when the tag group is assigned the "explicit" sequence.
 
:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Container tag expression.
|-
|-
|}
|}
Line 88: Line 63:
==Example==
==Example==


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


<pre>
<pre>
<bootstrap thing="AttrIncr">
<group id="Equipment" dynamic="yes">
   <container phase="Setup" priority="500">
   <value id="Hand" name="Requires one or more hands"/>
    val:Level.? >= 4
  <value id="TwoHand" name="Requires two hands"/>
    </container>
  <value id="AutoEquip" name="Gear is auto-equipped"/>
   <autotag group="TheGroup" tag="TheTag"/>
  <value id="Natural" name="Natural weapon/armor/etc."/>
   </bootstrap>
   <value id="CustomGear" name="Custom Gear"/>
   </group>
</pre>
</pre>

Latest revision as of 17:20, 28 January 2009

Context: HL Kit &#133; Kit Reference &#133; Structural File Reference 

The "group" Element

One of the cornerstones of describing objects in the Kit is the tags mechanism. 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".

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.

NOTE! Dynamic tags are processed in the order they are encountered when the data files are compiled, and there is no guarantee of the order in which dynamic tags will be processed. If a dynamic tag has already been defined when it is next encountered, the original definition is used. This means that the first definition of a dynamic tag that happens to be encountered during compilation is the one that will be used for all instances of the tag, so you should strive to ensure that all dynamically defined tags have identical specifications.

The "group" element also possesses child elements that define the individual tags of the group. 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.

value Zero or more "value" elements may appear as defined by the given link. This element specifies the tags that exist for the group.

NOTE! While it is valid to specify zero tags here, every tag group must have at least one tag defined. You can only specify zero tags here if the group is dynamic and at least one tag is defined directly on a thing.

The "value" Element

The "value" element defines a tag for the containing tag group. The complete list of attributes for this element is below.

id Id – Specifies the unique id of the tag within the group. This id is used in all references to the tag.
name (Optional) Text – Name assigned to the tag. If empty, the unique id is used as the name. Maximum length is 100 characters. Default: Empty.
order (Optional) Integer – Specifies the explicit order value to be used when sorting this tag against others within the tag group. This attribute only applies when the tag group is assigned the "explicit" sequence.

Example

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

<group id="Equipment" dynamic="yes">
  <value id="Hand" name="Requires one or more hands"/>
  <value id="TwoHand" name="Requires two hands"/>
  <value id="AutoEquip" name="Gear is auto-equipped"/>
  <value id="Natural" name="Natural weapon/armor/etc."/>
  <value id="CustomGear" name="Custom Gear"/>
  </group>
Retrieved from "https://hlkitwiki.wolflair.com//index.php?title=Group_Element_(Data)&oldid=2402"