Calculate Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Pick
Alternate Context:	None
Fields Finalized?	No
Where Used:	Fields
Procedure Use:	"calculate" type, "pick" context

The Bound script utilizes the following special symbols:

value	(Number) Entry: The current value of the field (if the field is numeric), else zero. Exit: The final value to be used for the field (if the field is numeric).
text	(String) Entry: The current context of the field (if the field is text), else the empty string. Exit: The final contents to be used for the field (if the field is text).

Description

The Calculate script is in many ways a specialized Eval script, with the explicit purpose of calculating the value of a field. The script is scheduled to occur at some point during the evaluation cycle, and it could just as easily be implemented as an Eval script. The advantage of the Calculate script is purely a semantic organizational benefit, since the script is defined directly on the field instead of generally on the component (as an Eval script would be handled).

The Calculate script allows you to calculate the appropriate contents for a field. Since the script is scheduled during evaluation, other scripts can legally modify the field before or after the script. Consequently, it is usually only appropriate to use a Calculate script for fields that can be calculated in one centralized location (this script). Otherwise, it is typically better to use Eval scripts for all manipulations of the field.

The Calculate script begins with an initial context of the pick containing the field being calculated. This makes it possible to easily access other fields on the pick when calculating the new contents. When invoked, the appropriate special symbol is initialized with the current contents of the field. If the field is numeric, the "value" special symbol contains the value, and the "text" special symbol contains the current contents of a text field. When the script completes, the updated contents of the appropriate special symbol are used for the field, with the other special symbol completely ignored.

Example

Within the Sample data files, the final value of a trait is determined via a Calculate script. The field value is the result of adding the user-assigned value, any bonuses assigned via scripts, and any in-play adjustment.

@value = field[trtUser].value + field[trtBonus].value + field[trtInPlay].value