Version 2020

Enable Custom Selection and Highlighting

Users of the Custom Visualization SDK can achieve some highlight effects by using the 3rd party plotting libraries like D3.js. The Custom Selection and Highlight API enables the selection status of the graphics to persist when reopening a saved dossier as well as when the custom visualization is used as the selector or target of filtering another visualization.

Implement the sections below in the following order to enable this feature:

  1. Create Graphic Models

  2. Bind Graphic Models to Graphics

  3. Enable Selection

  4. Enable Highlight

Create Graphic Models

To enable selection, build the graphic models and bind them to the graphic.

API Name

createGraphicModels: API to create model data for each graphics displayed on the visualization.

Parameters

N/A

Implementation

  1. Call functions in class DataInterface to get model data of the visualization.

  2. Create a set to hold graphic models. This can be defined as a tree/array or any structure you want.

  3. Create a graphic model for each graphic to be displayed on the visualization and add it to the set defined in step 2, then return the set.

    The definition of inner structures of the set of graphic models is left up to the SDK user. They can retrieved by calling the getGraphicModels@customVisBase function.

Example

createGraphicModels: function createGraphicModels() {
                var me = this,
					//A set to hold graphic models which you can define as a tree/array or any structure you want.
                    graphicModels = { children: [] };

                var rawData = this.dataInterface.getRawData(mstrmojo.models.template.DataInterface.ENUM_RAW_DATA_FORMAT.ROWS_ADV, {
                    hasSelection: true,
                    hasTitleName: true
                });

                $ARR.forEach(rawData, function (row) {
                    var headers = row.headers,
                        values = row.values,
                        value = values[0],
						//New a graphic model.
						graphicModel = new GraphicModel();

            		//Set properties to the graphic model.
 					graphicModel.setCustomProperties({
                        packageName: headers[0].name,
                        className: headers[1].name,
                        value: value.rv,
                        formattedValue: value.v
                    });
						
					// Set the selector of the graphic
                    graphicModel.setSelector(row.metricSelector, false);
                 	// Add the graphic model to the a set which you defined on your own.
                    graphicModels.children.push(graphicModel);
    
                });
				// Return the set of graphic models you defined
                return graphicModels;
            },

Bind Graphic Models to Graphics

API Name

getGraphicModels: Call this function to retrieve the set of graphic models created in the createGraphicModels API.

Parameters

N/A

Usage

It is recommended to call this function within the plot()function.

  1. Retrieve the set of graphic models.

  2. Iterate through each graphic model in the set and bind it to the corresponding graphic.

    The method of binding a graphic model to a graphic is defined by the SDK user or by the 3rd-party plotting libraries if any are used.

Example

		plot: function () {           
				// Sample code of initializing bubbles using the D3.js plotting library.   
				//...
				var svg = d3.select(this.domNode).select("svg");
                if (svg.empty()) {
                    svg = d3.select(this.domNode).append("svg")
                        .attr("class", "bubble");
                }
                svg.attr("width", width)
                    .attr("height", height)
                    .on('click', function () {
                        handleClickOnEmpty(viz);
                    });
                var g = svg.select("g");
                if (g.empty()) {
                    g = svg.append("g");
                }
                g.attr("transform", "translate(" + (width - diameter) / 2 + "," + (height - diameter) / 2 + ")");

				// Get the graphic models. 
				var graphicModels = this.getGraphicModels(); 
				//Bind the graphic models to the graphic.
                var node = g.selectAll(".node")
                    .data(bubble.nodes(data)
                        .filter(function (d) {
                            return !d.children;
                        }));
				//...
		}

Enable Selection

To enable selection two APIs need to be called - handleSelection() and handleContextMenuSelection() to notify our framework of a selection or context menu selection change.

API Name

handleSelection: Call this function to notify the framework of a click on a graphic and let the framework handle the selection change.

Parameters

graphicModel: The graphic model bound to the graphic.

isMultiSelectMode: If the user is making multiple selections set to true. Otherwise, set to false.

Usage

  1. Listen to the mouse-click (desktop) or tap (mobile device) on a graphic.

  2. Get the graphic model which is bound to this graphic as the first parameter.

  3. Check the key status to see if the Ctrl key (Command on Mac) is down to indicate multi-selection.

    • If down, set isMultiSelectMode to true
    • If else, set isMultiSelectMode to false.
  4. Pass the result in step 2 and step 3 as the parameter to call the function.

Example

onclick: function onclick(evt) {
	if (evt.e) {
		evt = evt.e;
	}

	var srcNode = evt.srcElement,
		//Get graphic model bind to the graphic.
		graphicModel = d3.select(srcNode).datum(),
		isMultiSelectMode = evt.ctrlKey || evt.metaKey;

	this.handleSelection(graphicModel, isMultiSelectMode);
},

API Name

handleContextMenuSelection: Call this function to notify the framework of right-click on a graphic and let the framework handle the context menu selection change.

Parameters

graphicModel: The graphic model bound to the graphic.

Usage

  1. Listen to the right-mouse-click (desktop) or long tap (mobile device) on a graphic.
  2. Get the graphic model which is bound to this graphic as the parameter.
  3. Pass the parameter to call the function.

Example

oncontextmenu: function oncontextmenu(evt) {
	if (evt.e) {
		evt = evt.e;
	}

	var srcNode = evt.srcElement,
		//Get graphic model bind to the graphic.
		graphicModel  = d3.select(srcNode).datum();

	this.handleContextMenuSelection(graphicModel);
},

Enable Highlight

Two APIs need to be implemented to enable highlights - one for the selected graphics and one to define the your highlight style.

API Name

getGraphicModelsBySelector: API to pick out the graphic models by the given selector.

Parameters

selector: The selector to select graphics models.

isAttrSelector: Whether the selector is an attribute selector.

Member Function

canPickGraphicModel: Use this function to check whether the graphic model should be picked by the given selector. If the graphic model is picked it will be highlighted when the custom visualization is the target and a selection is made in the source visualization being used as a filter.

Parameters

selector: The selector to check.

isAttrSelector: Whether the selector is an attribute selector.

graphicModel: The graphic model to check.

pickOptions: The criteria to match the graphic model and given selector. This parameter is optional, if you do not want to define a distinctive behavior, just pass this parameter as null.

Usage

  1. Pass a selector as the first parameter.

  2. If the selector is an attribute selector, set the second parameter true, otherwise set it false.

  3. Pass the graphic model as the third parameter to check if it should be picked by the selector given.

  4. Define the options for picking the graphic model. Refer to the section Pick Options for detail.

Implementation

  1. Get the graphic models by calling the member API getGraphicModels.

  2. Iterate through all graphic models and call the member function canPickGraphicModel to check if the graphic model should be picked by the selector.

  3. Return all graphic models picked by the given selector.

Example

getGraphicModelsBySelector: function getGraphicModelsBySelector(selector, isAttrSelector) {
                var viz = this,
                    ret = [],
					//Get the set of graphic models.
                    graphicModels = this.getGraphicModels(),
					//Define the rules for picking the graphic models.
                    pickOptions = {
                        attribute: $PT.METRIC,
                        metric: $PT.METRIC,
                        criteria: $PC.INTERSECTION
                    };
				//Iterate through the set.
                $ARR.forEach(graphicModels.children, function(graphicModel) {
					//Check if the graphic model should be picked
                    if (viz.canPickGraphicModel(selector, isAttrSelector, pickOptions, graphicModel)) {
                        ret.push(graphicModel);
                    }
                });
				// Return all the graphic models picked by the given selector.
                return ret;
            }

API Name

updateHighlight: API to define your own style of highlight.

Parameters

N/A

Member Function:

graphicNeedsHighlight: Call this function to check whether the graphic should be highlighted in the style of selection / context menu selection or not.

Parameters:

graphicModel: The graphic model to check.

forContextMenu: To check whether the graphic is in selection for context menu selection or not.

Usage:

  1. Pass a selector as the first parameter.
  2. To check whether the graphic is in selection, set the second parameter to false, to check whether the graphic is in selection of context menu, set it to true.
  3. You can use this function to check whether the graphic needs to be highlighted and what kind of highlight is needed in the API updateHighlight.

Implementation:

  1. Iterate through all graphics on the visualization, and get the corresponding graphic models.

  2. Call the function graphicNeedsHighlight in the previous table to check whether the graphic should be highlighted in the style of selection/ context menu selection or not.

  3. Realize the style of highlight in each case.

Example

updateHighlight: function updateHighlight() {
                var viz = this;
                //highlight effect for selection
                d3.select(this.domNode).selectAll(".node").select(".outer")
                    .style("stroke", "black")
                    .style("stroke-width", function(graphicModel) {
			// If the graphic should be highlighted as a style for selection, set the border of the bubble to black and 2 pixels in width
                        return viz.graphicNeedsHighlight(graphicModel, false) ? '2px' : '0px';
                    });

                d3.select(this.domNode).selectAll(".node").select(".inner")
                    .style("stroke", "white")
                    .style("stroke-width", function(graphicModel) {
			// If the graphic should be highlighted as a style for selection, set the border of the bubble to white and 2 pixels in width
                        return viz.graphicNeedsHighlight(graphicModel, true) ? '2px' : '0px';
                    });
 
            },

Pick Options

When a custom visualization is the target of a visualization as a filter and highlight mode is selected, the corresponding graphics need to be highlighted when a selection is made on the source visualization. The pick options are used to define the highlighting behavior of the target custom visualization after making a selection on the source visualization.

The Pick Options has three parameters: attribute, metric, and criteria.

attribute

Defines the projection from the header on the source visualization to the graphics on the target custom visualization.

It can be set to one of the following constants:

  • mstrmojo.customviz.PICKED_TYPE.ATTR
  • mstrmojo.customviz.PICKED_TYPE.METRIC

  • mstrmojo.customviz.PICKED_TYPE.BOTH

mstrmojo.customviz.PICKED_TYPE.ATTR means if we select headers on the source visualization, the graphics which represent headers with the same values will be picked and highlighted.

For example, if a row header with value "Sunday" is selected on the source visualization, the graphic in the graphic model that is also an attribute selector with the value of "Sunday" will be picked and selected.

Source

Target

mstrmojo.customviz.PICKED_TYPE.METRIC means if we select headers on the source visualization, the graphics which represent data points which contain the headers with same values will be picked and highlighted.

For example, if we select a row header with value "Sunday" on the source visualization, the graphics whose selectors in the graphic models are metric selectors which contain header with the value of "Sunday" will be picked and selected.

Source

Target

mstrmojo.customviz.PICKED_TYPE.BOTH means if we select headers on the source visualization, both the graphics which represent the headers and the data point with the same values will be picked and highlighted.

The picked graphics are a union of the graphics picked by mstrmojo.customviz.PICKED_TYPE.ATTR and mstrmojo.customviz.PICKED_TYPE.METRIC.

Source

Target

metric

Defines the projection from data points on the source visualization to the graphics on the target custom visualization.

It can be set to the following constants:

  • mstrmojo.customviz.PICKED_TYPE.ATTR
  • mstrmojo.customviz.PICKED_TYPE.METRIC

  • mstrmojo.customviz.PICKED_TYPE.BOTH

mstrmojo.customviz.PICKED_TYPE.ATTR means if we select data points on the source visualization,we will pick and highlight any graphic on the target visualization whose selector is an attribute selector which is among the headers of the data points selected on source visualization and the values of the two headers are equal.

For example, if we select the data point representing the "average delay on Sundays in year 2009" on the source visualization, the graphics which represent the header value "Sunday" and "2009" will be picked and highlighted on the target visualization.

Source

Target

mstrmojo.customviz.PICKED_TYPE.METRIC means if we select headers on the source visualization, the graphics which represent a data point with the same header values will be picked and highlighted on the target visualization.

For example, if we select the data point representing the "average delay on Sundays in year 2009" on the source visualization, the graphic which contains a data point representing "Sundays of year 2009" will be picked and highlighted on the target visualization.

Source

Target

mstrmojo.customviz.PICKED_TYPE.BOTH means if we select headers on the source visualization, both the graphics which represent the headers and the data point with the same values will be picked and highlighted.

The picked graphics are a union of the graphics picked by mstrmojo.customviz.PICKED_TYPE.ATTR and mstrmojo.customviz.PICKED_TYPE.METRIC.

Source

Target

criteria

Defines the projection from graphics on the source visualization to the graphics on the target custom visualization.

It can be set to the following constants:

  • mstrmojo.customviz.PICKED_CRITERIA.SUBSECTION
  • mstrmojo.customviz.PICKED_CRITERIA.INTERSECTION

mstrmojo.customviz.PICKED_CRITERIA.SUBSECTION means only if the set of header(s) in the graphic model bound to a graphic on the source visualization is a subset(not necessarily a true subset) of the set of header(s) in the graphic model bound to the a graphic on the target visualization, the projection is valid.

For example, if we set the parameter metric to mstrmojo.customviz.PICKED_TYPE.METRIC, and select the data point representing the "average delay on Sundays in year 2009" on the source visualization, all the graphics which contain some statistic values on "Sundays of all the months in year 2009" will be picked and highlighted on the target visualization, but the graphic which contain some statistic value of any airline in year 2009 will not be picked.

Source

Target

Target 2

mstrmojo.customviz.PICKED_CRITERIA.INTERSECTION means only if the set of header(s) in the graphic model bound to a graphic on the source visualization has a non-empty intersection with the set of header(s) in the graphic model bound to a graphic on the target visualization, the projection is valid.

For example, if we set the parameter metric to mstrmojo.customviz.PICKED_TYPE.METRIC, and select a data point the data point representing the "average delay on Sundays in January of year 2009" on the source visualization, all the graphics which contain some statistic values of "all airlines on Sundays of year 2009" will be picked and highlighted on the target visualization, but the graphic which contain some statistic value on "Mondays in year 2010" will not be picked.

Source

Target

Target

If the parameter metric is set to mstrmojo.customviz.PICKED_TYPE.ATTR and the data points on the source visualization have more than one header, the criteria parameter should be set to mstrmojo.customviz.PICKED_CRITERIA.INTERSECTION.