InDesign CS Scripting Changes
InDesign CS has introduced a large number of changes in scripting. Some things are new, some are simple changes in terminology, and some are changes that will break existing scripts. This is a guide to some of these changes, and is designed primarily to help in moving scripts written for version 2.0.2 to CS. This article by Shane Stanley is a preview of what will be covered November 9 at the AppleScript Pro Sessions in Newport, Rhode Island.
It is not exhaustive, by any means, but is intended as a good place to start. The emphasis is on things that have changed and might therefore cause existing scripts to break, rather than new features. Details will be added as time permits, so it's probably worthwhile checking back here regularly.
"Graphic" Class
In v2, "page item" was a superclass that included things like rectangles, text frames, ovals, etc, as well as things that couldn't actually exists on pages, such as images, PDFs, EPSes, etc. In CS, these latter items are no longer considered page items, but are part of a new superclass called "graphic". So if your script gets a reference to a picture using something like:
set thePic to page item 1 of rectangle 1
you would now change that to:
set thePic to graphic 1 of rectangle 1
Along with this change, documents, spreads, pages and master pages have a new property, "all graphics", which is analogous to "all page items" -- it returns a list of all the graphics contained by the item, and by any items contained by the item.
Text Handling Changes
One of the big changes in CS is improved handling of ranges, and this could cause problems with scripts that deal with text. In v2, text ranges had to be defined by character offsets, and would typically be in the form:
characters x to y
This would return a substring. Confusingly, the same thing in raw AppleScript would return a list of the characters (character 2 thru 6 of "Some text" -> {"o", "m", "e", " ", "t"}).
In CS, using "characters x to y" will also return a list of the characters. To get a substring, you use the normal AppleScript form:
text from character x to character y
In addition, ranges are no longer limited to characters – you can use words, paragraphs, and so on. For example:
text from character 2 to word 5
text from word 2 to paragraph -1
Making Groups
Under v2, you made a group something like:
make group at page 1 with data {list of the page items}
Under CS, you use the form:
make group at page item with properties {group items:{list of the page items}}
You can of course set other properties at the same time. Ungrouping is unchanged.
Improved Creation Targets
In CS, you can now specify where page items are created. For example:
make rectangle at end of page 1
will create a rectangle at the "back" of a page, and:
make rectangle at after page item 1 of page 1
will create a rectangle that is behind the frontmost existing page item.
Similarly, you can specify where a page or spread should be created:
make page at end
make page at before page 1
You can also refer to ranges of items:
pages 3 thru -1
rectangles 3 thru 7 of page 1
Export Changes
There have been a few changes in this area. First, you can now set the preferences for EPS exports:
tell application "InDesign CS"
set myFlattenerStyle to flattener preset "[High Resolution]"
set properties of EPS export preferences to {bleed bottom:0.0, bleed inside:0.0, bleed outside:0.0, bleed top:0.0, data format:ASCII, PostScript level:level 2, applied flattener preset:myFlattenerStyle, ignore spread overrides:false, OPI image replacement:false, omit bitmaps:false, omit EPS:false, omit PDF:false, EPS color:CMYK, preview:TIFF preview, EPS spreads:false, font embedding:subset, image data:all image data, page range:"1"}
export document 1 format EPS type to "Macintosh HD:Sample.eps" without showing options
end tell
With PDF exports, the "page range" property has been removed from the "PDF export preset" class (formerly known as the "PDF export style" class). The page range is now always set by addressing the "PDF export preference" object.
And a new class, "JPEG export preference", has been added to the application object for JPEG exports.
Master Page Changes
In v2, master page items were overriden simply by referring to them:
tell application "InDesign 2.0.2"
tell document 1
tell page 1
master page item 1 -- returns reference to page item
end tell
end tell
end tell
In fact, the above will override the backmost page item (-1) on the master page.
With CS, a new command has been introduced: "override". It's use is more logical:
tell application "InDesign CS"
tell document 1
override item 1 of master page items of page 1 destination page page 1
-- or:
override page item 1 of master spread of page 1 destination page page 1
end tell
end tell
Note that the second form has problems when facing pages are used. Note also that "master page items" is a property that returns a list of all items on the relevant master page; you can no longer refer to "master page item n".
Changes To Windows
In v2, "window 1" was the the active window, containing the active document. In CS there are two types of window: "layout window" (the v2 window), and "story window" (a window in the story editor). This means that in most cases you will need to change existing references to "window n" to "layout window n". Layout windows also have an important new property: "active page".
Cut, Copy And Paste
It is no longer necessary to activate InDesign to cut, copy or paste. You may at some time receive the following error message: "InDesign CS got an error: Cannot copy/cut unless the document is active." This is misleading – what it should really say is that you tried to cut or copy with nothing selected.
Custom Labels
As well as the labels used in v2, CS also lets you use private labels to store data in pages, documents, spreads and page items. Such labels have a key (how you refer to them) and a value (what you store):
tell application "InDesign CS"
tell document 1
insert label page item 1 key "My Label" value "42"
end tell
end tell
To delete the value, just set it to "". To read a value, you use something like:
tell application "InDesign CS"
tell document 1
set theValue to extract label page item 1 key "My Label" --> "42"
end tell
end tell
You cannot extract a value unless you know the key, and values can contain up to 32k of text.
PDF Attributes
A placed PDF has a property called "PDF attributes", which returns a reference to a PDF place preference for that PDF. This means that you can now find out how a PDF was placed, and what page of it was placed:
tell application "InDesign CS"
tell document 1
page number of PDF attributes of graphic 1 of page item 1
PDF crop of PDF attributes of graphic 1 of page item 1
end tell
end tell
This is important for picture-replacement scripts.
Speed
CS is much faster than v2, and there are a couple of changes than can speed some scripts up even more. First, a document can be opened without showing in a window:
tell application "InDesign CS"
open filePath without showing window
end tell
This will speed up subsequent actions. The InDesign CS demo script package available on this page includes both showing and non-showing versions of the same script for speed comparisons.
You need to make sure you don't leave it that way; it's a sure way to confuse a user. To show such a document, you can make a new window at it:
tell application "InDesign CS"
set theDoc to open filePath without showing window
-- do a lot of stuff
make window at theDoc
end tell
You can't hide a window once a document is open. You can, however, hide all palettes:
tell application "InDesign CS"
set palettes visible to false
end tell
Scripts run from the Scripts Palette also run faster because they avoid redrawing the sceen. This is still the case under CS, but if the script invokes a dialog, CS will do a redraw immediately before showing the dialog.
The "do script" command can also be used to increase speed in some cases. Unlike the equivalent in QuarkXPress, it should be passed either the text of the script, or a reference to a file containing the compiled script. It understands both AppleScript and javascript scripts.
Lastly, you can optimise your code a bit by nesting properties to reduce the number of events involved:
tell application "InDesign CS"
make document with properties {document preferences:{facing pages:false, pages per document:5, page width:"210 mm", page height:"297 mm"}, margin preferences:{bottom:"10 mm", top:"10 mm", left:"10 mm", right:"10mm", column count:1}, guide preferences:{guides in back:true, ruler guides color:grass green}}
end tell
Dialogs
InDesign CS also adds the ability to create custom dialogs with many standard interface elements. Although not covered in this article, a demo script showing this functionality is available on this page.
New Information Added 8/2004
Terminology Conflicts
InDesign overrides the two built-in AppleScript constants "space" and "reverse". To use them, you will have to call them outside the scope of InDesign.
Creating Anchored Items
You can make inline graphics directly, without resorting to copy and paste:
tell application "InDesign CS"
tell document 1
tell parent story of text frame 1
make text frame at character 1 with properties {contents:"foo"}
end tell
end tell
end tell
Setting the bounds is tricky, and is best done after the creation. Also, you will need to force the story to recompose to have the correct bounds returned (you can do this by asking for the last character of the frame).
Scripts Palette Changes
There are several changes involving the Scripts palette:
- Scripts run from the palette can use the application property "active script" to get their path.
- You can assign keyboard shortcuts to the palette's scripts.
- The palette recognises and can run plain text AppleScripts. Such scripts must be saved with the extension .as or .applescript.
- Properties used in compiled AppleScripts are now updated correctly.
- You can control the order of scripts in the palette. Start their names with two characters followed by a close parentheses, as in "00)", and the palette will ignore these characters when displaying the name.
- The palette honors the "Hide extension" checkbox in the Finder's file info dialog.
Change Case
The UI's Type -> Change Case command is available to scripters as "changecase".
Moving Pages Between Documents
Pages can be moved and duplicated across documents. However, you need to be careful about the order in which you move ranges of pages, and you can't retain text flows between pages when moving or duplicating ranges of pages.
New Page Masters
Pages created from scripting now inherit the master page applied to the previous page, the same as in the UI.
Contours And Clipping Paths
InDesign CS gives scripters access to the text wrap boundary and clipping paths. Clipping paths can also be converted to frames with the "convert to frame" command (buried in the Preferences Suite).
Type On A Path
Page items can now contain a "text path" that gives access to type on a path:
tell application "InDesign CS"
--make document
tell document 1
make oval with properties {geometric bounds:{0, 0, "20p", "20p"}}
make text path at page item 1 with properties {contents:"Some text on a circle"}
end tell
end tell
–Shane Stanley
"Ray Robertson created an AppleScript project for a key magazine publisher in Europe. This project helped keep InDesign and InCopy alive during a critical phase of their acceptance testing. Ray and I worked quickly and efficiently to summarize the customer's problem, identify a number of possible solutions, and select the best solution. Ray delivered an initial prototype within a day or so and shortly thereafter delivered a final version that was completely accepted by the customer. The bottom line, Ray's deep knowledge of AppleScript technology and Adobe software was not only invaluable, but his ability to complete the project with such tight quality controls truly saved the day!"
David Cohen
Product Manager
Adobe InDesign Team
David Cohen
Product Manager
Adobe InDesign Team
Client List
AccuweatherAutoshopper
Avatar Data
Publishing Solutions
Billboard Magazine
Citibank
Clarinda Co.
Georgia Dept. of
Community Affairs
Honeywell
Kaspick & Co.
Ledet & Associates
McGraw/Hill Publishing
McGregor Publishing
Network Communications, Inc.
Primerica
Publishers Press
RR Donnelley
Webco Printing
Apple and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries.
Apple assumes no responsibility with regard to the selection, performance, or use of the products or services. All understandings, agreements, or warranties, if any, take place directly between the vendors and prospective users.
Apple assumes no responsibility with regard to the selection, performance, or use of the products or services. All understandings, agreements, or warranties, if any, take place directly between the vendors and prospective users.