Actions - bitfocus/companion-module-base GitHub Wiki

Actions are the "commands" being executed when a user pushes a button.

This section explains how to provide the possible actions and their options to the user.

Your module can define the list of actions it supports by making a call to this.setActionDefinitions({ ...some actions here... }). You will need to do this as part of your init() method, but can also call it at any other time if you wish to update the list of actions exposed.

Note: Please try not to do it too often, as updating the list has a cost. If you are calling it multiple times in a short span of time, consider if it would be possible to batch the calls so it is only done once.

The boilerplate has a file actions.js which is where your actions should be defined. It is not required to use this structure, but it keeps it more readable than having it all in one file.

All the actions are passed in as one javascript object, like

{
  'action1' : { properties of action 1 },
  'action2' : { properties of action 2 },
  'action3' : { properties of action 3 }
}

The minimum you need to define for an actions is as follows:

{
    name: 'My first action',
    options: [],
    callback: (action) => {
        console.log('Hello World!')
    }
}

The callback function is called when the action is executed. Callback functions may either execute synchronously and return undefined, or asynchronously and return a promise that resolves undefined (including by directly returning in an async function).

Before Companion 3.5, when a series of actions was executed, each action's callback would be called in sequence, with no delay between actions (unless an action was defined with a relative or absolute delay) and no waiting for asynchronous callback functions' returned promises to resolve or reject. From Companion 3.5 onward, actions may be defined to run in sequence -- waiting for the promise returned by an asynchronous callback function to resolve before continuing. If you want your action to support delaying subsequent actions until completed, you must write your callback to not resolve the promise it returns until the action has completed. For example:

const actions = [
    // This action will begin to make a http request and subsequent sequential actions
    // will execute before the request is finished.
    {
        name: 'Fetch Google',
        options: [],
        callback: (action) => {
            fetch("https://google.com/").then(() => {
                console.log("request complete");
            }, () => {
                console.log("request failed");
            })
        }
    },
    // This action will begin to make a request and subsequent sequential actions
    // won't execute until the request is finished.
    {
        name: 'Fetch Google and wait',
        options: [],
        callback: async (action) => {
            return fetch("https://google.com/").then(() => {
                console.log("request complete");
            }, () => {
                console.log("request failed");
            })
        }
    },
]

There are more properties available, which are described in full in the documentation

The options property of the action definition is an array of input types, as defined here

As of @companion-module/base#v1.1.0, there is now a second parameter to each of callback, subscribe, unsubscribe and learn. This contains some utility methods that you may need. The full definition of this type is here.

Actions - bitfocus/companion-module-base GitHub Wiki

Further Reading