Finalize Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Pick
Alternate Context:	None
Fields Finalized?	No

The Finalize script utilizes the following special symbols:

value	Entry: The current value of the field (if numeric), else zero. Exit: Ignored.
text	Entry: The current contents of the field (if text), else the field value converted to a string. Exit: The contents to be used for finalized version of the field. The text may contain encoding.
ispick	Entry: Indicates whether the value is being finalized for a pick (non-zero) or a thing (zero). Exit: Ignored.

Description

The role of the Finalize script is to synthesize a text version of a numeric field that consists of more than just the field value. By default, a numeric field is automatically converted to a string when the ".text" target reference is used on the field, so this script is of no use unless you want a different behavior.

There are numerous places where a Finalize script can be extremely handy. Lots of fields are managed as numeric values for easy of manipulation in data files. However, many of those fields need to be displayed to the user with appropriate units annotated. For example, the cash possessed by a character and the costs of equipment are tracked as numeric values but should ideally be displayed as currency (e.g. "$142"). The height of a character may be tracked as inches, but the user wants to view it in a more common form (e.g. 5'11"). The Finalize script makes it easy to accomplish this.

The Finalize script is invoked after the entire evaluation cycle has completed, but it is only invoked when something actually asks for the finalized contents of the field. Once the script is invoked once, the results are cached internally, but the cost of invoking the script is not incurred unless the contents are actually used somewhere.

The Finalize script begins with an initial context of the pick containing the field being calculated. When invoked, the "value" special symbol is assigned the actual value of the field at the end of evaluation. If the field is text, then the value is always zero. Similarly, the "text" special symbol is assigned the text-based contents of the field after evaluation. If the field is numeric, the value is automatically converted to the corresponding string. When the script completes, the updated contents of the "text" special symbol are used as the finalized contents for the field.

NOTE! When accessing a numeric field via a script, you have the option to use either the ".value" or ".text" target reference. Within any script that utilizes finalized field values (indicated at the top of each script), you should always use the ".text" target reference, unless you have a specific reason for using the ".value" target reference. The reason for this is that ".text" will always retrieved any finalized version of the field, while ".value" will always retrieve the actual value, without any finalization logic being applied.

Example

Within the Sample data files, the height of a character is managed as a numeric field that handles everything in terms of inches. The user wants to view this in the standard format using feet and inches (e.g. 5'11"). A Finalize script is defined that accomplishes this, as shown below.

~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