Introduction to JavaScript in PTC Advanced Print Publisher
Before version 10.0, PTC Advanced Print Publisher only supported either its own proprietary macro and processing instruction language, or Perl, for template development.
Version 10 (released June 2011) introduced JavaScript and the Formatting Object Model (FOM) API, with this language also supported in the Arbortext Styler integration. JavaScript is an excellent fit for PTC Advanced Print Publisher because it is interpreted rather than compiled. JavaScript is used for both PTC Advanced Print Publisher formatting tags and automation, providing a common language for both parts of PTC Advanced Print Publisher.
PTC Advanced Print Publisher supports JavaScript version 1.8.1, which is provided by a customized version of the Mozilla TraceMonkey interpreter.
The following sections describe the PTC Advanced Print Publisher tag types that support JavaScript and some of PTC Advanced Print Publisher’s special JavaScript features.
Refer to
Overview of the Formatting Object Model for information about the FOM API.
JavaScript Tags
PTC Advanced Print Publisher provides two Javascript tags, script tags (.Js tag type) and function tags (.Jf tag type). There is not much difference between the two tag types, although it is recommended that you separate uses of the tags as follows:
• Script tags (.Js) — use for automation
To run a JavaScript script, the fContent.runStream() method allows this:
template.content.runStream("myScriptTag");
where myScriptTag is the name of the JavaScript script tag.
• Function tags (.Jf) — use for formatting
Function tags are executed as a JavaScript function, which ensures that any variables declared in the function remain local to that function. As functions, arguments can be passed to JavaScript function tags and they can be called as functions from within other code.
To call an PTC Advanced Print Publisher JavaScript function tag as a function, use:
template.content.functions.myFunctionTag();
where myFunctionTag is the name of the JavaScript function. fContent.functions is a list of the .Jf tags in the template. Arguments can be passed this way.
Datatypes in PTC Advanced Print Publisher
The Formatting Object Model (FOM) describes a number of datatypes. These represent particular types of information that PTC Advanced Print Publisher recognizes natively and FOM and JavaScript must understand. The datatypes describe information such as colors, lengths, and paths. PTC Advanced Print Publisher’s implementation of JavaScript attempts to convert a particular object property with a value to the correct datatype, outputting a message if the conversion is not possible.
So, for example, with the declaration frame.backgroundColor("red");PTC Advanced Print Publisher recognizes the string red as the name of a color. It converts the string to an fColor object.
PTC Advanced Print Publisher carries out an equivalent conversion for file location paths (converted to fPath object) and lengths (converted to fLength object).
The main datatypes in PTC Advanced Print Publisher are:
• fLength — represents a length measurement
PTC Advanced Print Publisher supports a number of different units, including custom units. The fLength object also takes a text property, for which PTC Advanced Print Publisher returns a value equivalent to the formatted length of that string.
• fPath — represents a file location path
fPath can be broken down into filename, extension, device, and so on. If you create a new fPath and give it a string such as D:/folder/myFile.txt, PTC Advanced Print Publisher can decompose it into an fPath object with separate properties.
• fColor — represents a color
fColor can accept RGB and CMYK values as well as names of colors recognized by PTC Advanced Print Publisher.
Loading External JavaScript Files
Writing JavaScript inside PTC Advanced Print Publisher can be difficult since it is not a code development environment. PTC supplies, or can supply, code completion libraries for the JSDT JavaScript plug-in for Eclipse. The libraries provide object definitions and documentation for the Formatting Object Model.
For code developed outside PTC Advanced Print Publisher, the fApplication.loadJS() method allows the loading and running of an external JavaScript file.
To create a tag in a template from an external JavaScript file, use the fContent.importJS() method as shown in this example:
var js;
js = template.content.getStream("myJS");
if (!js) {
var p = new fPath("D:/myJavaScriptFile.js");
template.content.importJS("myJS", p, false, true);
}
template.content.runStream(js);
In this example, the fContent.getStream() method verifies if a tag of the given name exists. If not, the external file is loaded from a path specified in an fPath object. The importJS() method takes four arguments:
• a file name
• a path
• arguments to confirm whether to load the file as a linked file (false) and whether to create a JavaScript function tag (true)
The last line of the example uses the fContent.runStream() method to run the imported JavaScript file.
File Access Using JavaScript
Typical JavaScript implementations do not provide file access, primarily for reasons of security. However, PTC Advanced Print Publisher has exposed file handling capabilities provided by Mozilla. Note that the capabilities are hidden from web browser implementations.
The Formatting Object Model provides a File object (NOT fFile) that provides access to external files. File access can allow users to create and manage external files and directories and read and write to those files. Creating a new File object automatically points to the current location of the installation of PTC Advanced Print Publisher, although it is possible to specify a different location. For example, this code creates a new external text file at the same location as the PTC Advanced Print Publisher document:
var current = File(template.path.resolve()).parent;
var file = new File(current + "/myFile.txt");
The first line sets the current variable to the parent folder of the current template location path. The second line creates a new file at that location, with the name myFile.txt. From here, the file can be opened using:
file.open("write, create","text");
where the File.open() method takes a number of parameters that define how that file is opened and its type. For more information on this feature, refer to the File object documentation.