Synthesize Script: Difference between revisions

From HLKitWiki
Jump to navigationJump to search
No edit summary
 
(One intermediate revision by the same user not shown)
Line 15: Line 15:
|Where Used:
|Where Used:
|[[Dossier Element (Data)|Dossiers]]
|[[Dossier Element (Data)|Dossiers]]
|-
|Procedure Use:
|"synthesize" type, "container" context
|-
|-
|}
|}
Line 58: Line 61:


{{note}} The Synthesize script is read-only. Within this script, virtually all aspects of the structural hierarchy can be accessed, but nothing can be changed.
{{note}} The Synthesize script is read-only. Within this script, virtually all aspects of the structural hierarchy can be accessed, but nothing can be changed.
{{note}} While within a Synthesize script and any procedures that are invoked, a global tag is automatically assigned by HL. The tag belongs to the "dossier" tag group and has the unique id of the dossier being output. This allows the script code to base its behavior on the actual dossier that the user is outputting.


==Example==
==Example==

Latest revision as of 08:14, 12 May 2009

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context: Hero
Alternate Context: None
Fields Finalized? Yes
Where Used: Dossiers
Procedure Use: "synthesize" type, "container" context

The Synthesize script utilizes the following special symbols:

newline (String) Entry: Contains the appropriate text to begin a new line of text within the output being synthesized (i.e. insert a line break).

Exit: Ignored.

boldon (String) Entry: Contains the appropriate text to turn on output of bold text.

Exit: Ignored.

boldoff (String) Entry: Contains the appropriate text to turn off output of bold text.

Exit: Ignored.

italicson (String) Entry: Contains the appropriate text to turn on output of italic text.

Exit: Ignored.

italicsoff (String) Entry: Contains the appropriate text to turn off output of italic text.

Exit: Ignored.

separator (String) Entry: Contains the appropriate text to insert a suitable horizontal separator. In HTML output, this is the "<hr>" element, and elsewhere it's a line consisting of a string of dashes.

Exit: Ignored.

Description

The Synthesize script is utilized when generating text output for a character dossier. A classic example is the creation of statblock output. When the user requests text output, he will also specify the style to be used when synthesizing the output (e.g. HTML, BBCode, or plain text). Before the script is invoked, HL will setup a number of appropriate mechanisms for that output style, which are provided via the various special symbols. For example, in HTML output, the "@boldon" special symbol will map to "<b>", while it will be "[b]" for BBCode output and do nothing for plain text output. This makes it possible for you to write a single Synthesize script that will generate output properly for each different style, without having to do any special handling within the script.

Unlike other scripts, the Synthesize script does not use a "@text" special symbol. Since the volume of output in some cases will be significant, using the standard approach simply isn't practical or efficient. Instead, the output is generated in sequential fashion, and the "append" language statement is used to accomplish this (see details). The "append" statement allows you to systematically construct the output, one section at a time. Once something is output, you can forget about it and let HL handle it.

If you need to do special formatting within a Synthesize script that is based on the output style, you can. You can find out the style by using the the "isdossierstyle" script target reference from within the State script context.

The Synthesize script starts with the actor to be output as its initial context. You can then cull whatever information you need from the actor for inclusion within the output.

NOTE!  The Synthesize script is read-only. Within this script, virtually all aspects of the structural hierarchy can be accessed, but nothing can be changed.

NOTE!  While within a Synthesize script and any procedures that are invoked, a global tag is automatically assigned by HL. The tag belongs to the "dossier" tag group and has the unique id of the dossier being output. This allows the script code to base its behavior on the actual dossier that the user is outputting.

Example

Every statblock starts with the character's name and then continues with other appropriate information that depends on the game system. The example below shows the start of a Synthesize script that includes the name, race, and age of the character.

var txt as string

~start by getting our name
if (empty(hero.actorname) = 0) then
  txt = hero.actorname
else
  txt = "Unnamed Character"
  endif

~output our name
append @boldon & "Name: " & @boldoff & txt & @newline

~output any race
txt = hero.firstchild["Race.?"].field[name].text
if (empty(txt) <> 0) then
  txt = "-none-"
  endif
append @boldon & "Race: " & @boldoff & txt & @newline

~output age
append @boldon & "Age: " & @boldoff & hero.child[mscPerson].field[perAge].text & @newline