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:

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.

◦ 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:

• fRunningHeaderReference.characters —if true, PTC Arbortext Layout Developer only extracts alphanumeric characters and ignores items such as markup.

• 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.