Introduction to JavaScript in PTC Arbortext Layout Developer
Before version 10.0, PTC Arbortext Layout Developer 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 Arbortext Layout Developer because it is interpreted rather than compiled. JavaScript is used for both PTC Arbortext Layout Developer formatting tags and automation, providing a common language for both parts of PTC Arbortext Layout Developer.
PTC Arbortext Layout Developer supports JavaScript version 1.8.1, which is provided by a customized version of the Mozilla TraceMonkey interpreter.
The following sections describe the PTC Arbortext Layout Developer tag types that support JavaScript and some of PTC Arbortext Layout Developer’s special JavaScript features.
Refer to
Overview of the Formatting Object Model for information about the FOM API.
JavaScript Tags
PTC Arbortext Layout Developer 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 Arbortext Layout Developer 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 Arbortext Layout Developer
The Formatting Object Model (FOM) describes a number of datatypes. These represent particular types of information that PTC Arbortext Layout Developer recognizes natively and FOM and JavaScript must understand. The datatypes describe information such as colors, lengths, and paths. PTC Arbortext Layout Developer’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 Arbortext Layout Developer recognizes the string red as the name of a color. It converts the string to an fColor object.
PTC Arbortext Layout Developer carries out an equivalent conversion for file location paths (converted to fPath object) and lengths (converted to fLength object).
The main datatypes in PTC Arbortext Layout Developer are:
• fLength — represents a length measurement
PTC Arbortext Layout Developer supports a number of different units, including custom units. The fLength object also takes a text property, for which PTC Arbortext Layout Developer 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 Arbortext Layout Developer 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 Arbortext Layout Developer.
Loading External JavaScript Files
Writing JavaScript inside PTC Arbortext Layout Developer 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 Arbortext Layout Developer, 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 Arbortext Layout Developer 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 Arbortext Layout Developer, 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 Arbortext Layout Developer 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.