Developing an ImageLink Provider Script

This is intended to describe how to write a provider script.

Overview

The Plug-in enables connection to any DAM or online image resource via a provider script that manages interaction with its REST API. This is a single script containing a number of key callback functions, prefixed with cb_.

Scripts are stored in locally in the preference folder. This can be located using ImageLink section of the InDesign preferences. Scripts are implemented Lua. This is a powerful, efficient, lightweight scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description.

Script Operation

Configuration Options

On startup the cb_getconfiguration function for each Provider gets executed. This returns a table of properties which configure the Provider, both in terms of user interface and the underlying link subsystem within InDesign.

The key property is the scheme. This is the first component of a URI, which is used to identify which provider manages it. Its name should be unique, and confirm to URI standards. Typically it would be a DAM system name or similar. The scheme name should not start with a digit and should not contain spaces. Only one installed provider per scheme is allowed.

Storing Data

A Provider can store data for later retrieval into the preferences folder using a call to PROVIDER.setdata. This can be passed any Lua type and serialises the data for later retrieval by PROVIDER.getdata. A Typical use would be to store server location, username and password details.

Session Data

A ‘session’ is defined as the period InDesign is running, so empty on startup. A call to PROVIDER.setsession stores data for later retrieval by PROVIDER.getsession. A Typical use would be to store authentication tokens, etc.

Global Variables

Each callback is run in it’s own Lua state, so global variables cannot be used between callbacks.

Multi-Threading

Certain callbacks are made on worker threads so must be thread-safe. The majority of calls to check an assets status are made this way. All utlility functions provided by the Plug-in are thread-safe.

Status Checking

For each linked image, InDesign periodically checks its state to update its status in the Links panel. To enable this process to be efficient, URIs are batched into a single request to the cb_getassetstatus callback. Maximum batch size is limited by the batchlimit configuration settings. Calls to getassetstatus are made aysnchronously, so although the time taken to intiate a new Lua state is neglibale, a performance improvement is to be had by batching requests, even if this ends up as a single request made to the DAM.

Batching can also be controlled by the batchlimittimems settings. This specifies the maximum time that can elapse before a batch request is made. For example, if the batchlimit was 10, but only 2 requests are pending within this time, the request for 2 is made.

To allow further control, minimumcheckintervalinms can be used. A value of zero means status checking will be as often as InDesign requests, which could potentially cause loading issues on a server. Once an asset has been checked, if a subsequent check on the same URI is requested in less time than specified by this parameter, the previous asset state is reused.

Drag and Drop from an External Application

When an image is dragged from an external source, such as a Browser and dropped on an InDesign layout, the Plug-in extracts the image source (if available) and calls cb_convertexternallink. This inspects the URI and decides if it can handled it. If it can, it returns how confident it is in handling it along with a modified URI that can be placed in InDesign. All providers are checkeed and the provider with the highest confidence is chosen. If more than one provider is found, the user will be presented with a choice of which to use.

Image Downloading

The download of the images is performed by InDesign using a GET operation. In preparation cb_preparedownload is called, which fixes the URI and provides HTTP header information. Preview images use the same callback, but are downloaded by the Plug-in.

JSON Parsing

CSJON is built into the Plug-in. It provides fast, standards compliant encoding/parsing routines and full support for JSON with UTF-8, including decoding surrogate pairs.

External Modules

The preferences folder contains a require folder where external modules can be placed for use by the provider.

Scripting

External scripts can be used to connect and place images. The URI scheme should match that of a provider. E.g:

cb_scripthttpconnect is called in response to app.httpLinkConnectionManager.httpConnect.

Debugging

To aid debugging there is debug option in the preferences. This enables reloading of the script everytime the Provider menu option is selected. It also logs most operations into the logs folder within the preferences. Ensure this option is turned off during normal operation as it has an impact on performance.

Remote debugging is supported using the ZeroBrane Studio IDE.

To Debug:

  • Copy mobdebug.lua and socket.lua into any location checked by the ‘require’ command (A list is shown if the module cannot be found). These are available from the ZeroBrane download.
  • Launch the IDE. Go to Project | Start Debugger Server and start the debugger server (if this menu item is disabled, the server is already started)
  • Add require(‘mobdebug’).start() call to your script.
  • Test your script. You should see a green arrow pointing to the next statement after the start() call in the IDE and should be able to step through the code

Sample Script for Pexels

A simple script with no folder browsing or authentication. The authorisation code has been redacted:

 

Sample Script For Our Demo DAM

A more complex example incorporating authentication, folder browsing and FPO image support.