FISH Variables
Introduction
Format Inheritable String Hash (FISH) variables share some characteristics with string counters — they both hold strings and they are both format safe. FISH are more useful than string counters and can be used for tracking complex information.
In PTC Arbortext Layout Developer, FISH are grouped in buckets (hashes). Five independent containers are available for storing any number of variables. When using or referring to FISH variables you must use the bucket number.
|
|
The Arbortext Styler integration uses the first two buckets (0 and 1) to track information. These must not be referenced in source edits.
|
Individual FISH variables are referred to by name. The same name can be used in different buckets. If a FISH variable has not been declared, PTC Arbortext Layout Developer does not output an error if it is used. If the variable has not been set, PTC Arbortext Layout Developer returns an empty string.
The main difference between FISH variables and string counters is that FISH can save and restore their values. For example, when formatting a document you can instruct PTC Arbortext Layout Developer to save the values of FISH variables in a bucket, carry out tasks based on their values, then restore them to the original values from the last save. Properties or values can be tracked through an XML hierarchy, with a bucket saved when entering a context, and subsequently restored when exiting the context. FISH buckets can be saved as many times as required so that they can be stacked to multiple levels. Note that buckets are not restored automatically. The template designer must ensure that restore actions are completed for each level of save.
Using FISH in JavaScript
This example code sets a FISH variable to a value:
formatting.fish[2].fishName = "hello";
where [2] refers to bucket number 2 (the third bucket, as numbering starts at 0). fishName is the name of the FISH variable being set. A variable can have any name, but if you want to use odd characters or spaces in a FISH name, declare it as shown:
formatting.fish[2]["fish name"] = "hello spaces";
This example saves bucket number 2 of FISH variables, to allow them to be restored later:
formatting.fishSave(2);
This example restores bucket number 2:
formatting.fishRestore(2);
The values of all FISH variables in bucket 2 will be restored to the values they had at the last formatting.fishSave(2) action. If new FISH variables were created in the bucket after the last save, their values will be empty after the restore.
The formatting.fishGet() method is exposed through JavaScript. When many levels of stacking have resulted from multiple formatting.fishSave() commands, formatting.fishGet() allows you to extract the value of the FISH variable from a specified number of levels. For example:
formatting.fishGet(2,"fishName",1);
This example returns the value of the variable named fishName in bucket 2, but only from the current and parent levels in the stack hierarchy. The final parameter indicates the number of hierarchy levels to search, starting from 0 for the current level. The nearest value, that is the most recently set, is returned.
Best Practices
• When using PTC Arbortext Layout Developer from the Arbortext Styler integration, do not use FISH buckets 0 and 1. Arbortext Styler uses these to track specific properties. Bucket 0 will be saved and restored when entering and exiting contexts — if you wish to add custom FISH that follow this behavior, use existing save and restore commands. Take care when naming your FISH variables.
• Use different buckets of FISH to track different groups of values to save and restore at different points.
