Actions

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 function on callback is what gets executed when the action is executed. It used to be possible to define this elsewhere, but that is no longer the case. You can see a description of the action object passed into the callback in the documentation. Make sure to not use any of the deprecated properties, they will be removed without warning!

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.

Further Reading

Actions also support the following advanced features:

• subscribe & unsubscribe flow
• learn option values
• result to custom variable