WIXLIB

Adobe InDesign CS3 Scripting TutorialGetting Started6Many applications contain Visual Basic for Applications (VBA), like Microsoft Word, Microsoft Excel,Microsoft Visio, or AutoCAD. Although you can use VBA to create InDesign scripts, InDesign does notinclude VBA.To use VBScript or Visual Basic for InDesign scripting in Windows XP, you must install InDesign from a useraccount that has Administrator privileges. After you complete the installation, any user can run InDesignscripts, and any user can add scripts to the InDesign Scripts panel.Which Scripting Language should you use?If you have written scripts before, use whatever language you know. If you have never written scriptsbefore or if you need to make your scripts work on both the Mac OS and Windows versions of InDesign,use JavaScript. If you need to communicate with other, non-Adobe applications on your system, use theappropriate, platform standard language (AppleScript on Mac OS or VBScript in Windows).We cannot fully document the language features of AppleScript, JavaScript, or VBScript, so you may needdocumentation for any or all those scripting languages.Note: You also can use almost any other programming language (like Python or C#) that can connect tothe platform standard automation system; that is beyond the scope of this document.How to use the Scripts in this DocumentTo use any script from this document, either open the tutorial script file (the filename is given before eachscript) or follow these steps:1. Copy the script from this Adobe PDF document and paste it into your script editor, such as theExtendScript Toolkit (for JavaScript examples), the Apple Script Editor (for AppleScript examples), or atext editor like Notepad (for VBScript examples).2. Save the script as a plain text file in the Scripts Panel folder (see “Installing Scripts” on page 4), usingthe appropriate file BScript:.vbs3. Choose Windows Automation Scripts, to display the Scripts panel.4. Double-click the script name in the Scripts panel, to run the script.Note: If you are entering the JavaScript examples, it is very important to use the same capitalizationshown in the example. JavaScript is case-sensitive, and the scripts will fail if they do not use thecapitalization shown. The AppleScript and VBScript examples are not case-sensitive.Note: If you are copying and pasting scripts from this document, be aware that line breaks caused by thelayout of the document can cause errors in your script. As it can be very difficult to find such errors,we recommend hat you use the scripts in the zip archive.

Adobe InDesign CS3 Scripting TutorialGetting Started7Your First InDesign ScriptNext, we will create an InDesign script that creates a new document, adds a text frame, and enters text inthe text frame. This demonstrates how to do the following: Establish communication with InDesign. Create a new document. Create a text frame on a specific page. Add text to a text frame.AppleScriptStart the Script Editor application (you can find it in your Applications folder, inside the AppleScript folder).Enter the following script (or open the HelloWorld.applescript tutorial script):tell application "Adobe InDesign CS3"set myDocument to make documenttell page 1 of myDocumentset myTextFrame to make text frameset geometric bounds of myTextFrame to {"6p", "6p", "24p", "24p"}set contents of myTextFrame to "Hello World!"end tellend tellSave the script as text with the file extension .applescript to the Scripts Panel folder (see “InstallingScripts” on page 4). To run the script, double-click the script name in the Scripts panel or click the Runbutton in the Script Editor window.JavaScriptStart the ExtendScript Toolkit (or a text editor). Enter the following script (or open the HelloWorld.jsxtutorial script):var myDocument app.documents.add();var myTextFrame ame.geometricBounds ["6p", "6p", "24p", "24p"];myTextFrame.contents "Hello World!";Save the script as a plain-text file with the .jsx file extension to the Scripts Panel folder (see “InstallingScripts” on page 4). To run the script, double-click the script name in the Scripts panel, or select InDesignfrom the application target pop-up menu in the ExtendScript Toolkit and then click the Run button).VBScriptStart a text editor (e.g., Notepad) and enter the following script (or open the HelloWorld.vbs tutorialscript):Set myInDesign CreateObject("InDesign.Application.CS3")Set myDocument myInDesign.Documents.AddSet myTextFrame .GeometricBounds Array("6p", "6p", "24p", "24p")myTextFrame.Contents "Hello World!"Save the script as a text file with the .vbs file extension to the Scripts Panel folder (see“Installing Scripts”on page 4). To run the script, double-click the script name in the Scripts panel.

Adobe InDesign CS3 Scripting TutorialScripting and the InDesign Object Model8Walking through the ScriptExamining the script presented above, here is a step-by-step analysis of what the script does (in eachscripting language):1. Establish communication with the InDesign application object:AppleScript:tell application "Adobe InDesign CS3"JavaScript:Refer to the application as app.VBScript:Set myInDesign CreateObject("InDesign.Application.CS3")2. Create a new document and a reference to the document:AppleScript:Set myDocument to make documentJavaScript:Var myDocument app.documents.add();VBScript:Set myDocument myInDesign.Documents.Add3. Create a new text frame on the first page and a create a reference to the text frame.:AppleScript:tell page 1 of myDocumentset myTextFrame to make text frameJavaScript:var myTextFrame :Set myTextFrame myDocument.Pages.Item(1).TextFrames.Add4. Set the geometric bounds (the location of the top, left, bottom, and right edges) of the text frame. Inthis step, the script uses measurement overrides (“p” for picas) to ensure the text frame is the correctsize, regardless of your default measurement units. The locations are provided as a list, or array, of values; each scripting language has a slightly different way of creating an array. For more on array variables, see “Array Variables” on page 11.AppleScript:set geometric bounds of myTextFrame to {"6p", "6p", "24p", "24p"}JavaScript:myTextFrame.geometricBounds ["6p", "6p", "24p", "24p"];VBScript:myTextFrame.GeometricBounds Array("6p", "6p", "24p", "24p")5. Add text to the text frame by setting the contents property to a string.:AppleScript:set contents of myTextFrame to "Hello World!"JavaScript:myTextFrame.contents "Hello World!";VBScript:myTextFrame.Contents "Hello World!"Scripting and the InDesign Object ModelThis section discusses the terminology of scripting languages in general and InDesign scripting inparticular.Scripting TerminologyThis section discusses common scripting terms and concepts.

Adobe InDesign CS3 Scripting TutorialScripting and the InDesign Object Model9CommentsComments give you a way to add descriptive text to a script. The scripting system ignores comments asthe script executes; this prevents comments from producing errors when you run your script. Commentsare useful to document the operation of a script (for yourself or someone else). In this document, we usecomments in the tutorial scripts.To include a comment in an AppleScript, type -- to the left of your comment or surround the commentwith (* and *). In VBScript, type Rem (for “remark”) or ' (a single straight quote) to the left of thecomment. Type the comment marker at the beginning of a line, to make the entire line a comment. InJavaScript, type // to the left of the comment, or surround the comment with /* and */. For example:AppleScript:--this is a comment* and so is this *)JavaScript:// this is a comment/* and so is this */VBScript:Rem this is a comment' and so is thisValuesThe point size of a character of text, the location of a text frame on a page, and the color of stroke of arectangle are examples of values used in InDesign scripting. Values are the data your scripts use to do theirwork.The type of a value defines what sort of data the value contains. For example, the value type of thecontents of a word is a text string, and 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 mostcommonly used in InDesign scripting:Value TypeWhat it isExampleBooleanLogical True or False.TrueIntegerWhole numbers (no decimalpoints). Integers can be positiveor negative. In VBScript, you canuse the long data type forintegers. In AppleScript, youalso can use the fixed or longdata types for both integers andreal numbers.14Double (VBScript),fixed or real(AppleScript),floating point(JavaScript)A high-precision number thatcan contain a decimal point.13.9972StringA series of text characters.Strings appear inside (straight)quotation marks."I am a string"

Adobe InDesign CS3 Scripting TutorialScripting and the InDesign Object ModelValue TypeWhat it isExampleArray (VBScript,JavaScript)or list (AppleScript)A list of values (the values canbe any type).{"0p0", "0p0", "16p4", "20p6"}10AppleScript:VBScript:Array("0p0", "0p0", "16p4", "20p6")JavaScript:["0p0", "0p0", "16p4", "20p6"]Converting Values from one Type to AnotherAll scripting languages supported by InDesign provide ways to convert variable values from one type toanother. The most common conversions involve converting numbers to strings (so you can enter them intext or display them in dialog boxes) or converting strings to numbers (so you can use them to set a pointsize or page location). See the examples below.AppleScript:--To convert from a number to a string:set myNumber to 2set myString to (myNumber as string)--To convert from a string to a number:set myString to "2"set myNumber to (myString as integer)--if your string contains a decimal value, use "as real" rather than "as integer"JavaScript://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;VBScript:Rem To convert from a number to a string:myNumber 2myString cstr(myNumber)Rem To convert from a string to an integer:myString "2"myNumber cInt(myString)Rem If your string contains a decimal value, use "cDbl" rather than "cInt":myNumber cDbl(myString)

Adobe InDesign CS3 Scripting TutorialScripting and the InDesign Object Model11VariablesA variable is a container for a value. They are called “variables” because the values they contain mightchange. A variable might hold a number, a string of text, or a reference to an InDesign object. Variableshave names, and you refer to a variable by its name. To put a value into a variable, you assign the data tothe variable.In our first sample script, above, we used the variables myDocument and myTextFrame to avoid having toprovide the full specification of the object (such as text frame 1 of page 1 of document 1 tem(0)) every time we refer to the object.In all the sample and tutorial scripts that come with InDesign, all variables start with my. This way, you caneasily differentiate variables we created in a script from the scripting language terms.Assigning a Value to a VariableAssigning values or strings to variables is fairly simple, as shown in the following table:LanguageExamples of Assigning a Value to a VariableAppleScriptset myNumber to 10set myString to "Hello, World!"set myTextFrame to make text frame at page 1 of myDocumentJavaScriptvar myNumber 10;var myString "Hello, World!";var myTextFrame myNumber 10myString "Hello, World!"Set myTextFrame myDocument.Pages.Item(1).TextFrames.AddNote: In JavaScript, all variables not preceded by var are considered global by default; that is, they are notbound to a specific function. var is not required, but we recommend you use var in any script withmore than one function. In AppleScript and VBScript, variables are local unless specifically definedas global variables. This means the variables do not persist outside the function in which they arecreated.Try to use descriptive names for your variables, like firstPage or corporateLogo, rather than x or c. Thismakes 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 (myFirstPage) or underscorecharacters (my first page) to create more readable names. Variable names cannot begin with anumber, and they cannot contain punctuation or quotation marks.Array VariablesAppleScript, JavaScript, and VBScript support arrays, which is a variable type that is a list of values. InAppleScript, an array is called a list. Examples of defining arrays are shown below:

Adobe InDesign CS3 Scripting TutorialLanguageExamples of Defining ArraysAppleScriptset myArray to {1, 2, 3, 4}JavaScriptmyArray [1, 2, 3, 4];VBScriptmyArray Array(1, 2, 3, 4)Scripting and the InDesign Object Model12Rem In Visual Basic.NET: myArray New Double (1, 2, 3, 4)To refer to an item in an array, refer to the item by its index in the array. The first item in an array in VBScriptand JavaScript is item 0; in AppleScript, item 1. Examples of referring to items in an array are shown below:LanguageExamples of Referring to an Item in an ArrayAppleScriptset myFirstArrayItem to item 1 of myArrayJavaScriptvar myFirstArrayItem myArray[0];VBScriptmyFirstArrayItem myArray(0)Note: The Visual Basic OptionBase statement can be used to set the first item of an array to item 1. In theexamples in this document, the first item in an array is item 0, not item 1, because that is the default.If you set OptionBase to 1, you must adjust all array references in the sample scripts accordingly.Arrays can include other arrays, as shown in the following table:LanguageExamplesAppleScriptset myArray to {{0, 0}, {72, 72}}VBScriptmyArray Array(Array(0,0), Array(72, 72))Rem In Visual Basic.NET: myArray New Array(New Double(0,0),NewDouble (0,0))JavaScriptvar myArray [[0,0], [72,72]];Finding the Value Type of a VariableSometimes, your scripts must make decisions based on the value type of an object. For example, if you areworking on a script that operates on a text selection, you might want that script to stop if the type of theselection is a page item. All the scripting languages allow you to determine the type of a variable.AppleScript:-- Given a variable of unknown type, "myMysteryVariable".set myType to class of myMysteryVariable--myType will be an AppleScript type (e.g., rectangle)JavaScript://Given a variable of unknown type, "myMysteryVariable".myType myMysteryVariable.constructor.name;//myType will be a string corresponding to the JavaScript type (e.g., "Rectangle")

Adobe InDesign CS3 Scripting TutorialScripting and the InDesign Object Model13VBScript:Rem Given a variable of unknown type, "myMysteryVariable".myType TypeName(myMysteryVariable)Rem myType will be a string corresponding to the variable type (e.g., "Rectangle")OperatorsOperators use variables or values to perform calculations (addition, subtraction, multiplication, anddivision) and return a value. For example:MyWidth/2This 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 lessthan( ). For example:MyWidth myHeightThis returns true (or 1) if myWidth is greater than myHeight; otherwise, false (0).All the scripting languages provide additional utility operators. In AppleScript and VBScript, theampersand (&) concatenates (or joins) two strings:"Pride " & "and Prejudice"This returns the following string:"Pride and Prejudice"In JavaScript, use the plus sign ( ) to join the two strings:"Pride " "and Prejudice"//returns the string: "Pride and Prejudice"Conditional Statements“If the selected object is a rectangle, set its stroke weight to 12 points.” This is an example of a conditionalstatement. Conditional statements make decisions; they give your scripts a way to evaluate something (likethe color of the selected object, the number of pages in the publication, or the date) and act based on theresult. Conditional statements almost always start with if.Note: Conditional statements often make logical comparisons. In AppleScript and VBScript, use theequals sign ( ) to compare objects. In JavaScript, the equals sign assigns a value to a variable; tocompare objects, use a double equals sign ( ).Control StructuresIf you could talk to InDesign, 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 torepeat an action over and over, with or without changes between instances (or iterations) of the loop, untila specific condition is met. Control structures usually start with repeat (in AppleScript) or for (inJavaScript and VBScript).

Adobe InDesign CS3 Scripting TutorialScripting and the InDesign Object Model14Functions and HandlersFunctions (in VBScript or JavaScript) or handlers (in AppleScript) are scripting modules you can refer towithin your script. Typically, you send a value or series of values to a function (or handler) and get backsome other value or values. The code used in functions and handlers is simply a convenience to avoidhaving to type the same lines of code repeatedly in your script.In AppleScript, handlers start with on. In JavaScript and VBScript, functions start with function.Understanding the InDesign Object ModelWhen you think about InDesign and InDesign documents, you probably organize the program and itscomponents in your mind. You know paragraphs are contained by text frames which, in turn, appear on apage. A page is a part of a spread, and one or more spreads make up a document. Documents containcolors, styles, layers, and master spreads. As you think about the layouts you create, you intuitivelyunderstand there is an order to them.InDesign “thinks” about the contents of a document in the same way. A document contains pages, whichcontain page items (text frames, rectangles, ellipses, and so on). Text frames contain characters, words,paragraphs, and anchored frames; graphics frames contain images, EPS files, or PDF files; and groupscontain other page items. The things we mention here are the objects that make up an InDesignpublication, and they are what we work with when we write InDesign scripts.Objects in your publication are arranged in a specific order: frames are on pages, which are inside adocument, which is inside the InDesign application object. When we speak of an object model or ahierarchy, we are talking about this structure. Understanding the object model is the key to finding theobject you want to work with, and your best guide to InDesign scripting is your knowledge of InDesignitself.Objects have properties (attributes). For example, the properties of a text object include the font used toformat the text, the point size, and the leading applied to the text.Properties have values; for example, the point size of text can be either a number (in points) or the string“Auto” for auto leading. The fill color property of text can be set to a color, a gradient, a mixed ink, or aswatch.Properties also can be read/write or read only. Read/write properties can be set to other values; read onlyproperties cannot.Objects also have methods—the verbs of the scripting world, or the actions an object can perform. Forexample, the document object has print, export, and save methods.Methods have parameters, or values that define the effect of the method. For example, the place methodof a documen

Adobe InDesign CS3 Scripting Tutorial Getting Started 4 Installing Scripts Installing an InDesign script is easy: put the script file in the Scripts Panel folder inside the Scripts folder in your InDesign application folder. (Create the Scripts folder if it does not already exist.)