WHERE TO START

Recently a user inquired if a script could be written to automate the process of exporting a document to PDF. If this was possible, the user inquired “where would I start.”

Blogs written on scripting most often assume that the reader knows the basics of writing a script. But this inquiry caused me to think that it might be a good idea to back-peddle a little and create a series of blogs targeted to the new beginner.

WHY APPLESCRIPT?

This discussion starts with AppleScript simply because I believe it is easier for the beginner to understand. If you are a Windows user, my apologies; you will have to wait for a series that talks about ExtendScript.

To write a script in AppleScript, you need the AppleScript Editor. For most Macintosh systems, you will find this application in the Utilities folder of the Applications folder. Once you find the application, double-click on its entry to launch it. Once launched, Option-click on its icon in the dock and select Options > Keep in Dock. Now, all you need to do is click on its icon in the dock to launch it.

 AppleScript Editor edit window

The editor is terribly easy to use, just start typing inside the large predominate panel. The instructions you write can be targeted to the Macintosh system as well as a wide variety of applications. Here we will focus on InDesign, version CC 2015. If you are using another version of InDesign, just change the name of the application in the following statement.

   tell application "Adobe InDesign CC 2015"
      --what you want the application to do goes here
   end tell 

TELL INDESIGN

To target the application you want to automate with a script, you create a tell block that starts with the word tell, and ends with an end tell statement. Notice, in the above, the name of the application is placed between quotation marks. With a script you use straight quotes only; not printer’s (curly) quotes.

Comments

Instructions to the user, or notes to yourself, can be placed in a script using a comment. A single line comment follows two hyphens as in the example above. A comment that spans more than one line is placed inside of a parent-asterisk pair.

   (*This comment has a lot to say and will take up more than one line.
   A comment that spans more than one line is enclosed within a paren-asterisk pair.
   *)

APPLESCRIPT DICTIONARY

To automate InDesign using an AppleScript script you need to get familiar with its AppleScript Dictionary. From within the AppleScript Editor, choose File > Open Dictionary…. This will present you a list of the dictionaries for all of the scriptable applications installed on your machine.

Choose dialog for scripting dictionaries

Choose the entry for your version of InDesign and click Choose.

Entries in the AppleScript Dictionary describe the scriptable objects that make up the application. Each object can have properties and methods.

  • Properties – words that describe the object
  • Methods – actions that can be performed by the object

APPLICATION PREFERENCES

If you browse through the dictionary, you will see that all of InDesign’s application preferences can be accessed, or set, with a script. But, be aware that when you set preferences for the application, every document that is created afterwards will inherit these preferences by default. One application preference you may want to work with is PDF export preferences.

PDF EXPORT PREFERENCES

In the find field (magnifier) type the words PDF Export. A list of suggested items is presented from which select PDF export preference with kind of Class.

This takes you to the entry for the PDF export preferences where you can browse through all of the preferences (properties) that can be set for this object classification (class).

Dictionary entry for PDF Export Preferences

As you will see, the list of properties for PDF Export Preferences is quite extensive.Make note of the settings that you are interested in.

To see what the current values for a particular property are, use a get statement. For example one property you might be interested in is crop images to frames. This get statement can be written as follows:

   tell application "Adobe InDesign CC 2015"
	get crop images to frames of PDF export preferences
   end tell 

To make sure you have written the statements correctly, click the Compile button at the top of the editor (hammer button). The code styling will change and no error will be posted if all is OK. If not, the error message should give you a clue of where you have made the error. Check for misspellings or curly quotes instead of straight. When the code compiles, click the <strongrun<>button to run the script. The value returned for the get statement will be displayed in the editor’s Result panel. (Make sure the Result button is highlighted). If you look at the entry for crop images to frames in the dictionary, you will see that the result will be boolean. A boolean is either true or false.</strongrun<>

Script with result in Result panel

SET

If you want to make sure that crop images to frames is always set to true, you can set this property using the following set statement.

   tell application "Adobe InDesign CC 2015"
	set crop images to frames of PDF export preferences to true
   end tell

Should you want to set more than one default value for PDF export preferences, you can place set statements in a tell statement block that tells PDF export preferences:

   tell application "Adobe InDesign CC 2015"
	tell PDF export preferences
	   set crop images to frames to true
	   set compress text and line art to true
           --more statements as needed
	end tell
   end tell

Before you decide that you need to define the whole whopping list of settings for your automated PDF export, you may wish to look at the PDF export presets provided by InDesign. To get a list of existing presets, you can use the following:

   tell application "Adobe InDesign CC 2015"
      get name of PDF export presets
   end tell

One way to get a quick overview of the settings established for a preset would be to open the Export Adobe PDF export window in InDesign (File > Export). With a document open, choose File > Export and Choose Adobe PDF (Print) in the chooser. Give the export a file location and click Save. (You can always Cancel before actually creating the PDF.) In the Export Adobe PDF window, choose a preset and browse through the dialog tab panels to see how the values are set. You may find that one of the presets has just about all of the settings defined the way you want them.

 Export to PDF dialog

Alternatively, you could use a script similar to the following to get the values you are interested in:

   set str to ""
   tell application "Adobe InDesign CC 2015"
      tell PDF export preset "[High Quality Print]"
    	set str to str & "name of applied flattener preset " & name of applied flattener preset
	set str to str & "optimize PDF " & optimize PDF & return
	set str to str & "export reader spreads " & export reader spreads & return
	set str to str & "include hyperlinks " & include hyperlinks & return
	set str to str & "include structure " & include structure & return
	set str to str & "export reader spreads " & export reader spreads & return
	set str to str & "include hyperlinks " & include hyperlinks & return
	set str to str & "include structure " & include structure & return
	--add more statements as needed
	end tell
end tell
str

This script introduces a couple of new concepts:

  • variables – The first statement creates a variable identified by str. You might want to think of a variable as the label on the front of a box to identify an item you have stored inside for later use. The identifier for a variable can be any combination of alphanumeric characters. A common convention for naming a variable is to place two words together with the second word designated by a capital letter. This is referred to as camel case as the capital in the middle can look like a camel’s hump.
    For example:
       myVariable
    or a shortened version:
       myVar
  • concatenation – This is a word that simply combines objects together. To combine words or strings of characters, the ampersand (&) is used. Notice in the example above, that in each set statement, the string (identified by the variable str) is added to itself. This is followed by text to identify the property, a space, the value for the property, and then a line return (return).

To get a sense of how this works, copy the script above into AppleScript Editor. Make sure you have your version of InDesign running in the background. Compile and then run the script. Check out the result in the editor’s Result panel. Add more statements to get all of the property values you are interested in.

If you find a PDF export preset that sets your PDF Export Preference values the way you want them, you can export a document to PDF using a script similar to the following:

Export to PDF With Preset

   (*Names of presets provided in InDesign for version 2015:
   "[High Quality Print]", "[PDF/X-1a:2001]", "[PDF/X-3:2002]", 
   "[PDF/X-4:2008]", "[Press Quality]", "[Smallest File Size]"*)
   --gets the path to the desktop on the computer
   set desktopFolder to path to desktop from user domain as string
   --adds the name of the file to the path to the desktop
   set filePath to desktopFolder & "samplePDF.pdf"
   tell application "Adobe InDesign CC 2015"
      set myExportPreset to PDF export preset "[Press Quality]"
      tell document 1
	  asynchronous export file format PDF type to filePath using myExportPreset
      end tell
   end tell

Note: asynchronous export is only available with later versions of InDesign. Consult the AppleScript Dictionary for your version of InDesign.

CREATE YOUR OWN PRESET

If you don’t find a PDF export preset that fits your particular need, you can write statements to define your settings individually, or you might decide to create a PDF export preset for a collection of preferences you use repeatedly. To create a preset with a script, you simply make a PDF export preset, give it a unique name, and establish its settings. If you look at the AppleScript Dictionary listing for PDF export preset, you will find that the property listing is similar to that for PDF export preferences. One way to accomplish this is to put a reference to the object being created in a variable and then use the variable as part of a tell statement to set the values for its properties. For example:

   set presetName to "ReaderSpreadPreset"
   tell application "Adobe InDesign CC 2015"
	if not (exists PDF export preset presetName) then
	   set myPreset to make PDF export preset with properties {name:presetName}
	else
	   set myPreset to PDF export preset presetName
	end if
	tell myPreset
	   set crop images to frames to true
	   set export layers to true
	   set export reader spreads to true
	   set open in full screen to false
	   set pdf magnification to actual size
	   set use document bleed with PDF to true	
	end tell
   end tell

Notice that this script uses an if statement to determine if a preset currently exists with the name identified in the variable presetName. If the preset exists, its values are overwritten by those enumerated in the tell myPreset statement block. For a fully functional script you might want to alert the user that the preset values will be overwritten and give the user the option to not override the settings.

Note: When you export a document using a preset, any properties not set by the preset default to those currently set by default.

SECURITY

PDF export preferences that can’t be included in a PDF export preset are those that have to do with security. Security settings are only effective if the property use security is set to true:

   --inside tell statement to PDF export preferences
   set use security to true
   (*the following value can only be set; 
   trying to get its value will produce an error*)
   set change security password to false
   set disallow changing to false
   set disallow copying to false
   set disallow document assembly to false
   set disallow extraction for accessibility to false
   set disallow form fill in to false
   set disallow hi res printing to false
   set disallow notes to false
   set disallow plaintext metadata to false
   set disallow printing to false

APPLIED FLATTENER PRESET

For the most part, the preferences that can be set for PDF export are fairly self explanatory. One that may give you some difficulty is applied Flattener Preset. A Flattener Preset is similar to a PDF Export Preset as it is a collection of properties identified by a given name.

Adobe’s technology for turning a document having transparencies into a form that can be output is called flattening. For this, InDesign provides several flattener presets, a list of which can be returned using:

   tell application "Adobe InDesign CC 2015"
      get name of flattener presets
   end tell

To use a flattener preset certain conditions must exist within the application. Without that, an attempt to set or get values having to do with a flattener or transparency will produce an error. For this reason you will want to place these statements inside a try, end try statement block.

   --assumes the presets referenced exist
   set myError to "" --initialize value for variable to empty string
   tell application "Adobe InDesign CC 2015"
      set myFlattener to flattener preset "[High Resolution]"
      set myPreset to PDF export preset "ReaderSpread"
      tell myPreset
         try
            set ignore spread overrides to true
            set applied flattener preset to myFlattener
        on error errStr
            set myError to errStr
        end try
       --other statements to set for the preset
      end tell
   end tell
   myError

With a number of PDF Export Presets created, you could present your user with a list of presets from which to choose as part of an export to PDF script.

EXPORT TO PDF SCRIPT 

   --expects open document in Adobe InDesign
   set myPrompt to "Choose PDF Export Preset"
   set desktopFolder to path to desktop from user domain as string
   set filePath to desktopFolder & "samplePDFExport.pdf"
   try
      tell application "Adobe InDesign CC 2015"
        --make sure there is a document open
	if (count of documents) is greater than 0 then
	   set docRef to document 1
	else
	   error "Script requires an active document"
	end if
	set presetList to get name of PDF export presets
	set presetList to choose from list presetList with prompt myPrompt without multiple selections allowed
	--make sure user has selected a preset
        if presetList is false then
	   error "Can't continue without preset choice"
	else
	   set presetName to item 1 of presetList --only 1 choice was allowed
	   set myExportPreset to PDF export preset presetName
	end if
        --perform the export
	tell docRef
	   asynchronous export file format PDF type to filePath using myExportPreset without showing options
	end tell
      end tell
   on error errStr
      activate
      display alert errStr
      return
   end try

Dialog presented when Export to PDF script is run

ON YOUR OWN

We have covered a lot of territory here including using AppleScript control statements such as if/else and try/on error. To dig deeper into working with AppleScript and PDF export, avail yourself of a copy of Adobe’s InDesign Scripting Guide_AS (click here). Search for topics having to do with PDF Export. You will find a wealth of information there. The latest version to my knowledge is for InDesign CS 6, but for the most part is perfectly applicable with later versions.

UPWARD AND ONWARD

As you can see from this last script example, a script can start to get pretty complex. In the next installation of this series we will explore ways you can make your script more readable and extendable as we add more to our example Export to PDF script above.