12. A Symphony of Automations: The System Project
We are what we repeatedly do.
—Aristotle
To produce rich, complex documents, it’s possible to create graphics automation systems: groups of agents that work together to act on multiple applications. Systems are the symphonies of graphic automation—with much going on and many different modules—and you are both composer and conductor (with a bit of the ringmaster thrown in). Within these exciting organisms, the modules have to perform flawlessly (meshing and communicating with others) if they’re to produce the document you planned.
The first part of this book covers automation concepts; the second covers tools; and the third provides recipe-type projects. This last chapter focuses on the experience of planning and building a multipart system. Although the project described here is larger than anything covered thus far in this book, its components are no more complex than those you’ve seen in previous chapters. And the process is pretty similar to building a single, small agent: You must plan what you’re going to do (breaking the project down into manageable sections), select your tools (that is, which form of automation you’ll use), and solve the problems that will inevitably crop up along the way.
Since you’re by now familiar with available automation technologies—you know how to use the tools, and you know where to look for technical details you don’t remember—this chapter is less about the nitty-gritty techniques of automation and more about planning and problem-solving strategies. When you’re building a large project, the most useful knowledge you can apply is an understanding of automation concepts, tools, and problem-solving techniques.
Go to www.peachpit.com/apprentice to download the scripts and project files described in this chapter.
The Project
Since this book covers Photoshop, Illustrator, and InDesign, I originally conceived of a project that would link the three programs and add some capabilities from other applications to build a large-ish graphics automation system. As it turned out, this automation uses seven applications, and it took nine applications to produce it: The automation uses the three Creative Suite applications, an e-mail client, a script editor, the Mac’s Finder (to build the audio file), and a Web browser. Producing the automation required an HTML editor and a text editor as well. Despite all of these tools, the individual automation agents are not all that complicated.
The project is to build a personalized, interactive PDF newsletter for our fictitious client—Star & Fey Seed Co.—to send to its customers (Figure 12.1). The newsletter contains personalized text, a photo of a garden rock with the customer’s first name (as if chiseled there), a map of the customer’s region of the United States with his or her state highlighted and showing the state’s U.S. Department of Agriculture hardiness zone (a climate-based code for planting guidance), and a customized spoken greeting incorporating the season and the customer’s first name and state.
Customers enter their contact information in a Web form, and that data is sent to an e-mail box; receipt of these messages triggers a script that collects the data from each e-mail as it is received and writes it to a text file. Later, a person triggers another script that reads all of the customers’ data from the text file and uses it to build files in Photoshop, Illustrator, and InDesign, as well as to build the audio file. Finally, the whole thing is saved as an interactive PDF and e-mailed to the customers using the addresses they provided.
I wanted to design an automation that would send a newsletter to customers almost immediately after they submitted their information, but it wasn’t practical, because the Creative Suite license doesn’t allow the kind of end-to-end, unattended automation I envisioned. A licensed Creative Suite user (that is, someone who has a legal copy of the software) must initiate the automation to create the images and the newsletter with the Creative Suite applications. I worked around this by having the graphic designer step in after the customer’s information is received but before any Creative Suite documents are generated.
Planning
You should always sit down and scope out your project before beginning work on it. Like any design project, this one has a goal, restrictions (intended usage, budget, and so on), and a timeline. When you are getting started, this phase often gets neglected. The first step is to write out the project’s workflow, which will look a little like the following:
1. Build templates for dynamically generated personalized communications, including determining which elements will be personalized.
2. Solicit customer information needed for contact purposes and for personalized elements of the newsletter (including name, home state, and e-mail address).
3. Receive and store customer data.
4. Parse customer data into tabular format for reuse in dynamically generated communications.
5. Combine customer data with templates to generate personalized communications.
6. Send personalized communication to customer via e-mail.
For this project I physically listed on a pad (almost like a to-do list) the modules I needed to build for my system. You’ll notice that most of this system’s application agents are scripts; in the Tools section later in this chapter, you’ll find out why, as I demonstrate how scripting (and AppleScript in particular) fulfills all of the automation needs for this project. The modules I built for this project include the following:
• Photoshop, Illustrator, and InDesign templates
• Web form to collect customer data and transmit it via e-mail
• E-mail rule (in Apple Mail) to intercept the e-mail generated from the Web form and trigger a script to process it
• A script to gather data from each e-mail and write it to a text file for storage
• A script to read the data from the above-described text file (to be triggered by a person when it’s time to send out the newsletters)
• A script that creates a personalized audio file (like the one I created in Chapter 2)
• A script to build a personalized Photoshop file
• A script to build a personalized Illustrator map file
• A script to open an InDesign template, plug in all of the other files, and export the PDF
• A script to build a new e-mail with customized text, attach the PDF, and send it to the customer
Note that the scripts described in the last five bullets will become one big script in the end.
Strategy
I laid out the scope of the project as described in the previous section because that’s exactly how I intended to build the system—one module at a time. I would later link them in a chain to produce the system. Working in discrete units serves as an efficient way to build a system: For starters (as I mentioned earlier in the book), it’s easier to build and test smaller agents because there are fewer issues to deal with and fewer things to go wrong; consequently, when something does go wrong, it’s easier to track down the problem. Also, you should think of these modules as a library of parts that can be adapted and reused for other projects—and it’s easier to reuse self-contained modules that do just one task. This building-block approach is very similar to the way Automator works (see Chapter 5).
Finally, the sense of satisfaction you get from successfully finishing a module can keep you going when you’re in the middle of a big project. You will undoubtedly encounter thorny problems, and although problem solving can actually be fun (it’s true), too many problems in a row will drag you down. This approach prevents that from happening.
The risk in building projects a module at a time is that if the system is dependent on a particular module (say, inserting files into an InDesign template), the whole system is in danger if that module proves unworkable. If that module isn’t produced until later in the project cycle (like the InDesign module), it might be too late in the process to rescue the system. Yet this also points up the virtue of breaking a workflow into the smallest possible units—because most of your modules are probably reusable. It also reinforces the importance of identifying and isolating tasks in your workflow before picking the automation tools to accomplish them (if you’re too wedded to one of your tools, you could miss finding a work-around). After you get a few automation projects under your belt, you’ll find it easier to identify potential trouble spots early and tackle them head-on. For instance, since I’d never linked an audio file to an InDesign document before this newsletter project, I decided to test it early so that I could cross it off my potential issue list. (This is not to say you won’t come across potentially deal-killing issues as you move through your projects; you will. Later, you’ll learn of one in particular that I had to handle for this project.)
Another timesaving strategy I employed was adapting previously created agents, including the spoken-word audio file (Chapter 2) and the script for generating e-mail messages (Chapter 10). Reuse and adaptation is a tried-and-true method that will greatly reduce the time you spend building and troubleshooting a system.
Dead Ends
On this project I wasted a good amount of time trying to figure out how to use a zip code to place a town marker on a map in Illustrator. My original idea was to have the person’s town indicated on his or her state map. I would then convert zip codes into latitude and longitude and use those coordinates to create objects in Illustrator. I found a free 1999 database file from the Census Bureau with zip codes and corresponding latitudes and longitudes, and imported it into a FileMaker Pro database. This done, it was pretty easy to write a script to locate the database record containing the person’s zip code and to get their coordinates.
But that scheme was for naught. Latitudes and longitudes are derived from lines drawn on a sphere, which when represented in a 2D space such as an Illustrator file, turns out to be curved. Coordinates in Illustrator are based on straight lines and therefore cannot be used to locate a position on a flat map. You can get approximate locations with this method, but the margin of error is too big to, say, accurately mark towns near state lines. I knew all that in the back of my mind, but I was so interested in solving the problem that before long I was on a caffeine-fueled quest to triumph at all costs. Before I crashed and burned, I discovered that you can script Google Earth and other mapping services. You can send a URL containing a zip code or address to Web sites like Yahoo Maps via scripting, then trigger a screen-capture utility to take a screen shot of the map it produces. (These were unusable because they cannot be redistributed for commercial purposes.) So I couldn’t use any of this in my newsletter, but it’s almost certain to come in handy somewhere down the line.
So don’t despair when something doesn’t work. Even if you fail, as I did, you will have at least learned what doesn’t work, and that goes into making you a better graphics automation developer. In other words, enjoy the journey.
Tools
The automation techniques I used to build this project had to meet three requirements: They needed to work across multiple applications (including a couple that aren’t part of Creative Suite); they had to pass data from the beginning of the process all the way to the end; and they had to continually trigger each module in turn (with the caveat that a person has to trigger Module 4, as described in the Planning section earlier in this chapter).
In this case, I opted to use one tool that can communicate with multiple applications (including non-Adobe applications). To work across multiple applications, your choices are Automator and scripting. I don’t have enough Automator actions for what I need to do (and it wouldn’t be efficient to write as many as this would take), so scripting won on this criterion.
Passing data from the beginning to the end of the system presents similar challenges. You could conceivably use different tools for different modules, but not all tools are good at interfacing and sharing data. Adobe’s actions, for instance, don’t interface with other agents at all, and it’s difficult to pull data out of an Automator workflow from another agent. To pass data all the way through the system, you can’t avoid using scripting. To keep the process moving (triggering each module in turn), scripting again represents the only workable solution. But how do you know which scripting language? Ideally, you’d want this to work on both Windows and Mac. But ExtendScript (Adobe’s cross-platform flavor of JavaScript) only links Adobe applications (and only when run from Adobe’s ExtendScript Toolkit). And VBScript only works on Windows, and only within one application at a time. So I went with AppleScript.
To keep the process moving, you could conceivably use a variety of tools, such as Creative Suite’s actions, scripts, and Automator. But this approach presents a different problem, requiring you to repeatedly leap from tool to tool. Graphics automation tools are typically written to operate within a relatively small environment (say, a single application) and don’t generally communicate very well with other tools. For example, actions can’t accept data from outside the application in which they reside (either Photoshop or Illustrator); Automator can trigger some other tools but is somewhat limited in how it can pass data to them; and so on. You would have to continually jump through hoops to make this approach work.
If you’ve been following the bouncing ball, you’ll know that AppleScript is the winner. It’s unfortunate that it only works on Macs, but AppleScript fulfills all my project’s automation requirements.
Getting Started
Although I always write up a plan like the one described earlier in this chapter, I have to admit that I don’t always follow it to the letter. I sometimes go off on tangents, and I definitely hit my share of dead ends. But there’s a difference between losing your way when you have a map to lead you back on track and being just plain lost. So give yourself a good map—a constantly updated to-do list—and do your best to stick with the plan. But don’t beat yourself up for getting a bit sidetracked. I guarantee the experience will prove useful in time, no matter how useless it feels in the moment.
The Templates
This project uses six templates: a photograph in Photoshop on which type is placed, four maps in Illustrator dividing the contiguous United States into four regions, and the final InDesign newsletter. Both the Photoshop and Illustrator files will be placed into the InDesign document. Templates are easy environments in which to work because you know where everything is and what it’s named.
A well-built template will be flexible enough to handle issues that crop up in automated design, such as type whose length changes in different iterations of a document. You can use your automation technology (for example, scripting) to handle some of the variability, but you can make it easy on yourself by compensating for variations during the design phase as much as possible.
Photoshop Template
This project’s Photoshop image consists of a rock onto which I have placed type that (hopefully) appears to be chiseled into the stone (Figure 12.2). One of the most common issues when dealing with type is how to make variable-length type fit within a given space—in this case, the length of a rock. Because Photoshop doesn’t have text-measuring capabilities, I had to improvise them. A good way to anticipate potential design issues is to insert the extremes of your content into the template. For the rock text, I inserted the shortest name (Al) I planned to use and then subsequently tried inserting incrementally longer names (Brigid, Nicholas, Alexandria, and so on). By so doing, I discovered ways I could build the template file to compensate for varying name lengths.
On my rock photo I’ve set up three text layers, each of which is a different font size to accommodate varying numbers of letters. Names of 10 or more characters just don’t look good on the rock, so I had to come up with a different solution for them (more on that in a subsequent section).
The rock image is 3 inches wide by 2 inches high at 120 dots per inch. I created a text layer by using the Text tool to click the image; then I named it ShortName. I typed a three-letter name (Jez) and used Free Transform to distort the type to match the position and perspective of the rock. I applied the Bevel and Emboss layer style (Layer > Layer Effects). Thirty-five-point type looked best for the three-and-under letter crowd.
I duplicated the ShortName layer twice, naming one MedName (for medium) and the other LongName. I found that 28-point type worked best for medium (4 to 6 letters) and that 19-point type worked best for names of up to 9 letters. I hid all three text layers by clicking the eyes on the far left of each layer in the Layers panel and saved the file, naming it RockFile.psd.
Illustrator Templates
The Illustrator maps were the most difficult to produce. I had to assign each of the 48 state layers their full state names rather than abbreviations. I overlaid the map with the USDA hardiness zones (www.usna.usda.gov/Hardzone/ushzmap.html).
I wanted my newsletter graphic to highlight the recipient’s home state, labeled with the state’s name—but when I used a map of the contiguous United States, the individual states were too small. So I decided to divide the U.S. map into four regions (Northwest, Southwest, Northeast, and Southeast). I divided the map into quarters pretty much by eyeball; I didn’t use one of the many accepted region divisions.
I duplicated the state layers and used these to create each state outline and state name (Figure 12.3).
InDesign Template
InDesign offers a few bells and whistles when it comes to exporting interactive PDF files: You can add audio (and video) files, interactive buttons, hyperlinks, and PDF bookmarks.
The Layout
First, I built the layout, creating and placing placeholder images for both the rock and map images and creating two text boxes. The first text box contains the customer’s first and last names (with a space in between); my script will pull these from my data (Figure 12.4).
I needed to name this text frame so that my script would be able to identify it. I selected the full-name text frame and chose Window > Interactive > Script Label. I then clicked in the Script Label panel, typed CustName, and pressed the Tab key to accept it (Figure 12.5).
In the text frame directly beneath the preceding one (which begins with the text Hello Customer), there are two words that will be replaced in each iteration. I needed to name this text frame by giving it a script label. I selected the Hello Customer text frame and chose Window > Interactive > Script Label. I then clicked in the Script Label panel, typed CustLetter, and pressed the Tab key to accept the label (Figure 12.6).
The word Customer will be replaced by the customer’s first name, and the word season will be replaced by the current season (spring, summer, fall, or winter). (The script gets the current month from the computer to determine which season it is.) While the customer name runs the risk of oversetting the text frame, I estimated that it would take a first name of about 20 letters to do so—not very likely.
Interactive Features
As mentioned previously, I’m using three of InDesign’s interactive features: the audio file, the Multistate button (with a Web page hyperlink), and a text hyperlink to e-mail. I wouldn’t ordinarily use so many interactive elements on one page, but in a rich, multipage document, a range of interactive features can be very effective.
I built a temporary audio file and placed it in the InDesign template (File > Place). The icon for an audio file is what InDesign calls a poster (Figure 12.7).
In setting up this part of my layout, I ran into one of those unforeseen problems. The standard poster for an audio file is pretty ugly, so I wanted to replace it with a graphic of my own design (Figure 12.8). To replace the poster, I double-clicked the placed audio file. Then, from the Poster pull-down menu, I selected Choose Image as Poster and clicked Choose (Figure 12.9). Even though I used the same Web-safe green for the background of both the audio poster and the newsletter, they didn’t match when I exported the document to PDF.
After about 40 minutes of trying everything I could think of (copying and pasting from Illustrator and triggering the audio from a button), I found that if I set Poster to None, the exported PDF would contain a black audio icon that I hadn’t seen before (Figure 12.10). Even if this didn’t make sense, given my other choices, I decided it wasn’t so bad. I gave this rectangle the script label AudioFile and then saved the file.
With InDesign, you can create interactive buttons that change their appearance according to whether they’re idle (the Up state), being moused over (the Rollover state), or being clicked (the Down state). This is part eye candy, part user feedback; I added a hyperlink to the button so that when a user clicks it, he or she is taken to a Web site.
InDesign lets you create multistate buttons in two ways: You can either convert your own graphic to a button or use InDesign’s Button tool and appearance effects. I chose to create the button-state graphics in Illustrator. To do so, I created three PNG files in Illustrator (File > Export > PNG format) and placed the Up button in InDesign. (While the Rollover and Down states are optional, all buttons in InDesign have the Up state.) I then converted it to a button (by selecting the Button graphic and choosing Object > Interactive > Convert to Button).
By bringing up the States pane (Window > Interactive > States), I created the other two states and imported the graphics for them. From the States pane menu (Figure 12.11), I chose New State to add the Rollover state, where I specified which graphic would appear when a user hovered his or her mouse over the button. I then returned to the States panel menu and selected Place Content into State (Figure 12.12). I browsed until I located the rollover graphic and clicked the Open button. I repeated the process for the Down state.
Although I couldn’t test the button states by mousing over and clicking the button in InDesign, I was able to see the states in play by clicking each in the States panel to make them appear in the InDesign document. To really test the button, I had to export to PDF. To actually get the button to do something (in this case opening a Web page), I selected the button and chose Object > Interactive > Button Options (you can also double-click the button to bring up the same window). I clicked the Behaviors button at top center and in the Event menu chose Mouse Up. (Mouse Up means “click and release the mouse button.”) In the Behavior menu, I chose Go To URL and entered my Web page address, http://www.starandfey.com (Figure 12.13). Note that you can specify multiple behaviors per event.
The last interactive feature I added to my InDesign template was an e-mail hyperlink. After bringing up the Hyperlinks panel by choosing Window > Interactive > Hyperlinks, I selected the text I wanted to associate with the hyperlink (in this case the entire “Send us a message” text frame). Then, from the Hyperlinks panel menu, I chose New Hyperlink (Figure 12.14).
From the Type pull-down menu, I then chose URL and typed in mailto:[email protected]. Note that this URL is formed by combining mailto: (don’t forget the colon) plus an e-mail address with no space in between. A few ways to highlight the link are provided in the Appearance area of the New Hyperlink dialog box, but none of them looked very good in this design. I chose Invisible Rectangle in the Type pull-down menu and None for the Highlight (Figure 12.15).
Export Setup
Although the script will do the exporting to PDF, I needed to set two important export preferences in InDesign: First, I saved the InDesign document one last time to make sure I wouldn’t lose anything. Then I exported the template document by choosing File > Export, selecting Adobe PDF from the Format pull-down menu, and clicking the Save button. In the next window I checked the Hyperlinks and Interactive Elements boxes in the lower right (Figure 12.16) to ensure that those elements are included in the PDF.
The Web Form
A form that resides on a Web page provides a nice means of collecting data: Users simply fill in the form, and the data is collected and sent to you in an e-mail message. You could collect the data in other ways (see the Adobe Acrobat form in the Ad Generator project in Chapter 11 as an example), but none is likely to be as user-friendly as Web forms: All they require is that the user be on the Internet and have a Web browser.
Web forms are surprisingly easy to build. They are fairly simple Web pages and can be built in almost any WYSIWYG Web page editor. (I used Adobe Dreamweaver.) You’ll need to check with your Internet service provider (ISP) as setups vary (some even offer templates), and you’ll need a Web hosting account. If you’re working with a Web producer, you can design the page, and that person will take care of all the back-end stuff.
I downloaded an example form from my ISP’s Web site and opened it in Dreamweaver. From there, I added a background color and the client’s logo, and deleted all of the fields I didn’t need. I also added a pull-down menu with the 48 contiguous states (Figure 12.17). Using the same method, I created a confirmation page that read, “Your submission was successful,” and an error page that read, “There is an issue with the information you entered. Press the Back button and try again.” Then, following my ISP’s instructions, I uploaded these forms to my Web site.
E-Mail Script and Rule
The cool thing about collecting data this way is that the data is delivered to my mailbox as regular e-mail messages. All I needed to do was figure out a way to automatically copy the data out of each message and compile it in a text file. (I could also have chosen to store the data in a spreadsheet or database.)
The E-Mail Script
To extract customers’ information from all the e-mail messages generated by my Web form, I wrote a script (which you can download with the rest of the project files from www.peachpit.com/apprentice). Whenever I receive a message from the Web form, a rule that I set up in Apple Mail recognizes the standard subject line and activates my script. Then the script copies whatever is in the body of the e-mail and appends it to the end of a text file (BrochureList.txt). This is great, because the script lets you write to a text file without ever opening it.
I did, however, have to troubleshoot a couple of unanticipated problems with this script. Invisible characters were being appended to the end of the e-mail messages and ending up in my text file, so I had to write a small loop in the script to delete them. To get rid of the unwanted mystery characters, I copied and pasted the invisible text from a sample e-mail, stored it in a variable called illegalCharacters in the script, and deleted them before writing to the text file.
The problem of the invisible characters is an example of something you will encounter time and again when writing automation agents—things that you didn’t think about or could not have foreseen. This is plain, old problem solving and can be the bane of your existence or a fun romp, depending on which way the winds blow—and your attitude.
Personally, I find this type of problem solving interesting, because it’s like solving a mystery. Take the invisible characters: All I could see was that there was some invisible text written to the text file. Where did it come from? Was I somehow accidentally writing it from the script? I checked but didn’t find anything there. So I opened one of the test e-mails written by the Web form, and sure enough there was some invisible text at the end of it. This usually points to the existence of a return or some tabs, but the invisible text remained even after I tried to delete those. I didn’t know where the invisible text came from or what it consisted of, but I knew that if I could store it in a variable in my script, I could use that to identify the characters copied from the e-mail and delete them.
After everything was working, I saved the script as EmailRuleScript.scpt.
The E-Mail Rule
The e-mail rule that initiates my script operates on the same principle as the junk-mail filter in your e-mail client (and is probably only a bit more complicated). Although common and simple to use, e-mail rules are bona fide automation agents. You can use them to automatically forward, delete, or reply to messages that match criteria you specify, such as recipient, subject line, or date received. Apple’s Mail application can also trigger AppleScripts, opening up entirely new vistas. And although it’s not as easy, you can script Entourage and Outlook to do something similar. I remember reading about someone who’d figured out she could send a message to her home e-mail, trigger an AppleScript to create a new message, attach a particular file to it, and e-mail it back to her—a weird but cool form of remote control, regardless of the security issues.
In this case I wanted an AppleScript to be triggered whenever an e-mail was received with the Subject line “Star & Fey Newsletter Form Feedback” (as set up in my Web form). In my e-mail application I set up a rule by choosing Mail > Preferences > Rules. E-mail programs (that support rules) vary, but the idea is that you specify one or more criteria (such as subject line, sender, or priority) and then one or more operations that you want to be carried out when the criteria is met. I clicked the Add Rule button and added a new rule, set up as shown in Figure 12.18.
I ended up with a text file—each line consisting of one person’s first name, last name, state, and e-mail address—that looks something like this:
Sam,Lowery,California,[email protected]
Jill,Layton,Oregon,[email protected]
Jack,Lint,Georgia,[email protected]
Harry,Tuttle,Maine,[email protected]
Ida,Lowery,Iowa,[email protected]
The Big Project Script
The command center for this project is one large script. It assembles data, builds an audio file, creates Photoshop and Illustrator documents, brings it all together in InDesign, and saves it as a PDF. The script is long, but it’s nothing more than a series of individual modules. It’s similar to an Automator work-flow, where each module accepts data, performs some operation, and then passes the data along to another module.
I won’t step through the script line by line but instead will provide an overview of each module and talk a little about the more interesting bits. I manually triggered the script from the script editor, but before I ran it, I opened the BrochureList.txt file containing the customers’ data and deleted the first empty line. The e-mail script writes a return before writing customer data, so if left unedited, the first line consists of nothing but a return, which the big script interprets as a customer record, causing it to error out when it tries to gather data that’s not there.
Seasons
Since one of the dynamic text elements in the newsletter is the season, I needed to find a way to determine which season was currently under way. To do so, I used system information (the date, according to the computer’s operating system). Among the data you can pull from the operating system is the date, which looks something like the following: Thursday, June 12, 2008 11:33:05 AM. I decided to extract the month to determine the current season. Other date elements you can use and act upon include the day of the week (is it the weekend or not?), the day of the month, the year, the period of day (A.M. or P.M., day or night). With two times, you can determine an elapsed amount of time (how long did it take to do something, and is that period of time out of spec?). As you can see, you can often ferret out a considerable amount of information from what seems like a small amount of data.
The month is June. To determine the season, I built four lists of the months in each season. Here’s how that looks in the script:
You can also save the date from the e-mail you received from the Web form and use that to derive the season—plus, knowing the date on which the customer contacted you might be handy for follow-up communications.
Once you’ve done this, it’s just a matter of finding out which list the current month belongs to (spring).
Importing Text File and Building Variables
After importing the text, I separated out the data and stored it in variables. The four variables for this project included each customer’s first name, last name, state, and e-mail address. Lists of this nature make it easy to work with data. You can identify this section of the script (the parsing of records and assigning them to variables) because it starts with the comment -- BUILD THE LISTS OF CUSTOMER DATA.
I used these four lists (variables)—FirstName, LastName, State, and Email—throughout the script.
Now that the basic data setup is complete, it’s time to start building the individual files that make up the final document.
Audio File
Once I’d created the variables, it was easy to grab personalized text from them and use that to create the audio file. Although the computer voice sounds far from human, it speaks directly to the customer (and no one else), which is a nice touch.
Just as with text in a text frame, I can build an audio file that mixes static and dynamic words. Here’s what I wanted the voice to say: Hello [customer’s first name]. Welcome to the Star & Fey [the season] newsletter. Check out the personalized garden stone on sale this month and double-check your hardiness zone for [the customer’s state] in the chart at the bottom. Have a great [the season].
Text-to-speech conversion is available in Windows, Mac, and other operating systems. This is something that computers do pretty well now (this wasn’t always the case), and it can be a great help for those with impaired vision or learning disabilities. As I was writing this (in June 2007), Apple announced improvements in its computer accessibility, including a much improved synthesized voice (called Alex, which will be available in Mac OS X 10.5 in October 2007). I hope Alex is a sign of changing times—for all operating systems.
The Mac’s available voices, while relatively good, are still sometimes hard to understand, and since Alex won’t be available until the fall of 2007, I decided to use a voice from a company called Cepstral (www.cepstral.com). They sell good synthesized voices for about $40, and I chose the UK English voice, Lawrence. The British accent doesn’t have anything to do with this project; I just happen to like it.
Photoshop
As I described in the Templates section, in Photoshop, I put a name on a rock, which isn’t all that difficult. All I had to do was replace text in one of three text layers I set up in my template. To determine which layer to display, my script had to count the number of characters in the first name to be displayed and then pick one of the layers.
The script counts the letters in the customer’s first name and stores that in a variable called NameLength. The script asks a series of questions to determine which category the name belongs in. The first question, if NameLength ≤3, is asking if the number of letters is less than or equal to 3. The second question, if (NameLength > 3) and (x < 7), is asking if the number is greater than 3 and less than 7. The third question asks if it is equal to or greater than 7 but less than 10. The last question determines whether the count is 10 or greater.
I found that names with 10 or more letters didn’t read well on the rock, so I decided that names of 10 letters or longer would make the LongName layer visible and insert the text Your Name—not an ideal solution, but it works. These are the types of work-arounds you’ll need to create when designing for data-driven documents. It is a whole new dimension to design for a page where elements may move around and change size, shape, and color.
Illustrator
Since there are four Illustrator maps for my four United States regions, I had to determine which one to open and act upon for each newsletter being generated. My approach for this was similar to the one I used to determine the season. I first built four variables (like the four seasons) and listed the states that belong to the four regions (NW, SW, NE, and SE). Here’s what the four variables and their lists look like:
Again, I more or less quartered the lower 48 according to my whim, not by any official reckoning. So now, as with the seasons, my script must find which list contains the newsletter recipient’s home state. I stored the recipient’s state in the variable StateName. Here again, my script asks a series of four questions, this time along the lines of if StateName is in NWlist. When it finds the correct list, the script uses the corresponding variable to open the region’s map file.
Once the region map is open, the script makes that state’s layer visible and exports the file in PNG format (Figure 12.19).
InDesign
Now it’s time to bring it all together. The script opens the InDesign template file, inserts the two images and the one audio file, changes some text, and exports the document. Inserting files is accomplished with fairly simple statements like place [file path] on rectangle [rectangle name] of document 1. Because the audio file is contained in a rectangle, setting its icon (or poster, in Adobe-speak) is a little weird: set sound poster type of sounds of rectangle "AudioFile" of document 1 to none.
One of the text boxes in my template displays the customer’s first and last names (which are made up by combining the first name variable, a space, and the last name variable) in a text frame. Because names can be of different lengths, the script includes some logic to ensure that the full name fits. Here’s the code that makes that happen:
This code inserts the customer’s full name (FullName) in the CustName text frame and starts a repeat loop that asks if the text frame is overflowing (true or false). If it is, the script sets the text frame to nothing (""), reduces the type size by 2 points, and starts over by inserting the full name again and running through the loop until the text frame does not overflow.
InDesign is a little weird and forces me to do something that doesn’t seem to make any sense. When text overflows a text frame and you set that text to nothing, InDesign only acts on the text that’s visible in the text frame. Thus, if I insert your full name and your last name disappears because it’s overflowing the text frame and I then set the text to nothing, it will only delete your first name. If your last name fits in the text frame, it will pop into view. So to ensure that the script wipes out all of the text in the frame, I have to set it to nothing—twice.
For the longer text block, I replaced only some of the text in the frame: the words Customer and season. I replaced Customer with this line in the script:
set (contents of every word of text frame "CustLetter" of document 1 whose contents is "Customer") to FirstNameSing
FirstNameSing is the variable storing the customer’s first name.
When all the changes are made, the script exports the InDesign document as a PDF named Star_and_Fey.pdf. The script doesn’t have to give each PDF a unique name because the file is overwritten after the previous one has been e-mailed.
Final E-Mail
I won’t dissect the e-mail script because it’s very similar to the e-mail invitation project in Chapter 10. Note that the body of the message is built in the same way as the audio file—that is, by mixing both static and variable text (Figure 12.20).
Note that there’s one little line (the third from the end of the script) that’s very dangerous: send newMessage can send e-mail to everyone in your data set—before you might be ready. For my testing, I disabled this line in AppleScript by “commenting it out,” which means to change the live code to a comment so the script won’t execute it. It’s still there, but it’s italicized and grayed out. The format of comments varies by scripting language, but in AppleScript you type two consecutive hyphens at the beginning of the line like this:--send newMessage.
I tested the script by commenting out the send newMessage line and changing the repeat line repeat with i from 1 to CustDataCount (it appears in the script right before the Create Audio File section) to repeat 1 times. This tells the script to only produce one PDF and not send it, so you can test and tinker until you get your newsletter right. But there will always be errors, bugs, or other unanticipated problems to solve. It’s just another part of getting the parts working and playing nice with one another so that the whole thing comes off without a hitch.
This is a data-driven personalized publishing project, but its lessons shouldn’t be interpreted narrowly. Think about all its component elements, the different problems each individual agent has to solve, and how everything works together. Keep an eye out for concepts and tricks you can use in other kinds of automation projects. As you gain experience with graphics automation, you’ll start analyzing other projects, and through tinkering you’ll start to build a knowledge database that will make you an ever more effective automation agent writer. Half the battle sometimes is knowing what is and isn’t possible. You can learn some of that by reading books and articles, but a great deal of it will come from your hands-on discoveries.