Field Element (Data)

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. changes – Tracks all changes in the order applied, ignoring any adjustments that yield no actual change (e.g. "+0" or "*1"). best – Records only the single largest adjustment, and all changes must use the same modify operator. If an adjustment results in no actual change, it is ignored. 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 or Bound script.

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.

bound	An optional "bound" element may appear as defined by the given link. This element defines the Bound Script that sets up the bounding limits to be used for the field value. If omitted, bounding is performed against the "minvalue" and "maxvalue" attributes. NOTE! A Bound script may only be used on a value-based field.
calculate	An optional "calculate" element may appear as defined by the given link. This element defines the Calculate Script that computes the value to be utilized for the field. If omitted, the field value is only modified via eval scripts. NOTE! A Calculate script may only be used on a "derived" field.
finalize	An optional "finalize" element may appear as defined by the given link. This element defines the Finalize Script that synthesizes a final value for display to the user. If omitted, no final formatting is performed. NOTE! A Finalize script may only be used on a value-based field.

The "bound" Element

The "bound" element defines the Bound script that dynamically calculates the bounding limits for the field value. The complete list of attributes for this element is below.

phase	Id – Specifies the unique id of the evaluation phase during which the script is invoked.
priority	Integer – Specifies the evaluation priority during which the script is invoked.
name	(Optional) Text – Specifies the name assigned to this script for the purpose of establishing timing dependencies. If empty, no timing dependencies may be defined elsewhere that depend upon this script. Default: Empty.
isprimary	(Optional) Boolean – Indicates whether this task should be considered the "primary" task when multiple tasks are assigned the same name. Default: "no".
PCDATA	Script – Specifies the code comprising the Bound script.

The "calculate" Element

The "calculate" element defines the Calculate script that dynamically determines the field value. The complete list of attributes for this element is below.

phase	Id – Specifies the unique id of the evaluation phase during which the script is invoked.
priority	Integer – Specifies the evaluation priority during which the script is invoked.
name	(Optional) Text – Specifies the name assigned to this script for the purpose of establishing timing dependencies. If empty, no timing dependencies may be defined elsewhere that depend upon this script. Default: Empty.
isprimary	(Optional) Boolean – Indicates whether this task should be considered the "primary" task when multiple tasks are assigned the same name. Default: "no".
PCDATA	Script – Specifies the code comprising the Bound script.

The "finalize" Element

The "finalize" element defines the Finalize script that synthesizes the final value for display to the user. The synthesized value may not exceed the maximum length specified by the "maxfinal" attribute for the field. The complete list of attributes for this element is below.

phase	Id – Specifies the unique id of the evaluation phase during which the script is invoked.
priority	Integer – Specifies the evaluation priority during which the script is invoked.
name	(Optional) Text – Specifies the name assigned to this script for the purpose of establishing timing dependencies. If empty, no timing dependencies may be defined elsewhere that depend upon this script. Default: Empty.
isprimary	(Optional) Boolean – Indicates whether this task should be considered the "primary" task when multiple tasks are assigned the same name. Default: "no".
PCDATA	Script – Specifies the code comprising the Bound script.

Example

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

<field
  id="wpDamage"
  name="Damage"
  type="derived"
  maxlength="20">
  </field>

<field
  id="perHeight"
  name="Height"
  type="user"
  maxfinal="20"
  defvalue="68">
  <bound phase="Render" priority="10000"><![CDATA[
    @minimum = field[perHtMin].value
    @maximum = field[perHtMax].value
    ]]></bound>
  <finalize><![CDATA[
    ~calculate the height in terms of feet and inches
    var feet as number
    var inches as number
    feet = @value / 12
    feet = round(feet,0,-1)
    inches = @value - (feet * 12)
    ~synthesize appropriate text to display the height properly
    @text = feet & "'"
    if (inches <> 0) then
      @text = @text & " " & inches & chr(34)
      endif
    ]]></finalize>
  </field>