actions

This module provides helpers for patterns regarding takeActionRequest, willTakeAction and

didTakeAction events.

Contents

Module Members

• OUTCOME_SUCCESS
• OUTCOME_ERROR
• publisherForFeature()
• publisher()
• connectPublisherToFeature()
• handlerFor()

Types

• ActionHandler
  • ActionHandler.registerActionsFromFeature()
  • ActionHandler.registerActions()

Module Members

OUTCOME_SUCCESS String

Constant for the value "SUCCESS" of a successful action request outcome.

OUTCOME_ERROR String

Constant for the value "ERROR" of an erronoues action request outcome.

publisherForFeature( context, feature, optionalOptions )

Creates and returns a function to publish takeActionRequest events for an action configured as feature. The action to publish is expected to be at the key action under the given feature path. So if the given feature path is click, the actual name of the action is expected to be found at context.features.click.action.

Apart from that this function works just like #publisher().

Parameters

Returns

publisher( context, action, optionalOptions )

Creates and return a function to publish takeActionRequest events for a given action. The outcomes of all given didTakeAction events are interpreted and optional callbacks according to the overall outcome are called. Interpretation is simple: If at least one didTakeAction event yields the outcome #OUTCOME_ERROR, the overall outcome is also erroneous. In any other case the overall outcome will be successful.

The promise returned by the publisher is resolved with an object carrying all responses and the outcome of the action. All on* handlers will only receive the list of responses to the action. A response is an object having the keys meta and event, being the meta and event objects of a didTakeAction event (see EventBus#publishAndGatherReplies() for details).

Example:

publisher = actions.publisher( context, 'save', {
   onSuccess: () => { closeApplication(); },
   onError: () => { displayError(); }
} );

$button.on( 'click', () => {
   publisher().then( result => {
      console.log( result ); // for example { responses: [ ... ], outcome: 'SUCCESS' }
   } );
} );

Parameters

Returns

connectPublisherToFeature( context, feature, optionalOptions )

Creates an action publisher for a given feature and makes it available as a context property.

The publisher is created under context[ `actions.${feature}` ], where context and feature are the arguments passed to this function. If an action topic has been configured for the given feature, the action publisher is created using publisherForFeature. Otherwise, it is a noop-function.

Parameters

handlerFor( context )

Creates a new action handler instance for takeActionRequest events. It handles sending of an optional

willTakeAction event and the following didTakeAction event, possibly following asynchronously later.

Parameters

Returns

Types

ActionHandler

ActionHandler.registerActionsFromFeature( feature, handler )

Registers a handler for takeActionRequest events with actions from a feature. It is assumed that the given feature has an onActions property, which is a set of actions to listen to. The set may be empty, null or undefined, in which case the handler simply won't be attached to any event.

Apart from that, this function works just like ActionHandler#registerActions.

Example: Consider the following configuration for a widget:

{
   "features": {
      "open": {
         "onActions": [ "openAction1", "openAction2" ]
      },
      "save": {
         "onActions": [ "save" ]
      }
   }
}

An example using that would be:

actions.handlerFor( context )
   .registerActionsFromFeature( 'open', ( event, meta ) => {
      somethingSynchronous();
      return actions.OUTCOME_SUCCESS;
   } )
   .registerActionsFromFeature( 'save', ( event, meta ) => {
      return Promise.resolve( somethingAsynchronous() );
   } );

Parameters

Returns

ActionHandler.registerActions( actions, handler )

Registers a handler for takeActionRequest events for a set of actions. The set may be empty, in which case the handler simply won't be attached to any event.

The handler is assumed to be a function that receives the event and meta object of the underlying

takeActionRequest event when called. In order to send the correct didTakeAction event as response, the return value of the handler is interpreted according to the following rules:

• the handler throws an error

  • the didTakeAction event is sent with outcome #OUTCOME_ERROR
  • the error is re-thrown

• the handler returns a simple value or a promise, that is later resolved with a value

  • if the value is a plain object, it is used as basis for the event object and
    • if the object has a property outcome with value #OUTCOME_ERROR, the didTakeAction event is sent with outcome #OUTCOME_ERROR
  • otherwise, or if the value is no plain object, the didTakeAction event is sent with outcome #OUTCOME_SUCCESS

• the handler returns a promise, that is later rejected with a value

  • if the value is a plain object, it is used as basis for the event object and
    • if the object has a property outcome with value #OUTCOME_SUCCESS, the didTakeAction event is sent with outcome #OUTCOME_SUCCESS
  • otherwise, or if the value is no plain object, the didTakeAction event is sent with outcome #OUTCOME_ERROR

So basically simple return values or resolved promises are assumed to be successful if they don't state otherwise, while rejected promises are assumed to be erroneous, if they don't state otherwise.

Example:

actions.handlerFor( context )
   .registerActions( [ 'open' ], ( event, meta ) => 42 )
   .registerActions( [ 'save' ], ( event, meta ) => Promise.resolve( { resultValue: 42 } ) );

Parameters

Returns