Analyzer Event Registration

Event Registration

Event registration occurs before Analyzer is initialized. Events are registered using the Analyzer API, which has to be required using RequireJS. When triggered, event listeners will execute in the order in which they were registered.

All registered event listeners receive at least three function parameters: e (the event object), and api or cv (global analyzer namespace).

Example:

require(["analyzer/cv_api"], function(api) {
  api.event.registerInitListener(function(e, cv){
	// Perform Action
  });
} 

Stop Immediate Propagation

There may be a time when, under special circumstances, a prior event listener will not want any further listeners to be executed. This can be performed by stopping the immediate propagation on the event chain. The function is attached to the event object (e), which is passed into the listeners.

Example:

api.event.registerInitListener(function(e, cv) {
  // Perform Action 1
  e.stopImmediatePropagation();
});
 
api.event.registerInitListener(function(e, cv) {
  // Perform Action 2
});

In the above code sample, even though two event listeners have been registered, since the first listener stopped the immediate propagation, the 2nd (and any subsequent) event listener will not be fired.

Prevent Default

All events have a default behavior associated with them and, in some cases, this behavior can be completely prevented. As with stopImmediatePropagation, this is also attached the to the event object (e) and needs to be called within the listener's code block.

Example:

api.event.registerInitListener(function(e, cv) {
  // Perform Action
  e.preventDefault();
}); 

Removing Listeners

It is possible to remove listeners once they have been registered.  A register event listener function returns a handler for that event listener which has a remove function attached to it. Calling this function removes the listener from the event chain.

Example:

var initListenerHandler = api.event.registerInitListener(function(e, cv) {
  // Perform Action
  e.preventDefault();
});
 
initListenerHandler.remove();

Attaching Event Listener Code

To insert your own custom javascript file, you must modify plugin.xml inside of your plugin folder. Currently, there is a commented line which is pointed at an example file inside of the analyzer's plugin script folder. If you would like to see this file working, uncomment that line by deleting the <!-- and --> surrounding the <file> tag. You must restart your server to see these changes.

Example:

<!-- <file context="analyzer">content/analyzer/scripts/api_examples/EventRegistration.js</file> -->

Events

The following are events in Analyzer.

init

The init event occurs after Analyzer's UI has initialized and the report definition (if opening a saved report) has been loaded into the editor.  Once all init handlers have been called, the report will automatically refresh its data so you do not need to call refreshReport in the init handler.

Example:

cv.api.event.registerInitListener(function(e, cv) {
  // Perform Action
  // e.stopImmediatePropagation();
});

onTableClick

The onTableClick event works only for the pivot table view. The event occurs after a user clicks on a table cell.  The registered onTableClick handlers are executed first, followed by the default on click event handlers. This event supports the stopImmediatePropagation and preventDefault functions.

Example:

cv.api.event.registerTableClickListener(function(e, api, td, ctx, filterCtx) {
  // Perform action
  // e.preventDefault();
  // e.stopImmediatePropagation();
});

This method signature contains a td parameter.  This parameter contains the <td> dom element that was clicked by the user.

onTableContextMenu

The onTableContextMenu event works only for the pivot table view. The event occurs after a user opens the context menu on a table cell, via the right-click menu.  The registered onTableContextMenu handlers are executed first, followed by the default on click event handlers. This event supports the stopImmediatePropagation and preventDefault functions.

Example:

cv.api.event.registerTableContextMenuListener(function(e, api, td, ctx, filterCtx) {
  // Perform action
  // e.preventDefault();
  // e.stopImmediatePropagation();
});

This method signature contains a td parameter.  This parameter contains the <td> dom element that was clicked by the user.

render

The render event occurs after the UI has finished drawing the visualization.  This event happens after the init event is completed.  This event can be used to highlight cells or change the styling of visualization elements. This event type supports stopImmediatePropagation, but does not support preventDefault.

Example:

cv.api.event.registerRenderListener(function(e, api, reportArea) {
  // Perform action
  // e.stopImmediatePropagation();
});

This method signature contains a div parameter.  This parameter contains the <div> dom element which contains the pivot table or visualization's view.

actionEvent

There are multiple action events which are triggered either through UI controls (by the user) or through API calls. Depending on the action, a specific actionCode is passed into the bound listener (Action Codes). Additionally, an actionCtx (action context) is provided to indicate upon which object(s) the action is being performed. This event type supports both preventDefault and stopImmediatePropagation.

Example:

cv.api.event.registerActionEventListener(function(e, api, actionCode, actionCtx) {
  //Perform Action
  e.preventDefault();
  e.stopImmediatePropagation();
});

buildMenu

The buildMenu event is fired when Analyzer attempts to build a menu within the application. Normally, these menus are built when right-clicking on a table cell or a gem. Also, you may want to hook into this event to override the default behavior and prevent the menu from building such that you can replace the default menu with one of your own.

Example:

cv.api.event.registerBuildMenuListener(function(e, api, menuId, menu, x, y){
  //Perform Action on api.*
  e.preventDefault();
  e.stopImmediatePropagation();
});

chartSelectItems

This event is fired when a user selects a chart data point or lassos a collection of data points within an Analyzer Visualization. This can be useful to perform an additional action when a user selects an item in a chart.

Example:

cv.api.event.registerChartSelectItemsListener(function(e, api, ctx[]){
  //Perform Action on api.*
  e.stopImmediatePropagation();
});

chartDoubleClick

This event is fired when the user double-clicks on a chart item. Normally, this would perform a drill-down action, providing a filtered result set.

Example:

cv.api.event.registerChartDoubleClickListener(function(e, api, ctx){
  //Perform Action on api.*
  e.preventDefault();
  e.stopImmediatePropagation();
});

dragEvent

Drag events are fired when beginning to drag any draggable item within Analyzer.

 Example:

 cv.api.event.registerDragEventListener(function(e, api, formula){
  //Perform Action on api.*
  e.stopImmediatePropagation();
});

dropEvent

Drop events are fired when a draggable element has been dropped onto a drop target within the layout panel, report area, trash can, or filter panel. This event is also fired when completing a drop programmatically using cv.api.operation.completeDrop after retrieving a valid drop target from cv.api.operation.getDropTarget.

Example:

 cv.api.event.registerDropEventListener(function(e, api, formula, dropClass){
  //Perform Action on api.*
  e.stopImmediatePropagation();
});

tableDoubleClick

This event occurs when double-clicking on a cell within Analyzer's PIVOT table.

Example:

 cv.api.event.registerTableDoubleClickListener(function(e, api, td, ctx, filterCtx){
  //Perform Action on api.*
  e.preventDefault();
  e.stopImmediatePropagation();
});

tableMouseMove

This event is fired when moving the mouse over a cell within Analyzer's PIVOT table. The listener is executed many times within a small mouse movement. Most often, the (x, y) coordinates of the mouse are recorded using this event.

Example:

 cv.api.event.registerTableMouseMoveListener(function(e, api, td, ctx, filterCtx){
  //Perform Action on api.*
  e.preventDefault();
  e.stopImmediatePropagation();
});

tableMouseOver

This event is fired when moving the mouse over a cell within Analyzer's PIVOT table. This event is only fired once when the mouse moves over a cell.

Example:

 cv.api.event.registerTableMouseOverListener(function(e, api, td, ctx, filterCtx){
  //Perform Action on api.*
  e.preventDefault();
  e.stopImmediatePropagation();
});