addAction

How to get addAction

import addAction from 'fontoxml-operations/src/addAction.js'

Type: Function

Register an action to the set of globally usable actions. Actions change application state, without mutating the DOM.

Examples of actions include saving the document, deleting references, etc.

The state of operations using an action are not automatically recomputed when data changes. While Fonto does automatically refresh some operation states in some cases, this behavior is subject to change. Therefore, we recommend not relying on this behavior to also recompute the state of custom actions. Instead, developers should make sure to call OperationsManager#invalidateOperationStatesByStepType whenever the result of the action's getState callback may have changed. For example, an action that uses the selection may invalidate corresponding operation states when the selection changes by subscribing to the selection change notifier. This is usually done in the same install.js that registers the action:

addAction(
    'sendCurrentParagraphToCms',
    async function sendParagraph(stepData) {
        await someManager.sendDataToCms(stepData.paragraph);
        return;
    }
);

// In this case the operation state will be invalidated every time the notifier is triggered.
selectionManager.selectionChangeNotifier.addCallback(() => {
    operationsManager.invalidateOperationStatesByStepType(
        'action',
        'sendCurrentParagraphToCms'
    );
});

Other examples of actions could be:

addAction(
    'toggleSomething',
    function toggle(stepData) {
        someManager.toggleFeature(stepData.feature);
        return;
    },
    function getState(stepData) {
        return {
            // In this case the action can always be executed.
            enabled: true,
            // The operation is considered as "applied" if the feature is already active.
            active: someManager.isFeatureActive(stepData.feature)
        };
    }
);

addAction(
    'performSomething',
    function performSomething(stepData) {
        someManager.performSomething();
        return;
    },
    function getState(_stepData) {
        // The state can also be returned as a promise.
        return Promise.resolve({
             enabled: someManager.getSomeValue() !== null,
             active: false
        });
    }
);

There is no need to add a notifier callback in order to invalidate the state of an action. You can trigger the invalidation manually wherever you think it is neccessary or whenever the state might have change. To do so you can use the same code that it is used above:

operationsManager.invalidateOperationStatesByStepType(
    'action',
    'toggleSomething'
);

Arguments

# Name Type Description
1. name String

The name of the action. Operations can invoke the action using a step of type "action/name".

2. run Function

Asynchronous callback function which defines the actual behavior of the action. Click on the type link to learn more.

Asynchronous callback function which defines the actual behavior of the action.

The callback receives the current operation StepData as the first and only argument. It should return nothing (undefined) or a addAction.CANCEL_OPERATION value to cancel the whole operation (under certain conditions). If your action is asynchronous, you can return a promise that eventually resolves into undefined or addAction.CANCEL_OPERATION.


  Arguments
# Name Type Description
1. stepData StepData
  Returns
3. [getState] Function

Optional asynchronous callback function which can be implemented to calculate the current state of operations using this action. Click on the type link to learn more.

Optional asynchronous callback function which can be implemented to calculate the current state of operations using this action. Useful if your action needs to manipulate the state of operations it is included in.

The callback receives the current operation StepData as the first and only argument. It should return the new OperationState. If determining the operation state is asynchronous, you can return a promise that eventually resolves into the new operation state.


  Arguments
# Name Type Description
1. stepData StepData
  Returns

Type: OperationState | Promise<OperationState>

Was this page helpful?