PTC ALD in Arbortext Styler > Components of Documents and Templates > Creating New Content from the Main Content Stream > Running Headers > Creating Running Header References
Creating Running Header References
The first step in using running headers is to create is a running header reference. In PTC Arbortext Layout Developer, a reference is a special command that makes information available for use by a specific PTC Arbortext Layout Developer formatting process. Running header references make text information available for the running header process to use.
There are two ways in which information can be specified for running headers. It can either be specified explicitly, or it can be extracted from the text being formatted. The method of specifying the information explicitly is the most common, since tools such as XPath can be used. Extraction methods use regular expressions to locate an end point of the extraction process.
The fRunningHeaderReference FOM object represents running header references. It has a constructor for creating a new running header reference, for example:
var ref = new fRunningHeaderReference();
Once you have created the running header reference object, you can specify its properties. This example code provides the text for the running header explicitly:
var ref = new fRunningHeaderReference();
ref.groups = fRunningHeaderReference.GROUP_1;
ref.text = "My Running Header Text";
The example uses two properties:
fRunningHeaderReference.groups — specifies the running header groups for which this reference provides information
PTC Arbortext Layout Developer supports 10 concurrent running header groups. Running header references can specify information for one or more groups at the same time. The group values are listed on the fRunningHeaderReference.RunningHeaderReferenceGroups constant.
fRunningHeaderReference.text — specifies the string to be passed through the running header mechanism
In the example above the string is specified explicitly. The string could also be the result of an XPath expression, using formatting.evaluateXPath(), or the result of a function that returns a string.
Once the running header reference has been created, it must be added to the formatting process. The fFormatting FOM object provides the formatting.addReference() method for this purpose, for example:
The extraction method uses the other properties of the fRunningHeaderReference object:
fRunningHeaderReference.extractText — if true (boolean), instructs PTC Arbortext Layout Developer to extract information from the text under conditions set by the other properties
fRunningHeaderReference.items, fRunningHeaderReference.numItems — advise the words or characters to extract
fRunningHeaderReference.items - which items to extract, for example words or characters. The fRunningHeaderReference.RunningHeaderReferenceItems constant lists the values allowed for this property.
fRunningHeaderReference.numItems — the number of items to extract
if working with the extraction method and not using a regular expression, set the numitems property to a specific value, and the items property to the type of item to be extracted, that is, words or characters.
if using a regular expression, set the items property to fRunningHeaderReference.EXTRACT_YANK. In PTC Arbortext Layout Developer , a yank is an extraction using regular expressions, where the information is yanked from the text. Use the numItems property to specify the number of items. The text property (described in the next point) provides the regular expression.
fRunningHeaderReference.text — specifies the regular expression that identifies the end point of the extraction process
Use this property if the fRunningHeaderReference.extractText property is true and the fRunningHeaderReference.items property is set to fRunningHeaderReference.EXTRACT_YANK. For example, to extract up to the first # character:
ref.text = "/#/";
fRunningHeaderReference.characters —if true, PTC Arbortext Layout Developer only extracts alphanumeric characters and ignores items such as markup.
Use this property if the extraction is set to collect characters.
fRunningHeaderReference.allow — advises PTC Arbortext Layout Developer which other pieces of information it should extract, for example processing instructions, comments, or carriage returns. The allowed values are stored in the fRunningHeaderReference.RunningHeaderReferenceAllow constant.
Use this property if extracting text and the fRunningHeaderReference.characters property is set to false.
fRunningHeaderReference.streamHierarchy — confirms the level in the hierarchy of PTC Arbortext Layout Developer tags in which to perform the extraction. The main content stream is level 0, the default setting for the property.
Use this property if extracting text.