BorderCollie for InDesign

BorderCollie is a free script for InDesign which helps with style management. It allows you to define, edit and synchronize styles and swatches across collections of disparate InDesign document collections.

This script was presented at the CreativeWow! session of the CreativePro Week 2017 in Atlanta.

Download link:

https://www.rorohiko.com/downloads/BorderCollie.1.0.0.zip

The Problem

(Note: BorderCollie is not for everyone; it will mostly be useful to users who need to maintain a large collection of InDesign templates)

Some InDesign users need to manage a large collection of InDesign templates or documents, and they need to make sure they are all set up correctly, according to some style guidelines.

The templates could be arranged logically, in some structure of nested folders. E.g. templates could be arranged by brand, by product, by customer…

Often, the document names are structured in some way and these names could encode some relevant info.

E.g. all business card templates might be called CustomerXYZ_BsCr.indt, and the _BsCr in the file name could be a code which indicates the template is for a business card.  _LrHd could indicate this is letterhead. Many companies develop some similar document naming standards, and BorderCollie can be made to use them.

Such naming convention allow for common traits to be standardized independent of the folder structure. E.g. all letterhead templates or all business card templates might need to have the exact same document size, independent of where they are located in the folder structure.

More examples: all documents might be arranged into folders by brand, and all branded documents might have a color swatch Brand Color. But the Brand Color swatch will be colored differently for each brand. Within brand XYZ this swatch needs to be defined consistently across all documents for brand XYZ. And within all documents for brand PQR a swatch by the name Brand Color will exist, but with a different color definition.

Typically, to create a new set of templates for a new customer or a new brand, one would copy a ‘base’ set of templates, then open all documents and redefine customer- or brand-dependent elements in them. This is painstaking and error-prone work.

BorderCollie

BorderCollie is a ‘herder’ for documents.

You can point it to a base folder, and it will scan that folder, and all its subfolders. It will find and inspect all .indd or .indt documents in the folder structure, anywhere below the starting point.

While BorderCollie visits all of these documents, it can be instructed to perform certain tasks along the way.

These tasks can be unconditional or conditional. You can either act on all documents, or more targeted, only on documents that match a certain requirement.

For example, tasks can be made to be dependent on the document name or document path.

A particular task could be targeted to only touch documents whose name contains _BsCr.

Another task could be targeted to only touch documents that are stored below a folder called Customer1244, in order to affect customer-specific settings.

Beware of inadvertent document version upgrades

Important: BorderCollie is a script that runs inside of InDesign.

If you run BorderCollie from a certain version of InDesign, and you let it loose on a folder structure that contains documents that were created with an older version of InDesign, then BorderCollie will upgrade all documents it visits to the version it is being run from.

Example: you have a folder full of templates for use with InDesign CS6, and you install BorderCollie in InDesign CC 2017.

You run BorderCollie on that folder. Afterwards, you’ll find that most or all documents will have been upgraded to CC 2017, and are not usable with CS6 any more.

In that case, if you want to keep the documents compatible with CS6, you need to install and run BorderCollie from CS6.

Be Safe Rather Than Sorry

To avoid major catastrophes, BorderCollie is set up to first make backup copies of any documents it re-saves in subfolders called Backup_nnnnn, with nnnnn an ever increasing number.

In addition to that, to avoid major hassles, it is highly recommended to only run BorderCollie on a copy of your document structure, and check everything thoroughly afterwards, and also to make sure good backups are available.

BorderCollie is very powerful, and it is easy to cause major self-inflicted damage.

Installing

To install BorderCollie, you need to first download the archive with the script (see download link earlier on this page).

Extract the archive, and look for a file called BorderCollie.jsxbin

Start InDesign, and make sure you can see the Scripts Panel (select the menu item Window – Utilities – Scripts).

Right-click or control-click the User folder icon and select Reveal in Finder or Reveal in Explorer from the contextual menu.

The Finder or Explorer should now show you the contents of a folder called Scripts.

Inside the Scripts folder you should see a nested folder called Scripts Panel.

Double-click the Scripts Panel folder so it opens.

Do not be tempted to drag BorderCollie.jsxbin directly into the Scripts folder. It needs to go one folder-level below, into Scripts Panel.

Drag BorderCollie.jsxbin into the Scripts Panel folder.

There might already be other scripts in the Scripts Panel folder – that’s OK.

Switch back to InDesign and look at the Scripts panel. BorderCollie.jsxbin should now be listed underneath the User entry. You might need to click the little disclosure-triangle or arrow in front of the word User to disclose the level below.

Controlling BorderCollie

To pass instructions to BorderCollie, you must create a text file called Updates.txt in the ‘base’ or ‘root’ folder where you will let BorderCollie loose.

Updates.txt will contain coded instructions for BorderCollie, one instruction per line.

Inventory

Often, the first task to tackle will be to take stock and figure out what is ‘out there’.

BorderCollie has a feature that allows you to extract and collect relevant info from all documents visited.

You can then use this info in a spreadsheet program to study the styles and swatches in your folder structure, and possibly decide on changes that are needed, or errors that need correcting.

For the sake of argument, I made a really small folder structure. 

The ‘base’ or ‘root’ folder is called Sample.

In this example, things are arranged by brand, and there are separate subfolders for each brand. For each brand, there is a business card, and some letterhead.

Your folder structures will no doubt be completely different, and arranged by different criteria, but that should not be an issue.

To get a list of all interesting info, I made a file called Updates.txt and in that text file, there is just a single line with the word list

Next, switch to InDesign and double-click BorderCollie.jsxbin  on the Scripts Panel.

A dialog should appear. Select the folder that contains the Updates.txt  file, then click Open.

BorderCollie will do its thing.

At present, there is no progress feedback – you have to wait until InDesign becomes responsive again. For a very large file collection, this might take a fairly long time.

Once BorderCollie finishes, a new file will appear in the ‘base’ folder: Inventory.txt

This is a comma-separated file which can be imported into a spreadsheet program like Excel or OpenOffice.

You can use the sorting features of the spreadsheet program to compare elements across multiple documents, and generally get a feel whether things are set up correctly or not.

The first column is a single-character code which represents the type of information:
D = Document
P = Paragraph Style
C = Character Style
S = Swatch

The next column is the name, and the following columns depend on the type of information.

Note that the keywords and values shown all over the spreadsheet are expressed in the same format you would use for formulating BorderCollie instructions.

For example, if you see ‘space=CMYK’ that would also be the way you can tell BorderCollie to set a swatch to the CMYK color space.

Style Names and style groups are structured like file path names. If you have a style group ‘ABC’ and style ‘XYZ’ then BorderCollie will refer to that style as ‘ABC/XYZ’ (no leading slash).

In some areas of the Updates.txt file, GREP expressions can be used. These are all ‘jammed’ between two slashes – e.g. /.*SpecialStyle.*/

Simple Examples

Consistent BasedOn

As an example, we want to introduce a new paragraph style into all documents, called BrandBase.

We want all other paragraph styles to be ‘Based On’ this new style.

We also want this BrandBase style to use the font Palatino, style Regular.

To accomplish that we change the file Updates.txt to contain

P,BrandBase,appliedFont=Palatino,fontStyle=Regular
P,/.*/,basedOn=BrandBase

This tells BorderCollie to perform the following operations on every document it encounters:

  1. If the style BrandBase does not exist, create it.
  2. Set the style BrandBase to have appliedFont=Palatino, and fontStyle=Regular. This also applies to documents where BrandBase already exists.
  3. Find all paragraph styles that have a name matching the GREP expression /.*/, and for each of them, change the basedOn to be BrandBase. I.e. make the style ‘Base On’ BrandBase.
    Note that this change will fail for some paragraph styles; more precisely: [Basic Paragraph], and BrandBase itself . You cannot make a style be based on itself. That is not a problem: BorderCollie will simply ignore those cases.

Before running BorderCollie, one of the files looks like this:

After running BorderCollie, the same file looks like this:

Note the new paragraph style BrandBase. I’ve also opened style body to show that it is now ‘Based On’  BrandBase.

Collapsing Styles

For the next example, we’ll be collapsing some styles. If we look at the same document, you should note that there is a paragraph style called headline and another one called  headline2.

There might be more variants out there, and the one thing they have in common is that their name starts with the word headline.

To collapse all these styles into a single style called ‘headline’, we’d use the following Updates.txt:

P,/headline.*/,replaceBy=headline

This tells BorderCollie to perform the following operations on every document it encounters:

  1. If the ‘replaceBy’ style headline does not yet exist, create it.
  2. The GREP expression matches any style whose name starts with headline. Any such style is ‘collapsed’ into the style headline. If the style that will be collapsed is referenced anywhere (e.g. applied to some text, or used as a ‘Based On’ style), the style headline will be substituted in place.

If we look at the same document we now see:

Note that the style headline2 has disappeared from the Paragraph Styles panel.

You can also see that the content in the layout has changed appearance: the text “Subtitle” now uses the same style as the “Sample”. “Subtitle” was formatted in style headline2, and is now formatted in headline.

Changing Style Colors

For the next example, we want to introduce a swatch called Brand Color and use it for the headline style.

The Updates.txt file will now contain:

S,Brand Color,model=PROCESS,space=RGB,colorValue=[200\,100\,180]
P,headline,fillColor=Brand Color

This tells BorderCollie to perform the following operations on every document it encounters:

  1. The ‘S’ code at the start of the line means: Swatch.
    If the swatch Brand Color does not exist, it is created.
  2. The swatch Brand Color is set to be a Process color, in the RGB color space, with color value RGB=200,100,180. This also happens if Brand Color already existed from beforehand.
    Note the backslashes before the two commas inside the color value. That is due to a quirk in BorderCollie: commas are normally used to separate individual elements in the line, e.g. the comma between ‘S’ and ‘Brand Color’.
    We need to make sure BorderCollie sees the colorValue as one single ‘thing’ rather than as three things separated by commas. By prefixing each comma inside the color value with a backslash (\), BorderCollie will not try to interpret the colorValue as three command elements. When specifying color values, remember to separate them instead with the two-character sequence \,
  3. The ‘P’ code means Paragraph Style.
    If the paragraph style headline does not exist, it will be created.
    The fill color for headline will then be set to be Brand Color. This also happens if the paragraph style headline already existed from beforehand.

The same document now looks like this:

We see that Brand Color was created, and assigned to paragraph style headline.

Branded Colors

The previous update was performed on all documents. For the next example, we want to use a different color definition for each brand.

The Updates.txt file now contains:

S,Brand Color,documentPath=/.*\/Brand1\/.*/,model=PROCESS,space=RGB,colorValue=[200\,100\,180]

S,Brand Color,documentPath=/.*\/Brand2\/.*/,model=PROCESS,space=RGB,colorValue=[100\,200\,150]

P,headline,fillColor=Brand Color

This is similar to the previous file, but now we have two Swatch lines. Each of the swatch lines contains a GREP expression for the document path, so we can restrict what documents each Swatch is applied to.

The first GREP expression documentPath=/.*\/Brand1\/.*/ will match only documents that contain the folder name Brand1 in their path, prefixed and followed with a slash – i.e. /Brand1/. These examples are for Macintosh. To also cover Windows, you could change the GREP expression to read documentPath=/.*[\\\/]Brand1[\\\/].*/ which will match either a / or a \ around the word Brand1.

The net effect is that we will be changing Brand Color to a different color in Brand1 vs Brand2.

Even though the two sample Business Card file started out as identical files, they are now different:

Reference

Next, a list of the possible commands you can add to Updates.txt. I have not tested all of these, and support for additional attributes can be added on an ‘as-needed’ basis.

S – Swatch

The S is followed by a comma separated list. The first element after the S is the swatch name, and then a list of zero or more keywords, followed by equal signs and values.

Keywords:

  • documentPath=/regexp/
    Only perform this operation on matching documents
  • model=PROCESS|REGISTRATION|SPOT
  • space=CMYK|LAB|RGB
  • colorValue=[n\,m\,….]
    Values separated by \,
    3 values 0-255 for RGB
    3 values 0-100,-128 – 127, -128 – 127 for Lab
    4 values 0-100 for CMYK

Example:

S,Brand Color,model=PROCESS,space=RGB,colorValue=[200\,100\,180]
S,/.*ground.*/,model=PROCESS,space=CMYK,colorValue=[50\,60\,70\,0]

P – Paragraph Style

The P is followed by a comma separated list. The first element after the P is the paragraph style name, and then a list of zero or more keywords, each followed by equal signs and values. The paragraph style name is prefixed with the group name if it is inside of a group (e.g. MyParaStyles/Headline )

Keywords:

  • replaceBy=paragraph_stylename
    If replaceBy is used, no other keywords should be used
  • basedOn=paragraph_stylename
    If basedOn is a string, it is interpreted as a style name to be used as the ‘based on’ style.
  • basedOn=/regexp/
    If basedOn is a regular expression, it is used to match only styles that have a matching basedOn style.
  • documentPath=/regexp/
    Only perform this operation on matching documents
  • fillColor=swatch_name
  • fillTint=number(0-100)
  • strokeColor=swatch_name
  • strokeTint=number(0-100)
  • alignToBaseLine=true|false
  • appliedFont=font_name
  • fontStyle=fontstyle_name
    has to be valid for the selected font_name
  • pointSize=number_with_unit
  • position=NORMAL|OT_DENOMINATOR|OT_NUMERATOR|OR_SUBSCRIPT|OT_SUPERSCRIPT|SUBSCRIPT|SUPERSCRIPT
  • autoLeading=number
  • baseLineShift=number_with_unit
  • firstLineIndent=number_with_unit
  • horizontalScale=number
  • verticalScale=number
  • hyphenation=true|false
  • leftIndent=number_with_unit
  • rightIndent=number_with_unit
  • lastLineIndent=number_with_unit
  • firstLineIndent=number_with_unit

Examples:

P,BrandBase,appliedFont=Palatino,fontStyle=Regular 
P,/.*/,basedOn=BrandBase

C – Character Style

The C is followed by a comma separated list. The first element after the C is the character style name, and then a list of zero or more keywords, each followed by equal signs and values. Thecharacter style name is prefixed with the group name if it is inside of a group (e.g. MyCharStyles/BiggerAndBetter )

In order to remove an overriding characteristic of a character style, you can set it to the word NOTHING.

Keywords:

  • replaceBy=character_stylename
    If replaceBy is used, no other keywords should be used
  • basedOn=character_stylename
    If basedOn is a string, it is interpreted as a style name to be used as the ‘based on’ style.
  • basedOn=/regexp/
    If basedOn is a regular expression, it is used to match only styles that have a matching basedOn style.
  • documentPath=/regexp/
    Only perform this operation on matching documents
  • fillColor=NOTHING|swatch_name
  • fillTint=NOTHING|number(0-100)
  • strokeColor=NOTHING|swatch_name
  • strokeTint=NOTHING|number(0-100)
  • appliedFont=NOTHING|font_name
  • fontStyle=NOTHING|fontstyle_name
    has to be valid for the selected font_name
  • pointSize=NOTHING|number_with_unit
  • baseLineShift=NOTHING|number_with_unit
  • firstLineIndent=NOTHING|number_with_unit
  • horizontalScale=NOTHING|number
  • verticalScale=NOTHING|number
  • position=NOTHING|NORMAL|OT_DENOMINATOR|OT_NUMERATOR|OT_SUBSCRIPT|OT_SUPERSCRIPT|SUBSCRIPT|SUPERSCRIPT

D – Document

A ‘D’ line indicates Document settings.

  • documentPath=/regexp/
    You can use the documentPath with a regular expression to select only specific documents. If you omit documentPath, all documents will be processed.
  • label=string
    Set the document script label
  • cmykProfile=string
  • rgbProfile=string
  • bleedBottomOffset=number_with_unit
  • bleedInsideOrLeftOffset=number_with_unit
  • bleedRightOrOutsideOffset=number_with_unit
  • bleedTopOffset=number_with_unit
  • allowPageShuffle=true|false
  • columnGuideLocked=true|false
  • createPrimaryTextFrame=true|false
  • documentBleedUniformSize=true|false
  • documentSlugUniformSize=true|false
  • facingPages=true|false
  • overprintBlack=true|false
  • pageWidth=number_with_unit
  • pageHeight=number_with_unit
  • preserveLayoutWhenShuffling=true|false
  • slugBottomOffset=number_with_unit
  • slugInsideOrLeftOffset=number_with_unit
  • slugRightOrOutsideOffset=number_with_unit
  • slugTopOffset=number_with_unit
  • startPageNumber=number

Example:

D,documentPath=/.*_BsCr.*/,pageHeight=5in