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:

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
`readFileAsUTF8(path)`	Reads a UTF-8 encoded text file
`writeFileAsUTF8(path, text)`	Writes a UTF-8 encoded text file to disk
`requestHTTP(method, url, headers, body)`	Performs an HTTP reqest
`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)
`sleep(seconds)`	Sleeps for the specified amount of seconds
`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
`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`)
`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
`readTextFile(path)`	Reads a UTF-8 encoded file and returns it as a sting
`writeTextFile(path, text)`	Writes a UTF-8 encoded file to disk
`readBinaryFile(path)`	Reads a binary file and returns it as a byte array
`writeBinaryFile(path, bytes)`	Writes a binary file to disk
`getTempPath()`	Returns the path to the temporary folder
`execute(arguments)`	Executes a process with the given argument array (first argument is the binary) and returns the process exit code

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
`createNode(type, data)`	Creates and returns a new node
`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
`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
`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`