Customize Context Menus

The Context Menu API allows for the customization of the contents and behavior of the context menus users can access while viewing a custom visualization.

Context menus are triggered by a right-mouse-click (desktop), or long tap (mobile device). You can handle both of these event by overwriting the oncontextmenu function in your custom 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 Context Menu Selection
4. Configure and Show Context Menu

Create Graphic Models

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 the dataInterface class 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.

4. 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.

5. Call the functions of the GraphicModel class to prepare the data needed for commands in the common context menu. For the details on the usage, see GraphicModel Class.

   • setSelector: required for all commands.

   • setGroupOptions: required for all group/calculation.

   • setDrillOptions: required for all group/calculation.

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);
                    // Set the headers used in group/calculation.
                    graphicModel.setGroupOptions(row.headers);
                    // Set the selector and the action of drop zone used in drill. 
                    graphicModel.setDrillOptions(headers[0].attributeSelector, [{
                            dropZoneIndex: 0,
                            keepParent: 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

Bind the graphic model to each graphic in the visualization, then get the graphic model from a graphic and pass it to the API to enable selection.

Member Function Name

getGraphicModels: Retrieves the set of graphic models you created in the createGraphicModels API.

Parameters

N/A

Usage

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 Context Menu Selection

The context menu selection the graphic model is the base of the commands in common part of the context menu, to enable context menu selection, we need to call handleContextMenuSelection() to notify our framework of context menu selection change,and this API will show context menu.

Member Function Name

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

Parameters

graphicModel: The graphic model to bind to the graphic.

Usage

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);
},

Configure and Show Context Menu

Two steps are involved to configure and show the context menu in the custom visualization.

First, implement the getContextMenuConfig API to tell the custom visualization framework what kind of menu items to show. Then the member function oncontextmenu is implemented to configure and show the menu when a right-mouse-click (desktop) or long tap (mobile device) event is detected.

Detailed information for configuring the commonConfig and customConfig variables can be found here:

• Common Context Menu Items
• Custom Context Menu Items

API Name:

getContextMenuConfig: Implement this API to provide configuration for building up the context menu.

Parameters

graphicModel: The graphic model to bind to the graphic.

Implementation

1. Define the common part of the context menu.

2. Define the customized part of the context menu.

3. Return the configuration in the format:

   Copy

   {
       common: commonConfig,
       custom: customConfig
   };

Example

getContextMenuConfig: function getContextMenuConfig(graphicModel) {
                var commonConfig = [
                    {
                        type: $DEFAULT_CONTEXT_MENU.KEEP_ONLY
                    }, {
                        type: $DEFAULT_CONTEXT_MENU.EXCLUDE
                    }, {
                        type: $DEFAULT_CONTEXT_MENU.DRILL
                    }, {
                        type: $DEFAULT_CONTEXT_MENU.GROUP
                    }, {
                        type: $DEFAULT_CONTEXT_MENU.CALCULATION
                    }, {
                        type: $DEFAULT_CONTEXT_MENU.SHOW_DATA
                    }, {
                        type: $DEFAULT_CONTEXT_MENU.GO_TO_TARGETS
                    }
                ];

                var customConfig = [
                    // ...
                    ];

                return {
                    common: commonConfig,
                    custom: customConfig
                };
}

Member Function Name

oncontextmenu: Implement this function to handle context menu selection and framework will show context menu.

Parameters

evt: The DOM event of context menu triggered.

Usage

1. Get the original event from the browser.

2. Find the object on which the event was triggered.

3. Pass the graphic model (d3 object in the sample code) to call handleContextMenuSelection(), and it will show the context menu.

Example

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

     var targetNode = evt.getTarget(),
         d = d3.select(targetNode).datum();

     this.handleContextMenuSelection(evt.e, d);
},

The context menu is not shown on documents in express mode and visualization as a filter consumption mode.