Custom Adobe InDesign scripts can save publishers time, trouble, and money by automating complex layout and design tasks. While scripts are usually deployed via InDesign’s scripting panel, they can also be incorporated directly into Typefi workflows to expand on the composition engine’s core functionality.
All custom InDesign scripts are designed to run at a specific event. This webinar, the first in our DO MORE with Scripting series, explains the nature of these events, and provides a solid foundation for those who want to start writing scripts for Typefi workflows.
This introductory webinar is also useful for anyone who uses Typefi Server, and who would like to learn more about how to deploy scripts in a Typefi workflow.
Introduction
The Typefi system was originally conceived as a scriptless automation system for composing InDesign documents, and in principle the core system can produce great-looking publications without any additional custom scripts.
However, the reality is that most jobs require some customisation. For example, a recent quick round-up revealed that we have only one customer who runs Typefi without any custom scripts.
Scripting is, therefore, an essential part of InDesign when it’s used to create complex documents.
Adobe claimed in their InDesign CS6 Scripting Tutorial that: “Scripting is the most powerful feature in Adobe InDesign. No other feature can save you as much time, trouble, and money as scripting.” I fully agree with that—I saw that when I worked as a typesetter, and it’s true in Typefi workflows too.
This webinar is about the role and the content of scripts in Typefi workflows. Typefi’s composition system—affectionately called ‘the Engine’—is a very big and complex JavaScript itself.
In the webinar series, we’ll show how you, as a user, can extend the Engine’s general functionality with custom functionality to tackle things that aren’t covered by the Engine.
In this first episode, we’re not yet going into writing scripts. Because custom scripts have to run at some event, you have to know the nature of these events before you can start writing scripts for Typefi workflows.
This first part is useful also for people who operate Typefi and want some background on the script events and on deploying scripts.
Script events (2:59)
All custom InDesign scripts are designed to run at a specific event. Those events can be seen on the Event Scripts tab of Typefi’s Create InDesign Document and Create InDesign Book actions.
The interface you see here is that of Typefi Server 8.4. It looks very much the same as earlier versions, but has several functional improvements.
The window shows the events largely in chronological order. I say ‘largely’ mainly because the spill.end event can occur just once during a job run (in theory) or many times, even several times on the same page.
The last item, Parameters, isn’t a script event. The field can be used to pass on directives to one or more scripts.
Book start (3:42)
At book.start all you have is an empty book file. No documents have been opened yet or added to the book. Essentially, a script has access only to the book file’s properties. If you were to stop a job right after the book.start event, all you’d see on your screen is an empty book file.
This event is only ever used to apply hotfixes (in single-document jobs, hotfixes are applied at document.start).
Document start (4:37)
At document.start, the Typefi Engine has opened a copy of the template and prepared it for the job: all pages after the first page are removed, the first page is cleared, and the document is saved using the name specified in the General tab.
Various checks are made and set for pagination (and reset when the job finishes). For instance, the unit of measurement is set to points, the rulers are set to page, and the zero point is set correctly.
At document.start you can do things like activate certain layers (informed, for example, by the contents of a Typefi field), set a spot colour, and change all or selected paragraph styles. What you can do at document.start can often be done at document.end as well, but document.start is more efficient because the document is much smaller.
Section start (5:34)
Not used.
Spread start (5:56)
At spread.start a script sees the first page of the spread (the left-hand page in left-to-right workflows). This event is used only very rarely—we’ve done just one.
Page start (6:25)
At page.start the Typefi Engine has added a new page and has overridden all master elements onto the page. If there’s a main story frame on the page and if there is a previous main story frame, the main story is threaded. The same goes for table of contents (TOC) and index frames. Floating and fixed elements have not yet been placed.
At page.start a script can place, for example, a continuation notice, or place a jump frame to extend a boxed story, including figure captions.
In general, run a script at page.start if you want to do things to a page before the Typefi Engine starts placing floats on that page.
Note: The above description does not hold for the first page of a section. On these pages, no frames have been placed or overridden at page.start.
Spill end (7:30)
At spill.end the Engine has read a story from the CXML, formatted it, and placed it in a text frame. This includes any anchored frame, index markers, and any tables embedded in a story. Floats are separate spills.
If the story is a main story, it will usually be overset. Because most of the story will be overset at spill.end, spill.end scripts typically can’t deal with geometry: properties such as horizontalOffset, baseline, and geometricBounds are not available at spill.end for the part of the story that’s overset. (Frame sizes are available to AutoFit; we’ll turn to that in a later session.)
Scripts that change the content of a story must run either at spill.end or, if they depend on page geometry, at page.end. Spill.end scripts are effective and efficient, especially in books with a small number of stories, such as novels.
Several Typefi script modules run at spill.end—among others, Conditional Spacing; Conditional Keeps (these scripts query just paragraph style names); alignment to the baseline of MathType equations (the baselines are read from the EPS files); and the GREP module.
If a job can be done at spill.end, do it—it’s an efficient event to run scripts in. In a later session we’ll see some examples of scripts whose deployment at spill.end seems counter-intuitive but, in fact, makes sense and is efficient.
Page end (9:42)
At page.end the Typefi Engine is done with the page—all text and all floating and fixed elements have been placed. If there aren’t any floats to be placed, a page looks the same at page.start and page.end.
Spread end (10:17)
This event coincides with page.end at a right-hand page (in a left-to-right workflow). This event is used only very rarely.
Section end (10:27)
A Typefi section has been finished. Typefi sections coincide with InDesign sections in a document. In a book job, each Typefi section is produced as a separate document. A typical section.end script is one that places thumb tabs at the edge of every page.
Index start (11:35)
Any index markers are processed at spill.end, so the index that you see in the Index panel in an InDesign document is built up while the document is paginated.
At index.start, therefore, all index markers have been processed so that InDesign’s Index panel is now populated. But the index has not yet been generated—at index.start the Engine is about to do that.
At index.start, scripts have full access to the Index panel and can be used, for instance, to set or change sort-order fields, fix InDesign’s page-range anomaly, and whatever else can be done in the Index panel.
Index end (12:30)
The index has been generated, placed, and paginated. Use any scripts that need to see the finished index; for example, to place repeat topics.
Document end (12:50)
At document.end the document is finished, including the index and the table of contents. Scripts have access to the full document. This event is comparable to opening a document in your desktop InDesign and running a script from InDesign’s Scripts panel.
When run as part of a job, document.end scripts must not change the page layout so as to avoid misaligning the table of contents and/or the index. If a script does change the text flow that script has to update the TOC and the index.
Scripts run at document.end can add things to pages that don’t change the layout, such as placing bars in the margins and shaded backgrounds. Other typical document.end scripts are those that manipulate running headers, log various types of document diagnostics such as missing glyphs, and mark overset text frames and table cells.
Book end (14:10)
All book files have been finished, the table of contents (if present) was redone, any cross-references have been updated, and the index generated. The book.end event, too, is comparable to a desktop situation: open a book, open all its content, and run a script from InDesign’s Scripts panel. Like document.end scripts, book.end scripts must not change the layout of any documents.
Parameters (14:42)
Script parameters can be used to pass on information to one or more scripts; for example, to run a job with a certain spot colour, or to differentiate proof and print jobs.
Script parameters are strings and can take any form in principle, but it’s good practice to use JSON (which stands for JavaScript Object Notation), for example: {'spotColour':'Red'} and {'output':'Proof'}. JSON is a JavaScript standard and is a well-understood way of passing information.
Several pieces of information can be combined in one string, as in:
{'spotColour': 'Red', output: 'Proof'}Parameters set in the Parameters field can be accessed by all scripts. More complex parameters can be handled differently; for instance, in configuration tables in the template.
About Peter Kahrel
Peter was born in Amsterdam, the Netherlands. He trained as a linguist at the University of Amsterdam and has an MA and a PhD, specialising in syntax, semantics, and typology. He has lived in the UK since 1994, working as a typesetter, editor, copy-editor, and indexer (and sometimes as a designer too) for publishers in the UK, the Netherlands, and Germany, preparing for the press both books and journals. He combined this with teaching at the Linguistics Department at Lancaster University.
Peter has been programming InDesign with JavaScript since 2003, mainly to cut out the tedium that faces every typesetter and indexer but in equal measure because it’s good fun. Peter has worked as a script developer at Typefi since 2010, and is highly regarded in the global InDesign scripting community.
Check out Peter’s website—which includes a bunch of free scripts—at CreativePro.