This guide explains how to write an ImageLink provider in Lua, from the initial configuration through browsing, placing and updating assets.
1. Start with a small provider
A provider connects ImageLink to a DAM or online image service. ImageLink calls functions in the provider script to retrieve assets, authenticate with the service, prepare downloads and check existing links.
Save the Lua script in the providers folder inside the ImageLink preferences folder. Its location is shown in ImageLink’s preferences. The script uses Lua and the APIs supplied by ImageLink.
Choose a URI scheme
The scheme identifies which provider owns a link. For example, example://images.example.com/photo.jpg belongs to the provider that declares scheme = "example". Its download callback can translate that URI into an HTTPS URL understood by the server.
Choose a scheme unique to your provider. Keep the provider’s asset identity separate from any temporary download URL or authentication token.
Register the provider and return an empty asset list
This scaffold declares a provider with no Login command, no FPO renditions and no paging. It returns an empty asset list so you can establish the structure before adding your service’s API calls. It is a starting point, not a complete DAM integration.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | function cb_getconfiguration() return { name = "Example DAM", scheme = "example", version = "1.0.0", login = false, fpo = false, supportspaging = false } end function cb_getassets(query_string, path, page) return 1, {} end |
Add callbacks as you implement each capability:
| User action or event | Callback | Script responsibility |
|---|---|---|
| Provider initialises | cb_getconfiguration | Declare its identity and capabilities. |
| User logs in, when enabled | cb_login, then cb_connect | Collect credentials, allow a connection, then authenticate. |
| User browses or searches | cb_getfolders, cb_getassets | Return folders, assets and page information. |
| User places an asset or changes rendition | cb_getasseturi, cb_preparedownload | Resolve the rendition, then supply a downloadable URI and request headers when downloading. |
| InDesign checks a link | cb_getassetstatus | Report availability and revision information. |
| User logs out | cb_logout, if supplied | Optionally revoke server credentials before ImageLink clears its connection session. |
These are the main interaction points, not a single fixed callback sequence. Downloads and status checks can recur independently, and some calls run on worker threads.
2. Configuration reference
cb_getconfiguration returns the provider’s configuration table. name, scheme and version are required. Add the optional properties needed by your service to the same table.
| Option | Lua type | Required / default | Purpose |
|---|---|---|---|
name | string | Required | User-facing provider name, used in provider selection and management UI. An empty value disables the provider. |
scheme | string | Required | URI scheme owned by the provider, such as dropbox or pexels. It is the primary key used to route links and callbacks to the provider. |
version | string | Required | Provider implementation version. Displayed in provider-management UI and used when comparing installed and available provider versions. |
login | boolean | true | Whether the provider supports an explicit login/logout workflow. When false, login/logout actions are disabled and the provider is treated as connected without a login session. |
fpo | boolean | false | Whether the provider supports FPO (For Placement Only) renditions. When enabled, ImageLink can request and place FPOs according to the user’s preferred link type. |
embedonly | boolean | false | Forces placed assets to be embedded in the InDesign document regardless of the user’s preferred link type. |
headersize | integer | 30 | Height, before UI scaling, reserved beneath each preview for provider-rendered asset information. |
url | string | Empty | Provider/site URL. It is used to construct the fallback favicon request when faviconuri is absent. |
infotext | string | Empty | Default text shown in the information/link area of the ImageLink panel. It may later be replaced by cb_getinfolinktext. |
infolink | string | Empty | Hyperlink destination used with infotext in the ImageLink panel. It may later be replaced by cb_getinfolinktext. |
description | string | Empty | Provider description. The current ImageLink implementation stores this value but does not display or otherwise consume it. |
domain | string | Empty | Provider domain. The current ImageLink implementation stores this value but does not otherwise consume it. |
cachetype | string | Defer to user preference | Overrides the provider’s cache system. Accepted values are imagelink and indesign. Any other value causes configuration to fail. |
batchlimit | integer | 10 | Maximum number of assets passed in a metadata/status batch to InDesign’s HTTP link subsystem. |
batchlimittimems | integer | 1000 | Batch time limit in milliseconds reported to the HTTP link subsystem. |
minimumcheckintervalinms | integer | Metadata preference × 1000; initially 60000 | Minimum age in milliseconds before cached asset status/metadata is considered stale and cb_getassetstatus is called again. |
functioncache | boolean | false | Enables caching of compiled/dumped Lua callback functions, avoiding repeated script loading and compilation for callback invocations. |
faviconuri | string | Empty | Explicit favicon/image URI for the provider. If omitted, ImageLink builds a fallback favicon request from url. |
supportspaging | boolean | true | Controls whether page navigation and page-count widgets are shown in the asset browser. |
minimumbuildno | integer | No check when omitted | The current implementation rejects the provider when this value is less than the running ImageLink build number. This is the reverse of conventional “minimum version†behaviour, so omit this option unless that exact behaviour is required. |
3. Store settings and session data
A provider can persist data in the ImageLink preferences using PROVIDER.setdata. The value is serialised and can be retrieved later using PROVIDER.getdata. Typical uses include a server location, username and other provider preferences.
This data persists between InDesign sessions. Do not assume it is encrypted: avoid storing passwords or long-lived secrets unless the security characteristics of the local preferences storage are acceptable for your provider.
1 2 3 4 5 6 | local settings = { username = "user@example.com", server = "https://dam.example.com" } -- Persistent: stored in the user's ImageLink preferences. PROVIDER.setdata(settings) |
1 2 3 4 5 6 7 8 | local settings = PROVIDER.getdata() if settings == nil or settings.server == nil then error("No stored provider settings") end local server = settings.server local username = settings.username |
Session Data
Session data is transient data associated with the provider’s current connection. It is empty at startup and is cleared when the provider logs out or its connection is reset. Store it using PROVIDER.setsessiondata and retrieve it using PROVIDER.getsessiondata. Access tokens and session cookies are typical examples.
Global Variables
Each callback runs in its own Lua state, so global variables cannot be used to share data between callbacks. Use PROVIDER.setdata for persistent data and PROVIDER.setsessiondata for connection-session data. Within a callback, prefer local variables.
Multi-Threading
Some callbacks run on worker threads and must be thread-safe. In particular, many asset-status checks run this way. Do not show dialogs or perform other UI-dependent work from worker-thread callbacks. Restrict those callbacks to the documented ImageLink APIs and thread-safe Lua code.
4. Authentication and connection lifecycle
First decide whether the user needs an explicit Login command. Set login = true for the normal login workflow, or see authentication without a Login command for an API key or other silent authentication.
For providers that use ImageLink’s explicit Login command, there are three implementation points in the provider script.
Enable login in the provider configuration
1 2 3 4 5 6 7 8 | function cb_getconfiguration() return { name = "Example DAM", scheme = "example", version = "1.0.0", login = true } end |
Implement cb_login
It is the responsibility of this callback to read any saved credentials, show the log-in/authentication dialog (if required) and tell ImageLink it may attempt a connection.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | function cb_login() local saved = PROVIDER.getdata() or {} local username, password = show_login_dialog( saved.username or "", saved.password or "" ) -- User cancelled. if username == nil or password == nil then PROVIDER.setcanconnect(false) return end -- Persist only non-secret preferences. PROVIDER.setdata({ username = username }) -- Make the password available to cb_connect without persisting it. PROVIDER.setsessiondata({ password = password }) -- Required: ImageLink checks this after cb_login returns. PROVIDER.setcanconnect(true) end |
ImageLink does not provide a default login dialog, so the provider must implement it in Lua.
Implement cb_connect
After cb_login returns with PROVIDER.setcanconnect(true), ImageLink calls cb_connect to authenticate with the server. cb_connect may be called again later if the provider becomes disconnected.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 | function cb_connect() local credentials = PROVIDER.getdata() local pending = PROVIDER.getsessiondata() if credentials == nil or credentials.username == nil or pending == nil or pending.password == nil then PROVIDER.setisconnected(false) return end local code, cookies, body = HTTP.post( "https://dam.example.com/login", "username=" .. HTTP.urlencode(credentials.username) .. "&password=" .. HTTP.urlencode(pending.password) ) if code ~= 200 then PROVIDER.setisconnected(false) error("Login failed; server returned HTTP " .. tostring(code)) end local response = cjson.decode(body) if response == nil or response.access_token == nil then PROVIDER.setisconnected(false) error("Login response did not contain an access token") end PROVIDER.setsessiondata({ access_token = response.access_token, authorization = "Bearer " .. response.access_token }) -- Required: ImageLink checks this after cb_connect returns. PROVIDER.setisconnected(true) end |
Other callbacks can then access the transient authentication data via the PROVIDER.getsessiondata call.
Optional: implement cb_logout
An optional logout callback can be provided if, for example, you want to revoke a token.
1 2 3 4 5 6 7 8 9 10 | function cb_logout() local session = PROVIDER.getsessiondata() if session ~= nil and session.access_token ~= nil then -- Send a token-revocation request if the API supports it. end -- ImageLink automatically clears session data and connection state -- after this callback returns. end |
Authentication without an ImageLink Login command
If login = false, ImageLink treats the provider as usable without an explicit login and does not run the normal cb_login/cb_connect sequence. A provider may still authenticate silently, for example with an API key, application token or operating-system credential. In that case, obtain or refresh the credential from an operational callback such as cb_getassets, cb_getassetstatus or cb_preparedownload, and keep transient tokens in session data.
Avoid displaying dialogs from callbacks that may run on worker threads.
The short login example uses a provider-specific show_login_dialog helper and an illustrative login endpoint. Implement those for your service; the Demo DAM example below shows a dialog built with DIALOG. It exchanges the transient password for a token. A production provider also needs a strategy for expired tokens or a fresh login when credentials are no longer available.
5. Browse folders and assets
After any required authentication, the provider supplies the contents of the ImageLink asset browser. Folder browsing is optional; asset retrieval is handled by cb_getassets.
Return folders with cb_getfolders
cb_getfolders(path) receives the current folder path and returns a table of folders. Each folder has a user-facing name and a non-empty path that your script can pass back to the service. Omit this callback when the service has no folder hierarchy.
1 2 3 4 5 6 7 8 9 10 11 | function cb_getfolders(path) -- Illustrative hierarchy; replace with your service's folder lookup. if path == "" then return { { name = "Photography", path = "/photography" }, { name = "Illustrations", path = "/illustrations" } } end return {} end |
Return assets with cb_getassets
cb_getassets(query_string, path, page) receives the search text, selected folder path and requested page. Use those values in your service’s search request. Return two values in this order: the total number of pages, then a table of ASSET objects.
1 2 3 4 5 6 7 8 9 10 11 | -- Convert one result from your service into an ImageLink asset: local asset = ASSET.new( "Photo.jpg", -- display name "example://images.example.com/photo.jpg", -- original URI "https://images.example.com/photo-preview.jpg", -- preview URI "https://images.example.com/photo-thumb.jpg", -- thumbnail URI { id = "photo-123", caption = "Example photo" } -- provider metadata ) -- Inside cb_getassets, return page count followed by the asset list: return 1, { asset } |
The URLs above are placeholders. The Pexels and Demo DAM examples show how to build assets from JSON responses. Always return both values, including when the asset list is empty.
Paging and asset information
For a paged API, use the requested page and calculate the total page count from the service response. With a fixed page size, this is commonly math.ceil(total_results / page_size). Set supportspaging = false when your implementation supplies one unpaged result list.
Store useful per-asset information in the metadata argument to ASSET.new. If you implement cb_renderassetinfo(asset, renderer), retrieve it with asset:getmetadata() to draw information below the preview. The headersize configuration property controls the space reserved for that information.
6. Placement, downloads and FPO
Prepare the actual download
Before an image is downloaded, the cb_preparedownload callback LUA function is called. Â It is the responsibility of this function to return any headers that the server/endpoint may require, and correct the URI so that it is accessible. Â For example, if your scheme is ‘mydam’, and the URIs you’ve provided to ImageLink are in the form ‘mydam://images.myserver.com/images/1234.jpg’, this callback needs to correct the scheme to form an accessible URI (e.g. ‘https://images.myserver.com/images/1234.jpg’).
1 2 3 4 5 6 7 8 9 | function cb_preparedownload(uri) local headers = {} uri:setcomponent("scheme", "https") headers["method"] = "post"; headers["Content-Type"] = "application/octet-stream" return uri, headers end |
By default, ImageLink downloads images with a GET request. A table entry named method can select another method, such as post or put. This is an ImageLink control value and is consumed by the plug-in rather than sent to the server as an HTTP header.
Optional: support FPO renditions
An FPO (For Placement Only) rendition is a lower-resolution image used during layout. The original provides the high-resolution image for output. To support both, add fpo = true to your provider’s configuration.
Implement cb_getasseturi(uri, type) to return the URI for the requested rendition. ImageLink uses it during placement and rendition changes. If it is absent, the input URI is left unchanged.
The following example uses .original and .preview suffixes to distinguish renditions. Your provider must translate those identifiers into the service’s actual download URLs in cb_preparedownload.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | function cb_getasseturi(uri, type) local uri_str = uri:get() -- Strip any existing rendition suffix uri_str = uri_str:gsub("%.original$", "") uri_str = uri_str:gsub("%.preview$", "") -- Decide what to append local suffix = ".original" if type ~= "original" then suffix = ".preview" end return URI.new(uri_str .. suffix) end |
7. Keep link status up to date
The status of an image is used to update the Links panel, indicating whether the image is still available on the server and whether it has changed since placement. The provider returns this information from cb_getassetstatus.
The InDesign link subsystem calls this callback when it needs status information, including during initial link processing and periodic refreshes while a document is open. A simple implementation that reads HTTP headers is:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | function cb_getassetstatus(uri_list) local return_list = {} -- Preserve the input order: each result describes the URI at the -- corresponding position in uri_list. for _, uri in ipairs(uri_list) do local asset_data = {} local size, modified = HTTP.getheader(uri:get()) if size == nil then asset_data.status = "inaccessible" else asset_data.status = "available" asset_data.size = size asset_data.modified = modified end table.insert(return_list, asset_data) end return return_list end |
ImageLink may batch the status requests, so this function is passed a table of URIs. Â The function must return a table of tables containing the same number of entries as input URIs, and as a minimum each entry should have a ‘status’ entry.
Each entry may contain:
| Field | Description |
| size | The size, in bytes, of the file |
| status | One of:
|
| name | The name of the image that will be displayed in the Links panel. |
| modified | The last modification date/time of the image |
| version | This can be any string that identifies the version of an image, and could be number or hash. |
If version is returned from this callback, ImageLink uses it to determine whether the image should be shown as modified in the Links panel. If the returned value differs from the version recorded when the image was placed or last updated, the link is shown as needing an update. If version is omitted, ImageLink uses the size and modified fields instead.
The HTTP-header example assumes the URI is already accessible over HTTP or HTTPS without additional credentials. For a custom provider scheme or an authenticated service, resolve the URI and supply the appropriate authentication in the status implementation, or use the service’s metadata API. See the Demo DAM example for an API-based status lookup.
8. Optional integrations
Drag and drop from another application
When an image is dragged from an external source, such as a browser, and dropped onto an InDesign layout, ImageLink extracts the image source when possible and calls cb_convertexternallink on the installed providers. A provider that recognises the source returns a numeric confidence value and the URI that ImageLink should place. ImageLink selects the provider with the highest confidence; if providers tie for the highest confidence, the user is asked which one to use. An error from this callback means that the provider is not considered for that external URI.
Connect and place assets from an InDesign script
External scripts can be used to connect and place images. The URI scheme should match that of a provider. E.g:
1 2 3 4 5 6 7 8 9 10 | var str = '{"user":"xxx","password":"yyy"}'; app.httpLinkConnectionManager.httpConnect("elvis://hub.sdam.io", str); alert(app.httpLinkConnectionManager.isConnected("elvis://hub.sdam.io")); app.linkingPreferences.httpLinksRenditionType = LinkResourceRenditionType.FPO; var rectframe = app.activeDocument.rectangles.add(); rectframe.geometricBounds = [10,10,30,30]; var file1 = "elvis://hub.sdam.io/file/1FfYBsucaXuBQqdXr9Ypgb/*/oNSvTtnNXEc.jpg?_=2" ; rectframe.place(file1); if(app.activeDocument.links[0].renditionData == LinkResourceRenditionType.FPO) app.activeDocument.links[0].replaceWithOriginal(); |
cb_scripthttpconnect is called in response to app.httpLinkConnectionManager.httpConnect.
This InDesign scripting example targets an installed provider with the elvis scheme. Adapt the scheme, credentials and asset URI to your provider; it is separate from the bitdam example below.
9. Development and debugging
Parse JSON responses
Lua CJSON is built into the plug-in. It provides fast, standards-compliant JSON encoding and decoding with UTF-8 support, including decoding surrogate pairs. It is available through the global cjson object.
Load shared Lua modules
The preferences folder contains a require folder where external modules can be placed for use by the provider.
Reload scripts and inspect logs
To aid debugging, the preferences contain a debug option. This reloads the script every time the provider menu option is selected and logs most operations to the logs folder in the preferences folder. Turn this option off during normal operation because it affects 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
10. Complete examples
Example ImageLink providers can be downloaded via ImageLink, via the Preferences dialog. Once a provider has been installed, its source code can be found in the ‘providers’ folder inside of ImageLink’s preferences folder.
Back to the start of the guide