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 |