Want a way to do this automatically and also pick different styles to use?
Back in 2010 Matthijs Collard of UNITiD created a great script for Creating a Table of Contents in OmniGraffle with AppleScript. Over the years this script has been used by many in the UX community, including the team here at iQ, and it has saved people so many hours of frustrating work. We’re all still waiting for the mythical Omnigraffle 6 to include this functionality but in the meantime, here’s an extension to that script that enables a selection of styles for your Table of Contents (ToC).
What we did
Recently a couple of my colleagues asked me to review a document they had produced in Omnigraffle that had over 120 pages in it. I noticed that whilst the rest of the document looked great with the content broken out into clear sections the ToC automatically generated didn’t really help to orient the user without any form of hierarchy or emphasis.
So I wondered if I could play around with the scripts a bit to make something that fitted the needs of the project better. I ended up creating four new ToC styles to suit different needs and preferences.
The outcomes of my experiments are available to download as AppleScript files - Table of Contents scripts (74 kB).
I’ve also created some samples files to download (5.4 MB) including a blank Omnigraffle template file as well as samples with each of the different styles applied.
How to run the scripts
1. Open your target Omnigraffle document.
If you are using the downloaded sample files, create a copy of the blank sample provided.
If you have numerous Omnigraffle docs open, just make sure the one you want to add the table of contents to is the active document.
It is not necessary to have the Table of Contents canvas selected but I like to have it open with the Outline pane visible. That way you can see the elements being added automatically to the page as the script runs.
2. Open the script file you want to use in AppleScript Editor.
You may want to configure the script to suit your file and styles. Most of the elements to change are at the start of the file with comments on what to change. The scripts as is have been configured for the sample files provided.
3. Click the Run button on the AppleScript Editor toolbar.
If there are more canvases in the file than titles can fit on one canvas then additional Table of Contents canvases will be automatically added.
The sample file provided has 121 canvases included so you can see how the ToC works with a long document. Hopefully the sample files are helpful to play around with and see what style might suit your needs best.
The different styles
Script file: ToC_1_AllCanvases_DividerLine.scpt
This is a copy of the original Table of Content script. All canvases are included in the ToC with the same emphasis. A divider line is added between each canvas name. Additional canvases are added if the Table of Contents runs over more than one canvas. In the sample file 1 you’ll see the ToC runs over four pages. This style probably works best for shorter documents. See below for a better style to use with long documents.
Script file: ToC_2_AllCanvases_Sections.scpt
At iQ Content we tend to separate our longer documents into sections using a section header canvas. This script will search through your document to find the section divider canvases and ‘promote’ this in the Table of Contents as headings. All other canvases will be considered sub-pages within the sections. The sub-pages are indented with smaller font size and different colour styles. It now makes it much easier to scan through a long ToC and see what is included.
How this works: Have a look in the sample files provided. The section header canvases all have a shared layer called ‘Section Divider’ in them. The script searches all canvases to see if it has a layer called ‘Section Divider’ and if so, it is made into a heading. Therefore it is possible to make any canvas a heading if you want to – see the canvas in the sample files called ‘Introduction’ as an example.
Note: The links in exported pdf still work for both section headings and sub-pages.
Script file: ToC_3_SectionTitlesOnly_DividerLine.scpt
The Style 2 ToC does a good job of making a long table of contents much easier to read but sometimes you just want a quick way to get to the main sections of a document rather than needing to list every page. So this script only shows the section headers in the Table of Contents. In the sample file there are 12 section headers so the Table of Contents fits neatly on one page rather than the four pages in the Style 2 version.
Script file: ToC_4_SectionTitlesOnly_DottedLine.scpt
I went through a number of different document styles we use in Omnigraffle and found that where people had created their own Summary pages they had followed a style that used a dotted line between the title and page numbers similar as you might find in a text book.
So this scripts creates a Section Titles Only ToC as in Style 3 but in this case has implemented the dotted line style that some of our UX folk prefer.
Rather than actually trying to work out what length of dotted line is needed the workaround is to layer the dotted line behind the text. The text elements are then adapted to have a white background and the text style set to auto-size to the length of the content.
Script file: ToC_5_AllCanvases_DottedLine.scpt
This implements the dotted line style into the original script showing all canvases with equal weighting.
If you want to find out what the AppleScript for a particular style in Omnigraffle is, use the Copy As > AppleScript option from the Edit or context menu.
For example, if you’d like to change the style of the dotted line used in scripts 4 & 5, draw the style you’d like in Omnigraffle, select the line and Copy As > AppleScript and then paste into the Apple Script editor. You’ll see the code for the Omnigraffle object in AppleScript. The stroke pattern for the dotted line in the example below is 1. Try out different stroke patterns to get a style you like.
Hope these scripts are useful.
This was my first foray into the world of AppleScript so if you can suggest any improvements or if you create any additional styles yourself that you think others might like, please add to the comments below.
Happy New Year from all at iQ Content!
Table of Contents scripts (74 kB)
Sample files (5.4 MB)
This project was undertaken as part of the iQ Labs initiative.