Developing Add-ons

Creating a minimal add-on

Each add-on has its own folder in which it can store any required resources and the required "addon.js" file. The folder should be named like the identifier used to access the add-on programmatically.

At the global scope of addon.js, the add-on should perform any basic setup that it needs. This includes a call to registerAddon, and registering any actions or events that it supports. A simple example could look like this:

// This call must be done before any other calls. The first argument must be a
// unique identifier of the add-on and should include the creator's name in some
// form. It must be a valid JavaScript identifier.
registerAddon("superplugins_example", {
	version: "1.0.0",
	title: "Example Addon",
	vendor: "Superplugins Inc.",
	description: "Adds a menu entry for displaying a message box."
})

registerAction("showMessageBox", function() {
	print("Now showing the message box...");
	alert("This is the message!", "Message Addon");
});

addMenuEntry("showMessageBox", "Show message box", "control+alt+M")

API Overview

In addition to the ECMA script v3 functionality, such as Array and Math, the following global Functionality is available:

Dialogs and Console

Global Function	Description
`alert(message[, title])`	Shows a an informational message box
`print(text)`	Prints a message to the log/console
`prompt(message[, default])`	Displays a message box with an input box
`chooseFile(options)`	Shows a file chooser dialog, returns the URL of the chosen file
`chooseDirectory(options)`	Shows a directory chooser dialog, returns the URL of the chosen directory

File operations

Global Function	Description
`existsFile(path)`	Tests whether a file exists at the given path/URL
`readFileUTF8(path)`	Reads a UTF-8 encoded text file
`writeFileUTF8(path, text)`	Writes a UTF-8 encoded text file to disk
`calculateStrongChecksum(path)`	Calculates the strong (SHA512/224) checksum of the given file
`calculateWeakChecksum(path)`	Calculates the weak checksum of the given file
`getTempPath()`	Returns the path to the temporary folder
`encodeInetPath(path)`	Encodes a normal OS path to an path using percent encoding
`compareFilenames(a, b)`	Performs a path comparison suitable for sorting
`getImageFileClass(path_or_url)`	Returns one of "raw", "jpeg", "tiff", "photoshop" or "other"

Network I/O

Global Function	Description
`requestHTTP(method, url, headers, body)`	Performs an HTTP reqest

Data handling

Global Function	Description
`toJSON(value)`	Converts an value to JSON format
`md5Of(data)`	Computes the MD5 hash of the given data
`sha1Of(data)`	Computes the SHA1 hash of the given data
`sha256Of(data)`	Computes the SHA-256 hash of the given data
`sha512Of(data)`	Computes the SHA-512 hash of the given data
`md5HMACOf(data, key)`	Computes the HMAC-MD5 of the given data (RFC2104)
`sha1HMACOf(data, key)`	Computes the HMAC-SHA1 of the given data (RFC2104)
`sha256HMACOf(data, key)`	Computes the HMAC-SHA-256 of the given data (RFC2104)
`sha512HMACOf(data, key)`	Computes the HMAC-SHA-512 of the given data (RFC2104)

Add-on registration and settings

Global Function	Description
`registerAddon(name, properties`)	Registers the add-on with the host application
`getSetting(name)`	Retrieves an add-on specific setting
`setSetting(name, value)`	Sets/stores an add-on specific setting
`addMenuEntry(action_name, caption, default_shortcut)`	Adds a main menu entry
`addContextMenuEntry(action_name, caption, default_shortcut)`	Adds a file context menu entry
`addContainerMenuEntry(action_name, caption, default_shortcut)`	Adds a container node context menu entry
`notifyUser(message, primary_action, secondary_action)`	Displays a notification in the notification center
`runActivity(caption, message, total_amount, callback)`	Executes an activity that is displayed in the notification center
`runIdleActivity(caption, message, total_amount, callback)`	Same as `runActivity`, but using idle priority
`registerAction(name, callback)`	Registers a new global action
`invoke(action_name)`	Invokes an action given by its qualified name
`registerContextAction(name, callback, visible_callback)`	Registers a new (file) selection specific action
`registerContainerAction(name, callback, visible_callback)`	Registers a new container/view specific action
`registerEvent(name)`	Registers a new module/add-on specific event
`connectToEvent(event_name, callback)`	Connects a callback to an event given by its qualified name
`emit(event_name, value)`	Emits a previously registered event, passing the given value

Current view items

Global Function	Description
`getFocusIndex()`	Returns the current focus index
`setFocusIndex(index)`	Sets the focus index
`getSelection()`	Returns the currently selected item indices
`setSelection(indices)`	Sets the indices of the current selection
`getItems()`	Gets the list of all items in the current page (class `FileNode`)

Library utilities

Global Function	Description
`getRelatedFiles(file_node)`	Returns all related files (RAW+JPEG, edits, sidecar files, edit source files)
`getMaterializations(file_node)`	Returns all materializations (RAW+JPEG pairs)

Misc.

Global Function	Description
`sleep(seconds)`	Sleeps for the specified amount of seconds
`execute(arguments)`	Executes a process with the given argument array (first argument is the binary) and returns the process exit code

Global Property	Type	Description
`library`	`Library`	Currently loaded library
`modules`	`Object`	Object containing all available modules

Note that the modules object, as well as all sub objects includes a help() method that lists all available members.

Library class

Member	Description
`createEvent(caption)`	Creates a new event and returns the corresponding node
`createTextFile(target, sub_path, contentx)`	Creates a new `File` node in the given target event/shoe box folder
`createRawNode(type, data)`	Creates and returns a new node - use with care
`moveFilesToLibraryTrash(files)`	Moves the given files into the library trash
`modifyFileMetadata(file_node, xmp)`	Adds/replaces the metadata fields of a file node given in the supplied XMP metadata
`rootNode()`	Returns the root node of the library
`lookupNode(id)`	Looks up a node by its ID (ULID)
`getNode(runtime_id)`	Looks up a node by its runtime ID
`getStrongFiles(strong_checksum)`	Returns all files with the given strong (SHA512/224) checksum
`getWeakFiles(weak_checksum)`	Returns all files with the given weak checksum
`importFilesPlain(files[, target])`	Imports a set of files into the given target event/shoe box folder
`help()`	Lists all available members

Node class

There are many different node classes. Each class has specific members that can be listed with the help() method.

Member	Description
`id()`	ID (ULID) of the node
`type()`	Type name of the node (e.g. "Event" or "Collection")
`owner()`	The owner node of this node
`runtimeID()`	Runtime ID of the node
`fullLocalPath()`	For nodes with a URL, the path of the file/directory
`url()`	For nodes with a URL, the path of the file/directory
`readURL()`	For file nodes, the path to use for reading the file
`help()`	Lists all available members

Note that during import, the file may still be at a different location than its nominal URL. In this case, readURL will return the path of the source file.

NotificationAction class

Passed as an argument to notifyUser.

Member	Description
`NotificationAction(caption, callback)`	Constructs a new `NotificationAction`