Field Element (Data) - Revision history

Rob: /* The "field" Element */

2009-02-20T09:57:23Z

The "field" Element

← Older revision		Revision as of 09:57, 20 February 2009
Line 99:		Line 99:
	:{\| class="infotable"		:{\| class="infotable"
	\|class="leftnormal"\|[[#bound\|bound]]		\|class="leftnormal"\|[[#bound\|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.		\|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.<br>
			{{note}}A Bound script may only be used on a value-based field.
	\|-		\|-
	\|[[#calculate\|calculate]]		\|[[#calculate\|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.		\|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.<br>
			{{note}}A Calculate script may only be used on a "derived" field.
	\|-		\|-
	\|[[#finalize\|finalize]]		\|[[#finalize\|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.		\|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.<br>
			{{note}}A Finalize script may only be used on a value-based field.
	\|-		\|-
	\|}		\|}

Rob: /* The "field" Element */

2009-02-20T02:24:26Z

The "field" Element

← Older revision		Revision as of 02:24, 20 February 2009
Line 91:		Line 91:
	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.<br>		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.<br>
	Default: "none".		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.		{{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.
	\|-		\|-
	\|}		\|}

Rob: /* The "field" Element */

2009-02-20T02:11:48Z

The "field" Element

← Older revision		Revision as of 02:11, 20 February 2009
Line 88:		Line 88:
	none – No history tracking is performed.<br>		none – No history tracking is performed.<br>
	stack – Tracks all changes in the order applied.<br>		stack – Tracks all changes in the order applied.<br>
	best – Records only the single largest adjustment, and all changes must use the same modify operator.<br>		changes – Tracks all changes in the order applied, ignoring any adjustments that yield no actual change (e.g. "+0" or "*1").<br>
			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.<br>
	Default: "none".		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.		{{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.

Rob: /* The "field" Element */

2009-01-13T06:52:56Z

The "field" Element

← Older revision		Revision as of 06:52, 13 January 2009
Line 91:		Line 91:
	Default: "none".		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.		{{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" };~~
	\|-		\|-
	\|}		\|}

Rob at 12:49, 29 November 2008

2008-11-29T12:49:46Z

@@ Line 111: / Line 111: @@
 ==The "bound" Element{{anchor|bound}}==
-The "bound" element defines the [[Match Tag Expression|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.
+The "bound" element defines the [[Bound Script|Bound script]] that dynamically calculates the bounding limits for the field value. The complete list of attributes for this element is below.
 :{| class="infotable"
-|class="leftnormal"|PCDATA
+|class="leftnormal"|phase
-|TagExpr – Specifies the code comprising the Match tag expression.
+|Id – Specifies the unique id of the evaluation phase during which the script is invoked.
 |-
 |}
@@ Line 121: / Line 133: @@
 ==The "calculate" Element{{anchor|calculate}}==
-The "calculate" element defines the [[Match Tag Expression|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.
+The "calculate" element defines the [[Calculate Script|Calculate script]] that dynamically determines the field value. The complete list of attributes for this element is below.
 :{| class="infotable"
-|class="leftnormal"|PCDATA
+|class="leftnormal"|phase
-|TagExpr – Specifies the code comprising the Match tag expression.
+|Id – Specifies the unique id of the evaluation phase during which the script is invoked.
 |-
 |}
@@ Line 131: / Line 155: @@
 ==The "finalize" Element{{anchor|finalize}}==
-The "finalize" element defines the [[Match Tag Expression|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.
+The "finalize" element defines the [[Finalize Script|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.
 :{| class="infotable"
-|class="leftnormal"|PCDATA
+|class="leftnormal"|phase
-|TagExpr – Specifies the code comprising the Match tag expression.
+|Id – Specifies the unique id of the evaluation phase during which the script is invoked.
 |-
 |}
@@ Line 144: / Line 180: @@
 <pre>
-<containerreq phase="Setup" priority="500" name="MyTest>
+<field
-   <before name="BeforeTest"/>
+  id="wpDamage"
-   <after name="AfterTest"/>
+  name="Damage"
-   val:Level.? >= 4
+  type="derived"
-   </containerreq>
+  maxlength="20">
 </pre>

Rob at 12:25, 29 November 2008

2008-11-29T12:25:58Z

← Older revision		Revision as of 12:25, 29 November 2008
Line 98:		Line 98:

	:{\| class="infotable"		:{\| class="infotable"
	\|class="leftnormal"\|[[#~~match~~\|~~match~~]]		\|class="leftnormal"\|[[#bound\|bound]]
	\|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.~~		\|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.
	~~{{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/After Element (Data)~~\|~~before~~]]		\|[[#calculate\|calculate]]
	\|~~Zero or more~~ "~~before~~" ~~elements~~ may appear as defined by the given link. This element ~~specifies appropriate timing dependencies possessed by~~ the ~~container requirement~~.		\|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.
	\|-		\|-
	\|[[~~Before/After Element (Data)~~\|~~after~~]]		\|[[#finalize\|finalize]]
	\|~~Zero or more~~ "~~after~~" ~~elements~~ may appear as defined by the given link. This element ~~specifies appropriate timing dependencies possessed by~~ the ~~container requirement~~.		\|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.
	\|-		\|-
	\|}		\|}
	~~{ &l_calculate, e_xml_optional }, \~~
	~~{ &l_finalize, e_xml_optional }~~
	~~{ &l_condition, e_xml_optional },~~
	~~{ &l_bound, e_xml_optional },~~

	==The "~~match~~" Element{{anchor\|~~match~~}}==		==The "bound" Element{{anchor\|bound}}==

	The "~~match~~" element defines the [[Match Tag Expression\|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.		The "bound" element defines the [[Match Tag Expression\|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.

			:{\| class="infotable"
			\|class="leftnormal"\|PCDATA
			\|TagExpr – Specifies the code comprising the Match tag expression.
			\|-
			\|}

			==The "calculate" Element{{anchor\|calculate}}==

			The "calculate" element defines the [[Match Tag Expression\|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.

			:{\| class="infotable"
			\|class="leftnormal"\|PCDATA
			\|TagExpr – Specifies the code comprising the Match tag expression.
			\|-
			\|}

			==The "finalize" Element{{anchor\|finalize}}==

			The "finalize" element defines the [[Match Tag Expression\|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.

	:{\| class="infotable"		:{\| class="infotable"
Line 126:		Line 141:
	==Example==		==Example==

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

	<pre>		<pre>

Rob at 12:19, 29 November 2008

2008-11-29T12:19:16Z

← Older revision		Revision as of 12:19, 29 November 2008
Line 3:		Line 3:
	==The "field" Element==		==The "field" Element==

	Most components will possess at least one field. These fields represents values associated with all things derived from the component, such attack and damage values for weapons, ranges and components for spells, etc. Each separate field is specified through the use of a "field" element. The complete list of attributes for this element is below.		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.

	:{\| class="infotable"		:{\| class="infotable"
Line 56:		Line 56:
	\|-		\|-
	\|nevercache		\|nevercache
	\|(Optional) Boolean – Indicates that the results of finalization for this field should never be cached and always regenerated. Default: "no".		\|(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		\|persistence
Line 64:		Line 67:
	full – The field is never reset and is saved in portfolios for restoration when reloaded.<br>		full – The field is never reset and is saved in portfolios for restoration when reloaded.<br>
	Default: "none"		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		\|ismultiline
Line 71:		Line 77:
	\|(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".		\|(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".
	\|-		\|-
	\|~~PCDATA~~		\|format
	\|~~TagExpr~~ – ~~Specifies~~ the ~~code comprising~~ the [~~[Container Tag Expression\|Container tag expression~~]].		\|(Optional) Set – Designates any special numeric formatting to be enforced for a value-based field. Must be one of these values:<br>
			integer – Any portal mapped to the field will always treat the field as an integer value.<br>
			float – Any portal mapped to the field will always treat the field as a floating-point value.<br>
			any – Portals are free to determine how to present the field for editing.<br>
			Default: "any".
			\|-
			\|history
			\|(Optional) Set – Designates what type of history tracking is to be performed for this field. Must be one of these values:<br>
			none – No history tracking is performed.<br>
			stack – Tracks all changes in the order applied.<br>
			best – Records only the single largest adjustment, and all changes must use the same modify operator.<br>
			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" };
	\|-		\|-
	\|}		\|}
	~~{ "usedelta", e_xml_set, l_yes_no[1], NULL, SIZE_YES_NO, l_yes_no },~~
	~~{ "iscachefinal", e_xml_set, l_yes_no[1], NULL, SIZE_YES_NO, l_yes_no },~~
	~~{ "format", e_xml_set, l_edit_format[0], NULL, SIZE_EDIT_FORMAT, l_edit_format },~~
	~~{ "history", e_xml_set, l_field_history[0], NULL, SIZE_FIELD_HISTORY, l_field_history },~~

	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.		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.

Rob: New page: {{context|Kit Reference|Structural File Reference|Component Element (Data)}} ==The "field" Element== Most components will possess at least one field. These fields represents values assoc...

2008-11-29T11:40:54Z

New page: {{context|Kit Reference|Structural File Reference|Component Element (Data)}} ==The "field" Element== Most components will possess at least one field. These fields represents values assoc...

New page

{{context|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 attack and damage values for weapons, ranges and components for spells, etc. Each separate field is specified through the use of a "field" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|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. 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"
|-
|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".
|-
|PCDATA
|TagExpr – Specifies the code comprising the [[Container Tag Expression|Container tag expression]].
|-
|}
{ "usedelta", e_xml_set, l_yes_no[1], NULL, SIZE_YES_NO, l_yes_no },
{ "iscachefinal", e_xml_set, l_yes_no[1], NULL, SIZE_YES_NO, l_yes_no },
{ "format", e_xml_set, l_edit_format[0], NULL, SIZE_EDIT_FORMAT, l_edit_format },
{ "history", e_xml_set, l_field_history[0], NULL, SIZE_FIELD_HISTORY, l_field_history },

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.

:{| class="infotable"
|class="leftnormal"|[[#match|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/After Element (Data)|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.
|-
|[[Before/After Element (Data)|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{{anchor|match}}==

The "match" element defines the [[Match Tag Expression|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.

:{| class="infotable"
|class="leftnormal"|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.

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