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 FunctionDescription
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 FunctionDescription
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 FunctionDescription
requestHTTP(method, url, headers, body)Performs an HTTP reqest

Data handling

Global FunctionDescription
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 FunctionDescription
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 FunctionDescription
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 FunctionDescription
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 FunctionDescription
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 PropertyTypeDescription
libraryLibraryCurrently loaded library
modulesObjectObject 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

MemberDescription
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.

MemberDescription
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.

MemberDescription
NotificationAction(caption, callback)Constructs a new NotificationAction