Tag Properties and Operations
Tag Properties
In PTC Arbortext Layout Developer, most tag types share a common set of properties. Individual tag types also have properties that are specific to that tag type or group of tag types. Tags can be considered as a file within an PTC Arbortext Layout Developer document. As with files, tags have a name and an extension that denotes their type. They have other base properties, for example whether the tag is linked, and the target of the link, whether it is protected or read-only, and if it belongs to an PTC Arbortext Layout Developer namespace.
If a tag can be edited, it can be considered as a text stream. As with a text stream, more properties are available. It can be useful to treat a tag as a text stream and write raw information into it. Note that any information must be written in the correct format. Text streams (fStream object) have a large number of useful properties:
• size — the number of characters present in the tag, including markup and whitespace characters.
It is often useful to know the size of a tag, particularly when it has no content.
• Properties that are populated if the text stream contains XML:
◦ isXML — denotes whether the stream is recognized as XML
If a stream’s type is not one of the XML types (.xm or .xd), PTC Arbortext Layout Developer considers it as XML if the XML declaration appears at the top of the tag. Otherwise, this tag property can force PTC Arbortext Layout Developer to parse the stream as XML.
◦ xmlValidate — instructs PTC Arbortext Layout Developer to validate the stream
By default PTC Arbortext Layout Developer does not attempt to validate an XML instance, only to parse it into a tree.
◦ xmlParseError, xmlValidError — the code for the last parsing and validation errors (where applicable) are retained as a property of the stream when it is being considered as XML.
• Properties that control the behavior of whitespace characters to normalize space, tab, and line break characters, for example:
◦ ignoreSpaces — ignore trailing, leading, or multiple spaces
◦ mapReturns — map carriage returns to other items such as spaces
• Transformation types that can be used to create or populate a stream. These properties are part of the target stream rather than the source stream, which might have multiple transformations applied.
◦ transformSource — the source stream used to create the current stream
◦ transformType — the type of transformation that generates the contents of the stream
PTC Arbortext Layout Developer tags can be transformed using XSLT, Perl scripts, search and replace scripts, SAX, or even a simple direct clone.
◦ transformCtrl — the PTC Arbortext Layout Developer tag that is being used to control the transformation
◦ transformParams — any parameters can be passed to the transformation process, defined in a control stream
◦ transformFrequency — how often to run the transformation
It can be set to run automatically, on demand, or just once.
• Properties that facilitate the editing of the stream, for example:
◦ currentPos — the current cursor position in the stream
◦ recordUndo — whether undo is enabled
It is recommended that undo is disabled if writing to many streams, to improve performance.
◦ recordRevMarks — Whether change tracking is enabled
PTC Arbortext Layout Developer has a change tracking capability which can be applied to individual text streams
◦ isEncrypted — whether the tag is encrypted
Graphic tags have some useful properties. Object graphics (fGraphic object) only store the height and width, but raster graphics (fRaster object) have more properties, for example:
• height and width
The height and width of the original graphic are useful in determining the scaling to be applied or whether to use a landscape or portrait display.
• fileType and filename
• isMirrored, isFlopped, rotation — PTC Arbortext Layout Developer allows raster graphics to be rotated, mirrored, or flopped. This information is stored.
• page — the page in a PDF from the raster graphic was imported, if using the PDF import feature
Tag Operations or Methods
PTC Arbortext Layout Developer tags can be considered as separate files within a document. Tag management operations are available, for example the following methods described for the fTag object:
• copyTag() — copy the contents of the tag to a new tag
Copying takes all content and some of the tag’s properties and creates a new tag with the supplied name.
• deleteTag() — delete the tag and its content
• renameTag() — rename the tag
Renaming also includes moving the tag to a namespace and changing the type of the tag. A rename action updates any references to the tag in existing pages or frames.
If a tag is being treated as a text stream, some useful operations are available for the fStream object:
• read() and write() — read or write text to the stream
This can be used together with operations to move to a specific location within the stream, using JavaScript or PTC Arbortext Layout Developer’s proprietary macro commands.
• clear() — clear the text stream, removing all content
• save() — save the contents of a stream to an external file
• run() — run the contents of a stream, if the stream is one of the script tag types
• load() — load the contents of an external file into the tag