Field Element (Data)

From HLKitWiki
Revision as of 12:19, 29 November 2008 by Rob (talk | contribs)
Jump to navigationJump to search

Context: HL Kit … Kit Reference … Structural File Reference … Component Element (Data) 

The "field" Element

Most components will possess at least one field. These fields represents values associated with all things derived from the component, such as attack and damage values for weapons, ranges and components for spells, etc. Extensive details on the use of fields can be found in the separate section on Advanced Fields. Each separate field is specified through the use of a "field" element. The complete list of attributes for this element is below.

id Id – Specifies the unique id to utilize for this field.
name Text – Specifies the publicly visible name associated with the field. Maximum length is 30 characters.
abbrev (Optional) Text – Specifies a shortened abbreviation to use for the field name. If empty, the name is used as the abbreviation and truncated as necessary. Maximum length is 10 characters. Default: Empty.
maxlength (Optional) Integer – Specifies the maximum number of characters that will be managed for this field. If zero, the field is considered a value-based field. Default: "0".
type (Optional) Set – Designates the type of access behavior granted by this field. Field values for picks always start out equal to the value assigned to the thing, and they can often be changed for the pick during evaluation. Must be one of these values:

static – The value assigned to the thing is fixed and can never be changed.
user – The value is user-configurable via some appropriate method, such as an edit portal for text-based fields.
derived – The value is calculated during the evaluation cycle.
Default: "user".

style (Optional) Set – Designates any special characteristics of the field. Must be one of these values:

normal – The field is used normally as a simple value or string.
menu – The field contains an item selected via a menu.
array – The field encompasses an array of values, with the size specified via the "arrayrows" attribute.
matrix – The field encompasses a matrix of values, with the size specified via both the "arrayrows" and "maxtrixcolumns" attributes.
Default: "normal".

decimals (Optional) Integer – Specifies the number of decimal places to be included when outputting a value-based field as text. Values are always tracked internally as floating point numbers, but this attribute governs how the field is displayed as text. If zero, the field is always output as an integer value. Default: "0".
defvalue (Optional) Text – Specifies the default value to be assigned for this field on every thing that possesses the field. If the field is value-based, then this attribute is assumed to be value-based as well and is converted to a value for assignment, with the empty string being treated as zero. Default: "".
arrayrows (Optional) Integer – Specifies the number of rows possessed by a field designated as either an array or matrix. Default: "1".
matrixcolumns (Optional) Integer – Specifies the number of columns possessed by a field designated as a matrix. Default: "1".
minvalue (Optional) Integer – Specifies the minimum value that the field can assume. If a value lower than this is ever assigned to the field, it is bounded to this value. Default: "-999999999999999.".
maxvalue (Optional) Integer – Specifies the maximum value that the field can assume. If a value greater than this is ever assigned to the field, it is bounded to this value. Default: "999999999999999.".
maxfinal (Optional) Integer – Specifies the maximum number of characters that any finalized value may possess. If zero, no finalization is performed for the field. If non-zero, a Finalize script must be provided. Default: "0".

NOTE! Finalization is only supported for value-based fields.

nevercache (Optional) Boolean – Indicates that the results of finalization for this field should never be cached and always regenerated. This attribute applies only to finalization of values on picks. Default: "no".
iscachething (Optional) Boolean – Indicates whether the finalized results for this field should be cached for things. Finalized values are rarely utilized for things, but they are expensive to re-calculate when used on things, so this attribute allows things to cache their finalized values. Default: "no".
persistence (Optional) Set – Designates the persistence behavior for this field, which means how the value is managed across evaluation cycles and whether it is saved/loaded to/from portfolios. Persistence is not applicable for "static" fields and is always performed for "user" fields, so this attribute only applies to "derived" fields. Must be one of these values:

none – The field has no special persistence behavior, being reset at the start of every evaluation cycle and never saved in portfolios.
noreset – The field is never reset at the start of evaluation cycles and never saved in portfolios.
full – The field is never reset and is saved in portfolios for restoration when reloaded.
Default: "none"

usedelta (Optional) Boolean – Indicates whether a separate "delta" value should be maintained for the field. Deltas make it possible to easily have users edit values that are intuitive, even though they integrate adjustments that are applied from other effects. The delta is only applicable to "user" fields that are value-based. Default: "no".
ismultiline (Optional) Boolean – Indicates whether the field should always be considered to contain multi-line text. If a field is multi-line, all portals mapped to the field are implicitly designated as multi-line. If a field is not multi-line, then portals can make their own determination regarding multi-line behavior. This attribute only applies to text-based fields. Default: "no".
signed (Optional) Boolean – Indicates whether the field should always be considered to contain a signed value. If field is signed, then any portal mapped to the field is implicitly designated as signed, else portals are free to make their own determination regarding signed behavior. Default: "no".
format (Optional) Set – Designates any special numeric formatting to be enforced for a value-based field. Must be one of these values:

integer – Any portal mapped to the field will always treat the field as an integer value.
float – Any portal mapped to the field will always treat the field as a floating-point value.
any – Portals are free to determine how to present the field for editing.
Default: "any".

history (Optional) Set – Designates what type of history tracking is to be performed for this field. Must be one of these values:

none – No history tracking is performed.
stack – Tracks all changes in the order applied.
best – Records only the single largest adjustment, and all changes must use the same modify operator.
Default: "none". NOTE! History tracking is only supported for fields that meet the following criteria: type must be "derived"; style must be "normal"; must be value-based; may not be persistent; may not possess a Calculate, Finalize, or Bound script. static T_Glyph_Ptr l_field_history[] = { "none", "best", "stack" };

The "field" element also possesses child elements that pertain to the individual field value. 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 and the container requirement test is applied to them all.

IMPORTANT! This element is only applicable when the container requirement is defined within a component. In all other cases, this element may not be specified.

before Zero or more "before" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the container requirement.
after Zero or more "after" elements may appear as defined by the given link. This element specifies appropriate timing dependencies possessed by the container requirement.

{ &l_calculate, e_xml_optional }, \ { &l_finalize, e_xml_optional } { &l_condition, e_xml_optional }, { &l_bound, e_xml_optional },

The "match" Element

The "match" element defines the Match tag expression that determines whether a particular thing is subject to the container requirement. The tag expression is applied against each thing derived from the component, and the requirement 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.

Example

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

<containerreq phase="Setup" priority="500" name="MyTest>
  <before name="BeforeTest"/>
  <after name="AfterTest"/>
  val:Level.? >= 4
  </containerreq>