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:

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

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.

id()ID (ULID) of the node
runtimeID()Runtime ID of the node
fullLocalPathFor nodes with a URL, the path of the file/directory
urlFor nodes with a URL, the path of the file/directory
readURLFor 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.

NotificationAction(caption, callback)Constructs a new NotificationAction