Release: InCatalog 2.34 for InDesign 2023-2025

This release improves accessibility, fixes ExtendScript method names on macOS, and publishes an updated scripting reference.

Update

To update, download and install the latest version from the product’s installation section.

Changes

Changes the default link marker color to a more visible reddish orange instead of light gray.
Adds commands for the Data Linker panel’s update buttons that can be accessed as the InCatalog Data Linker Menu product area in the Keyboard Shortcuts dialog, and with Quick Apply (when the Data Linker is open and its corresponding buttons are enabled).
Adds an Update Linked Element action, available in the InCatalog Data Linker Menu product area for keyboard shortcuts and Quick Apply, that can be used to update the contents of the current linked element, or of each element of the containing group, if the linked element is part of a group, or of each cell in the current table, if the linked element is in a cell.
Deprecates the ExtendScript methods updateDocument(usingFile, usingString,...) and updateData(usingFile, ...) on macOS. In place of updateDocument(), now use either updateDocumentUsingFile(snapshotFile, dataFormat, ...) or updateDocumentUsingString(snapshotString, dataFormat, ...), depending on the data source. Instead of updateData(), now use updateDataUsingFile(snapshotFile, ...). This change homogenizes InCatalog’s scripting environment and lets the same JSX file work with either OS. (macOS only)

Event names in AppleScript (update document and update data) are unaffected.

✻

InCatalog Automation Reference

InCatalog provides a number of methods/events and properties for updating linked elements in the document (update document), for updating the source data from linked elements (update data), and for creating and managing links (catalog link data). In general, the scripting interface exposes and expands on functionality provided by InCatalog’s user interface.

Here we describe the ExtendScript/JSX interface (which applies to UXP and Visual Basic too). The AppleScript interface (macOS only) is similar and can be viewed by opening InDesign’s scripting dictionary (with InCatalog installed) in the macOS Script Editor application.

InCatalog Preferences

Properties on: InCatalogPreferences

Property	Type	Access	Description
`markersShowing`	bool	r/w	If true, link markers are visible
`markerColor`	3 Reals UIColors	r/w	The color of link markers, specified either as an array of three doubles, each in the range 0 to 255 and representing R, G, and B values, or as an InDesign UI color. Can return: Array of 3 Reals (0 – 255) or UIColors enumerator.

Preferences examples:

app.incatalogPreferences.markerColor = UIColors.LIGHT_BLUE;
app.incatalogPreferences.markerColor = [225, 101, 82];
app.incatalogPreferences.markersShowing = true;

InCatalog Settings

Properties on: Document

Property	Type	Access	Description
`catalogDDSet`	string	r/w	The data descriptor set name associated with this document

InCatalog Updating

Update Methods

The first grouping of methods are the original, work-with-the-whole-document methods, while the second grouping — new with InCatalog 2.34 — limit their update to their hosting object (and shed the unneeded scope-of-update parameters that the whole-document methods provide).

All update methods return either the number of linked elements that were updated or a string containing the error log.

For brevity, parameters, common to all methods, are described after the list of methods.

Methods on: Application, Document

// Update the contents of the document's link elements
// from the provided database snapshot file/path.
updateDocumentUsingFile(snapshotFile[, dataFormat, unquotedData,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update the contents of the document's link elements
// from formatted data in the provided string.
updateDocumentUsingString(snapshotString[, dataFormat, unquotedData,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update the contents of the document's link elements
// from one or more ODBC tables.
updateDocumentUsingODBC([dsn, userName, password,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update the contents of the document's link elements
// from one or more open FileMaker Pro databases. (macOS only)
updateDocumentUsingFileMaker([runtime,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update/create the contents of the provided snapshot file
// from the document's linked elements' contents.
updateDataUsingFile(snapshotFile[, dataFormat, unquotedData,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    picturePathLevels, recordCreation, snapshotCreation, posixPaths])

// Update/create the contents of one or more ODBC tables
// from the document's linked elements' contents.
updateDataUsingODBC([dsn, userName, password,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    picturePathLevels, recordCreation, posixPaths])

// Update/create the contents of one or more open FileMaker Pro
// databases from the document's linked elements' contents. (macOS only)
updateDataUsingFileMaker([runtime,
    ddSet, dd, ddContents, ddMap,
    firstPage, lastPage, firstSpread, lastSpread, selectedGroup, selectedFrame,
    picturesIgnored, hiddenLayersIgnored, masterPagesIgnored,
    unusedParameter,
    picturePathLevels, recordCreation, posixPaths])

Methods on: Spread, Layer, Page, Group, PageItem, Table, Cell, TextFrame, TextColumn, Story, Text, Paragraph, Line, Word, Character, TextStyleRange, InsertionPoint

// Update the contents of the object's link elements
// from the provided database snapshot file/path.
updateDocumentUsingFile(snapshotFile[, dataFormat, unquotedData,
    ddSet, dd, ddContents, ddMap,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update the contents of the object's link elements
// from formatted data in the provided string.
updateDocumentUsingString(snapshotString[, dataFormat, unquotedData,
    ddSet, dd, ddContents, ddMap,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update the contents of the object's link elements
// from one or more ODBC tables.
updateDocumentUsingODBC([dsn, userName, password,
    ddSet, dd, ddContents, ddMap,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update the contents of the object's link elements
// from one or more open FileMaker Pro databases. (macOS only)
updateDocumentUsingFileMaker([runtime,
    ddSet, dd, ddContents, ddMap,
    keyUpdating, documentDisplaySuppressed, fuzzyPictureLookup, partialData])

// Update/create the contents of the provided snapshot file
// from the object's linked elements' contents.
updateDataUsingFile(snapshotFile[, dataFormat, unquotedData,
    ddSet, dd, ddContents, ddMap,
    picturePathLevels, recordCreation, snapshotCreation, posixPaths])

// Update/create the contents of one or more ODBC tables
// from the object's linked elements' contents.
updateDataUsingODBC([dsn, userName, password,
    ddSet, dd, ddContents, ddMap,
    picturePathLevels, recordCreation, posixPaths])

// Update/create the contents of one or more open FileMaker Pro
// databases from the object's linked elements' contents. (macOS only)
updateDataUsingFileMaker([runtime,
    ddSet, dd, ddContents, ddMap,
    picturePathLevels, recordCreation, posixPaths])

Update Enumerations

SnapshotFormatType

Name	Description
`SnapshotFormatType.TAB_DELIMITED`	tab-delimited fields, return-delimited records
`SnapshotFormatType.COMMA_DELIMITED`	comma-delimited fields, return-delimited records
`SnapshotFormatType.FOXPRO_TAB_DELIMITED`	Foxpro/Foxbase-style tab-delimited fields, return-delimited records

Update Method Parameters

Unless otherwise specified, default values for optional parameters are taken from either the active data descriptor or InCatalog’s preferences settings.

Note: use undefined as a placeholder value for optional parameters (see examples, below).

Snapshot file

Name	Type	Description
snapshotFile	File \| string	Required. The data snapshot file to be imported, updated, or, if it doesn’t exist, created and filled.
dataFormat	SnapshotFormatType	Optional. The delimited snapshot file’s format (default is from Data preferences).
unquotedData	bool	Optional. Set to `true` if the delimited fields do not all have quote marks around them (default is from Data preferences).

ODBC connection

Name	Type	Description
dsn	string	Optional. The system- or user-level data set name (DSN) for the ODBC connection (default is from the current DD’s `&` qualifier).
userName	string	Optional. The user name for the ODBC login (default is from the current DD’s `$` qualifier).
password	string	Optional. The password for the ODBC login (default is from the current DD’s `!` qualifier).

FileMaker Pro session (macOS only)

name	type	description
runtime	bool	Optional. Set to `true` if the connection is a FileMaker Pro Runtime application database (default is `false`).

DD Set

name	type	description
ddSet	File \| string	Optional. The location of the DD set folder (default is the current DD set).
dd	string	Optional. The name of the data descriptor in the DD set (default is the current DD).
ddContents	string	Optional. The actual DD contents to use in lieu of a DD set and DD.
ddMap	string	Optional. The name of the DD map to use (default is the default/unnamed map).

Scope of update (whole document updates only)

name	type	description
firstPage	number	Optional. The start of the page range for the update (default is 1).
lastPage	number	Optional. The end of the page range for the update (default is the last page in the document).
firstSpread	number	Optional. The start of the spread range for the update (default is 1).
lastSpread	number	Optional. The end of the spread range for the update (default is the last spread in the document).
selectedGroup	bool	Optional. Set to `true` to limit the update to the currently-selected group (default is `false`).
selectedFrame	bool	Optional. Set to `true` to limit the update to the currently-selected frame (default is `false`).
picturesIgnored	bool	Optional. Set to `true` to skip any picture frames during the update (default is `false`).
hiddenLayersIgnored	bool	Optional. Set to `true` to skip any elements on hidden document layers (default is `false`).
masterPagesIgnored	bool	Optional. Set to `true` to skip any elements on master pages (default is `false`).

Document update

name	type	description
keyUpdating	bool	Optional. Set to `true` to update keys in the data links themselves instead of the document contents (default is false). The DD must describe three fields: old key value (as the key), new key value, optional DD name.
documentDisplaySuppressed	bool	Optional. Set to `true` to hide document changes during the update (default is from Update preferences).
fuzzyPictureLookup	bool	Optional. Set to `true` to import pictures using “fuzzy” picture lookup (ignoring file prefix/suffix; default is from Update preferences).
partialData	bool	Optional. Set to `true` if, when a record isn’t found, it’s not an error (default is `false`).

Data update

name	type	description
picturePathLevels	number	Optional. The number of picture path levels to extract, where 0 (zero) means “all” (default is from Create/Update preferences).
recordCreation	bool	Optional. Set to `true` to create records as needed (default is `true` if the snapshot file is being created; otherwise, is from Create/Update preferences).
snapshotCreation	bool	Optional. When `true`, the snapshot file is fully created (fleshed out) from the .x file when the update finishes; otherwise, the collected data are simply left in the .x file for a later time — disabling this is only useful for the case of huge snapshot files (default is `true`).
posixPaths	bool	Optional. When `true`, extract POSIX-style paths instead of classic HFS-style paths (macOS only, ignored on Windows; default is from Create/Update preferences).

Updating examples:

var snapshotFile = "/Users/Em/Documents/GroovyData.csv";
var dataUnquoted = false;  /* fields are quoted */

// Update linked elements in the current document's selected frame.
app.activeDocument.updateDocumentUsingFile(
    snapshotFile, SnapshotFormatType.COMMA_DELIMITED, dataUnquoted, /* snapshot parameters */
    undefined, undefined, undefined, undefined, /* DD Set parameters */
    undefined, undefined, undefined, undefined, undefined, true /* Scope group parameters*/);

// Update all linked elements in the current document.
app.activeDocument.updateDocumentUsingFile(snapshotFile, SnapshotFormatType.COMMA_DELIMITED, dataUnquoted);

// Update the contents of all linked elements in a frame on the active document's first page.
app.activeDocument.pages[0].rectangles.everyItem().updateDocumentUsingFile(snapshotFile, SnapshotFormatType.TAB_DELIMITED, dataUnquoted);

// Update the snapshot file with the content of all linked items on the first spread.
app.activeDocument.spreads[0].updateDataUsingFile(snapshotFile, SnapshotFormatType.TAB_DELIMITED, dataUnquoted, undefined, undefined, undefined, undefined, undefined, undefined, undefined, true /* use POSIX paths */);

InCatalog Links

Properties on: PageItem, Cell, Text, Paragraph, Line, Word, Character, TextStyleRange, InsertionPoint

Property	Type	Access	Description
`catalogLinkData`	`Array of Any` NothingEnum	r/w	the catalog link information associated with the object or `NOTHING` if no link is applied. If a text element contains more than one link, only the first link is returned. Applying `NOTHING` removes/ deactivates an existing link

Where Array of Any is, for historical reasons, an ordered list of values:

Index	Name	Type	Description
0	DDName	string CatalogDefaultValue	Required. The name of the link’s associated DD or `DEFAULT_VALUE` to use the current DD’s name. An empty name clears an existing link.
1	keyName	string	Required. The link’s key or, for indirect key types, the “fallback” key (which may be empty) to use when an indirect key can’t be found.
2	fieldName	string	Required. A valid field name from the specified DD.
3	keyType	CatalogKeyType CatalogDefaultValue	Optional. The link’s key type (default is key from link unless the specified DD is active and the field’s DD entry provides a value via the `L”x”` qualifier).
4	subfield	number CatalogDefaultValue	Optional. The one-based subfield or 0 (zero) for no subfield (default is 0).
5	picturePosition	CatalogPicturePosition	Optional. How an updated graphic is positioned (default is `AS_IS`).
6	priceStyle	string CatalogDefaultValue	Optional. The name of the associated price style, if the linked text element is a price (default is an empty string unless the specified DD is active and the field’s DD entry provides a value via the `P”style”` qualifier).
7	isPrice	bool CatalogDefaultValue	Optional. The linked text element is a price (default is `false` unless the specified DD is active and the field’s DD entry provides a value via the `P`, `T`, or `U` qualifier).
8	isTagged	bool CatalogDefaultValue	Optional. The linked text element is tagged text (default is `false` unless the specified DD is active and the field’s DD entry provides a value via the `P`, `T`, or `U` qualifier).
9	convertQuotes	bool CatalogDefaultValue	Optional. Whether straight quotes should be converted to typographer’s quotes, if the linked text element is tagged text (default is true unless the specified DD is active and the field’s DD entry provides a value via the `T` or `U` qualifier).
10	isCurrent	bool CatalogDefaultValue	Optional. A flag indicating the state of the linked element that’s reset to `true` with every update. Links marked as dirty/not-current (by a script) are displayed with red link markers in the UI until they’re updated.

Link Enumerations

CatalogDefaultValue

Name	Description
`CatalogDefaultValue.DEFAULT_VALUE`	placeholder within `Array of Any`

CatalogKeyType

Name	Description
`CatalogKeyType.FROM_LINK`	use the key provided by the link
`CatalogKeyType.FROM_GROUP`	obtain the link’s key from the containing group
`CatalogKeyType.FROM_TEXT_BACKWARDS`	obtain the link’s key from the text looking backwards
`CatalogKeyType.FROM_TEXT_FORWARDS`	obtain the link’s key from the text looking forwards
`CatalogKeyType.FROM_CONTENTS`	obtain the key from the linked text or linked element’s contents
`CatalogKeyType.FROM_TEXT_UPWARDS`	obtain the key from the text looking upwards
`CatalogKeyType.FROM_TEXT_DOWNWARDS`	obtain the key from the text looking downwards

CatalogPicturePosition

Name	Description
`CatalogPicturePosition.AS_IS`	leave the picture where it is
`CatalogPicturePosition.DEFAULT_VALUE`	position the picture in the upper-left corner of the frame
`CatalogPicturePosition.CENTERED`	center the picture in the frame
`CatalogPicturePosition.FITTED`	resize the picture to fit the frame exactly
`CatalogPicturePosition. FITTED_PROPORTIONALLY`	resize the picture such that its greater dimension fits the frame exactly and its aspect ratio is maintained
`CatalogPicturePosition. FILLING_PROPORTIONALLY`	resize the picture such that its lesser dimension fits the frame exactly and its aspect ratio is maintained
`CatalogPicturePosition.IN_SIZED_FRAME`	resize the frame to fit the picture exactly
`CatalogPicturePosition. FITTED_HORIZONTALLY_ IN_VERTICALLY_SIZED_FRAME`	resize the picture to fit the frame’s width exactly, then resize the frame’s height to fit the picture exactly

Linking examples:

// Apply a data link to the selected page item.
app.activeDocument.selection[0].catalogLinkData = [CatalogDefaultValue.DEFAULT_VALUE, "1-100", "price", CatalogKeyType.FROM_LINK];

// Apply a data link to the second word of the first story.
var theStory = app.activeDocument.stories[0];
theStory.words[1].catalogLinkData = [CatalogDefaultValue.DEFAULT_VALUE, "1-100", "price"];
// Remove the just-applied link.
theStory.words[1].catalogLinkData = NothingEnum.NOTHING;