Action Model

ActionModel is responsible for registering physical, behavioural actions, side effects and the mapping between them.

Getting Started

To get access to ActionModel:

const ActionModel = muze.ActionModel;

ActionModel.registerPhysicalBehaviouralMap({..});

Methods

for

Syntax: for(...canvases)

Takes an array of canvas instances on which further actions will be performed like registering actions, side effects or enabling interactivity between them.

Parameters:

Property	Type	Required	Default	Description
canvases	Canvas	true	-	Instance of canvas on which actions will be performed

Usage:

const ActionModel = muze.ActionModel;

// for method attaches the canvases in action model where registration of actions
// and side effects will be done.
ActionModel.for(canvases)
  .registerSideEffects(...sideEffects);

Returns: ActionModel

enableCrossInteractivity

Syntax: enableCrossInteractivity(crossInteractionConfig?: object)

By default cross interactivity is disabled between multiple canvases. This method enables cross interaction between the canvases so that any action happening in one canvas gets dispatched on other canvases as well. An optional object can also be passed which is used to configure the cross interactions between canvases

CrossInteractionConfig:

Property	Type	Description
<SOURCE_CANVAS>	Object	Configures interactions on a list of target canvases when some action happens on <SOURCE_CANVAS>. Here <SOURCE_CANVAS> is the alias of the canvas. It can be retrieved by calling canvas.alias() function.

Returns:

• GenericSideEffect
• SpawnableSideEffect

Any side effect which will add any new element to the chart like drawing a rectangular box or add any new layer over the chart needs to inherit this class.

drawingContext

Syntax: drawingContext()

This methods returns the containers and other properties like width and height of the container for drawing any elements on the chart.

Returns: object

{
  svgContainer, // Svg container of the visual unit component.
  width, // Width of the container in pixels.
  height, // Height of the container in pixels.
  sideEffectGroup, // Svg group for adding any side effect dom elements.
}

SurrogateSideEffect

This abstract class needs to be extended for modifying the styles of elements in the visualization.

Returns: SurrogateSideEffect

dissociateBehaviour

Syntax: dissociateBehaviour(...maps)

Breaks the link between behavioural actions and physical actions. It takes an array of behavioural action and it's physical action.

Parameters:

Property	Type	Required	Default	Description
maps	Array	true	-	An array of behaviour name and physical action name.

Returns: ActionModel

registerPhysicalBehaviouralMap

Syntax: registerPhysicalBehaviouralMap(map)

Registers the mapping of physical and behavioural actions. This mapping is used to establish which behavioural actions should be dispatched on trigger of any physical actions.

Parameters:

Property	Type	Required	Default	Description
map	object	true	-	An object having keys as name of the physical action and value as an object which specifies the name of the behaviours.

Returns: ActionModel

registerPhysicalActions

Syntax: registerPhysicalActions(physicalAction)

Registers physical actions on the canvases. It takes an object with key as the name of action and value having the definition of the action.

Parameters:

Property	Type	Required	Default	Description
physicalAction	Object	true	-	Names of physical actions and their definitions.
<ACTION_NAME>	*PhysicalAction	-	-	Function which attaches some event listeners on the target dom element.

*PhysicalAction

Returns a function which attaches event listeners on dom elements and triggers a physical action with a payload and name of the physical action.

Type: Function

Returns: *PhysicalActionFn

*PhysicalActionFn

Returns: GenericBehaviour

VolatileBehaviour

extends GenericBehaviour

This behavioural action is a generic class for behavioural actions which are volatile. That means any action which does not need to keep the previous identifiers in the selection set. For example, highlight behaviour is a volatile behaviour because on every mouse interaction only the identifiers interacted with are kept in entry set and rest of the identifiers are in exit set. It does not persist the identifiers which were interacted previously. It implements the setSelectionSet method to achieve this.

PersistentBehaviour

extends GenericBehaviour

This behavioural action is a generic class for behavioural actions which are peristent. That means any action which needs to keep the previous identifiers in the selection set. For example, select behaviour is persistent behaviour because on every click the previous identifiers interacted with are kept in the entry set.

createElement

Syntax: createElement(container, elemType, data, className)

Creates dom elements of the specified element type in the specified container element.

Parameters:

Property	Type	Required	Default	Description
container	HTMLElement | SVGElement	true	-	Dom element where the new element will be created.
elemType	string	true	-	Type of the element (tag name) which will be created.
data	Array	true	-	Array of data points which will be bound to the elements. For every element in the array a new dom element will be created and each element will be bound to the new dom element.
className	string	false	-	Class name which will be set on the elements.

Returns: D3 Selection.

registerSideEffects

Syntax: registerSideEffects(...sideEffects)

Registers the side effects on the registered canvases. It takes definitions of side effects and registers them on the canvases.

Parameters:

Property	Type	Required	Default	Description
sideEffects	GenericSideEffect	true	-	Side effect class

Returns: Action model.

GenericSideEffect

This is the base class of all side effects. It contains all common methods like setting configuration, disabling, enabling side effect, etc. Every new side effect has to inherit this class or SpawnableSideEffect or SurrogateSideEffect class. All side effects are initialized by firebolt. The instance of firebolt is passed on initialization.

static formalName

Syntax: formalName()

Returns the unique name of the side effect which will be used in behaviour-effect map for mapping the side effect with a behavioural action.

Returns: string: Unique name of the side effect.

Usage:

const canvas = env.canvas();

class ColorChanger extends SurrogateSideEffect {
  static formalName () {
    return 'colorChanger';
  }
}

muze.ActionModel.for(canvas).mapSideEffects({
  select: ['colorChanger'] // Formal name of the side effect should be passed
  // in behaviour effect map.
});

static target

Syntax: target()

Returns the target area of the side effect. Defaults to all. Target area can be visual-unit or visual-group or all. If target area is visual-unit, then the side effect will be applied for each units. For example, if you want to add a layer, then the target must be visual-unit. If the target area is visual-group, then a common side effect will be created for all the units.

Returns: string: Name of the target area.

apply

This method is responsible for changing the visualization or adding any new element like layers in the visualisation. This method must be implemented by any side effect classes which needs to show any effect in the visualization.

Syntax: apply(entryExitSet, payload, options)

Parameters:

Property	Type	Required	Default	Description
entryExitSet	EntryExitSet	true	-	Entry exit set attached with the behavioural action mapped with the side effect.
payload	object	true	-	Payload object of the behaviour mapped with the side effect.
options	object	false	undefined	Options which are set in the behaviour-effect map.

Usage:

ActionModel.registerPhysicalBehaviouralMap({
  ctrlClick: {
    behaviours: ['select']
    touch: false // An optional attribute which tells if it is needed to be registered
    // on touch devices or not. By default it is true.
  }
});

Example:

In the above example, we bind ctrlClick physical action with select behaviour and dissociate select behaviour from click action so that only when we ctrl/cmd+click on the element then the select behaviour gets dispatched.

registerBehaviouralActions

Syntax: registerBehaviouralActions(...actions)

Registers behavioural actions on the canvases. It takes definitions of the behavioural actions and registers them on the canvases. Every behavioural action must inherit the GenericBehaviour or VolatileBehaviour or PersistentBehaviour class.

Parameters:

Property	Type	Required	Default	Description
actions	GenericBehaviour	true	-	Behaviour class definition.

Returns: ActionModel

GenericBehaviour

This is an abstract class which takes payload and creates the entry and exit set. Any new behaviour class should inherit this class or VolatileBehaviour or PersistentBehaviour class.

setSelectionSet

Syntax: setSelectionSet(uids, selectionSet)

Adds or removes identifiers in the SelectionSet instance. This is called internally by the behaviour class.

Parameters:

Property	Type	Required	Default	Description
uids	Array	true	-	Array of row identifiers which are interacted with.
selectionSet	SelectionSet	true	-	Instance of selection set.