Basic Text Streams
Introduction
Text streams are the basic content holders for text in PTC Advanced Print Publisher. They appear as tags of type .tx tags in documents. Text streams can be created dynamically and have content added easily. They can be used to hold pieces of content during the formatting process, for reuse elsewhere. Page frames can hold text streams. There is no restriction to the amount of content that a text stream can hold, or to the type of content. There is also no restriction on the number of content streams that can exist in a document, outside any memory usage restrictions. By default, text stream content is encoded in UCS2 when using the Unicode version of PTC Advanced Print Publisher. The Unicode version is used in the Arbortext Styler integration.
A text stream attempts to build an XML DOM if the stream starts with the XML declaration
<?xml version=”1.0”?>. If the content is well formed,
PTC Advanced Print Publisher constructs a read-only XML DOM. XPath and XSLT can be performed against this DOM. The content does not need to be valid to have the DOM created. In contrast, XML streams try to build an XML DOM by default. See
XML Content Streams for information.
PTC Advanced Print Publisher provides methods for creating and manipulating content streams, using script- or UI-based methods.
Text Streams and JavaScript
In the Formatting Object Model (FOM), the fStream object represents all text stream types. This object inherits the fTag object, so all the properties and methods of fTag are available to fStream. The fStream object is the text representation of any PTC Advanced Print Publisher tag that can be edited manually in PTC Advanced Print Publisher.
The fStream object is described in the Content group of FOM objects. The fContent object provides properties and methods for accessing and manipulating text streams.
Refer to
Content Streams for some common properties of text streams.
Refer to
Tag Properties and Operations for some common properties of tags.
Creating New Content Streams and Adding New Content
During formatting, it is often useful to create new content streams and write information to them. These content streams can then be reused, and have formatting applied to their content using markup. The reuse of content in streams has multiple potential uses, for example:
• provide new content for new frames
• output inline content
• generate reports
• debug templates
This example code creates a new text content stream:
var myStream = template.content.createStream("contentTag", fTag.TYPE_TEXT);
where contentTag is the name of the tag that is created for the text stream. fTag.TYPE_TEXT is the constant value for the .tx tag type held by the fTag object. The template.content.createStream() method returns an fStream object.
An alternative method of creating a new stream checks if the required tag exists before creating the new one:
var myStream;
myStream = template.content.getStream("contentTag");
if (!myStream) myStream = template.content.createStream("contentTag", fTag.TYPE_TEXT);
In this example, the getStream() method on the fContent object attempts to retrieve the named tag. If the method returns null, the tag does not exist and the request to create the new content stream can be completed.
Methods on the fStream object are provided to read and write to the text stream. As tags can be considered as individual files in a document, the methods are similar to file access actions:
• read() — reads the contents of the stream. The method has a parameter numChars that indicates the number of characters to be read.
• readln() — reads a line of content from the stream up to the next hard return character
• write() — writes the provided content into the stream at the current position
You can use the seek() method to specify the cursor position.
• writeEscaped() — writes special characters to their escaped versions (entities)
• clear() — clears the content stream of all its contents
Loading External Content into the PTC Advanced Print Publisher Document
The fContent and fStream objects both provide methods for loading content into a document:
• The fContent object provides the importText() method for loading new content into your document. This sample code creates a new text stream object that contains text from an external file:
var path = new fPath("D:/myFile.txt");
var newStream = template.content.importText("newContent", path, false);
where the parameter “newContent” is the name of the new tag that is created. The path parameter is an fPath object. The fPath declaration can also specify any options to import the content in a specific encoding. The false parameter specifies that the action should not create a link to the external file — use true if you do want to create a link.
A parameter that represents import options is also allowed with importText(). This example does not include the parameter so the load action deviates from the default requirement of exact copy.
• The fStream object provides the fStream.load() method for loading content into an existing tag. It is similar to the fContent.importText() method, but it does not include a tag parameter. This sample code loads content into the existing tag myContent:
var path = new fPath("D:/myFile.txt");
var stream = template.content.getStream("myContent");
stream.load(path, false);
where the parameter “myContent” is the name of the existing tag.
The method includes the option to add the same import parameters as fContent.importText().
Exporting Content Streams
You can export a content stream to a file from PTC Advanced Print Publisher. This can be useful if you are using a content stream to hold a report or to generate content. The save() method of the fStream object provides this functionality. This sample code exports the content stream myContent:
var path = new fPath("D:/myNewFile.txt");
var stream = template.content.getStream("myContent");
stream.save(path, false);
In this example, the path parameter defines the target file for saving the content. The second parameter false specifies that markup should not be stripped from the output — use true if you do not want to remove markup.
Text Streams and Whitespace
When PTC Advanced Print Publisher formats a content stream, by default whitespace is displayed as it appears in the content stream. This can give unexpected results if hard returns, spaces, and tabs are used to lay out the text. PTC Advanced Print Publisher treats hard returns as a trigger for resetting formatting properties. Tabs are treated as tabs to push content along to the next tab stop.
PTC Advanced Print Publisher text streams have three properties that control how white space is interpreted:
• fStream.mapReturns — whether to interpret return characters as returns or spaces
• fStream.mapTabs — whether to interpret tab characters as tabs or spaces
• fStream.ignoreSpaces — how to handle space characters that appear in different places. For example, leading and trailing spaces can be ignored, and multiple spaces can be compressed to a single space.
Set these values on a stream when you create it to save confusion when the content stream is displayed. For example:
var stream = template.content.getStream("myContent");
stream.mapReturns = fStream.MAP_RETURNS;
stream.mapTabs = true;
stream.ignoreSpaces = fStream.IGNORE_START + fStream.IGNORE_MULTIPLE + fStream.IGNORE_END;
|
|
The whitespace properties only affect the formatted output, not the content of the text stream itself.
|
The fFormatting object includes inline versions of these properties, which allow the whitespace settings to be changed dynamically while formatting.
It is possible to specify whitespace handling in a strip space control stream, which can determine whether whitespace is meaningful.
Best Practices
• When creating a new content stream, always test if stream exists before creating it.
• Use PTC Advanced Print Publisher’s whitespace stream settings to ensure white space is normalized in content streams.
