advertisement
Getting Started Scripting terminology and the InCopy object model 15
Scripting terminology and the InCopy object model
Now that you created your first InCopy script, it is time to learn more about the terminology of scripting languages in general and InCopy scripting in particular.
Scripting terminology
First, let’s review a few common scripting terms and concepts.
Comments
Comments give you a way to add descriptive text to a script. The scripting system ignores comments as the script executes; this prevents comments from producing errors when you run your script. Comments are useful when you want to document the operation of a script (for yourself or someone else). In this document, we use comments in the tutorial scripts.
To include a comment in JavaScript, type
//
to the left of the comment, or surround the comment with
/* and
*/
. For example:
// this is a comment
/* and so is this */
Values
The point size of a text character, the contents of a note, and the filename of a document are examples of values used in InCopy scripting. Values are the data your scripts use to do their work.
The type of a value defines what sort of data the value contains. For example, the value type of the contents of a word is a text string; the value type of the leading of a paragraph is a number. Usually, the values used in scripts are numbers or text. The following table explains the value types most commonly used in InCopy scripting:
Value Type
Boolean
Integer
Number
String
Array
What it is
Logical True or False.
Example
True
Whole numbers (no decimal points). Integers can be positive or negative.
14
A high-precision number that can contain a decimal point.
A series of text characters. Strings appear inside (straight) quotation marks.
A list of values (the values can be any type).
13.9972
"I am a string"
["0p0", "0p0", "16p4", "20p6"]
Getting Started Scripting terminology and the InCopy object model 16
Converting values from one type to another
JavaScript provides ways to convert variable values from one type to another. The most common converstions involved converting numbers to strings (so you can enter them in text or display them in dialogs) or converting strings to numbers (so you can use them to set a point size or page location).
//To convert from a number to a string: myNumber = 2; myString = myNumber + "";
//To convert from a string to an integer: myString = "2"; myNumber = parseInt(myString);
//If your string contains a decimal value, use "parseFloat" rather than "parseInt": myNumber = parseFloat(myString);
//You can also convert strings to numbers using the following: myNumber = +myString;
Variables
A variable is a container for a value. They are called “variables” because the values they contain might change. A variable might hold a number, a string of text, or a reference to an InCopy object. Variables have names, and you refer to a variable by its name. To put a value into a variable, you assign the data to the variable.
In all examples and tutorial scripts that come with InCopy, all variables start with my
. This enables you to easily differentiate variables we created in a script from scripting-language terms.
Assigning a value to a variable
Assigning values or strings to variables is fairly simple, as shown in these examples: var myNumber = 10; var myString = "Hello, World!"; var myTextFrame = myDocument.pages.item(0).textFrames.add();
N OTE : In JavaScript, all variables not preceded by var
are considered global by default; that is, they are not bound to a specific function. While var is not required, we recommend that you use it in any script with more than one function.
Try to use descriptive names for your variables, like firstPage or corporateLogo , rather than x or c . This makes your script easier to read. Longer names do not affect the execution speed of the script.
Variable names must be one word, but you can use internal capitalization (like myFirstPage ) or underscore characters ( my_first_page
) to create more readable names. Variable names cannot begin with a number, and they cannot contain punctuation or quotation marks.
Array variables
An Array object is a container for a series of values: myArray = [1, 2, 3, 4];
To refer to an item in an array, refer to its index in the array.In JavaScript, the first item in an array is item 0: var myFirstArrayItem = myArray[0];
Arrays can include other arrays, as shown in the following examples: var myArray = [[0,0], [72,72]];
Getting Started Scripting terminology and the InCopy object model 17
Finding the value type of a variable
Sometimes, your scripts must make decisions based on the value type of an object. If you are working on a script that operates on a text selection, for example, you might want that script to stop if nothing is selected.
//Given a variable of unknown type, "myMysteryVariable"...
myType = myMysteryVariable.constructor.name;
//myType will be a string corresponding to the JavaScript type (e.g., "Rectangle")
Operators
Operators use variables or values to perform calculations (addition, subtraction, multiplication, and division) and return a value. For example:
MyWidth/2 returns a value equal to half of the content of the variable myWidth
.
You also can use operators to perform comparisons (equal to ( = ), not equal to( <> ), greater than ( > ), or less than (
<
)). For example:
MyWidth > myHeight returns the value true
(or 1) if myWidth
is greater than myHeight
; otherwise, false
(0).
In JavaScript, use the plus sign (
+
) to join the two strings:
"Pride " + "and Prejudice"
//returns the string: "Pride and Prejudice"
Conditional statements
“If the size of the selected text is 12 points, set the point size to 10 points.” This is an example of a conditional statement . Conditional statements make decisions; they give your scripts a way to evaluate something (like the color of the selected text, number of pages in the document, or date), then act according to the result. Most conditional statements start with if
.
Control structures
If you could talk to InCopy, you might say, “Repeat the following procedure 20 times.” In scripting terms, this is a control structure . Control structures provide repetitive processes, or loops . The idea of a loop is to repeat an action over and over again, with or without changes between instances (or iterations ) of the loop, until a specific condition is met. Control structures usually start with the for.
Functions
Functions are scripting modules to which you can refer from within your script. Typically, you send a value or series of values to a function and get back another value or values. There is nothing special about the code used in functions; they are simply conveniences to avoid having to type the same lines of code repeatedly in your script. Functions start with function .
advertisement