Customizing the Offset Size of Selected Categories in Sisense Pie Chart Widgets

[JeremyFriedel]

Customizing the Offset Size of Selected Categories in Sisense Pie Chart Widgets

In Sisense, pie chart widgets, including the various pie chart style options such as donut charts, are a common way to visualize data. By default, when a user selects a category within a pie chart, that slice "pops out" to highlight the selection. This article explains how to customize the offset size of selected categories in Sisense pie chart widgets by leveraging the Highcharts settings of the widget using Sisense widget scripting capabilities.

Understanding the Default Behavior

When a slice in a Sisense pie chart is selected, it moves outward from the center by a medium-sized offset. The size of this move is set by the slicedOffset property in the Highcharts setting object, Highcharts is the JavaScript visualizing library that Sisense uses for rendering pie charts and many other common widget types.

Default Pie Chat Offset

Default Donut Pie Chart Offset

The Highcharts slicedOffset Property

The slicedOffset property determines the distance, in pixels, that a slice is moved when it is selected or "sliced out." By modifying this property, it is possible to increase or decrease the offset to better fit the visualization requirements. The unit is always set in raw pixels as an integer and not any other unit.

Accessing and Editing the Highcharts Options Object via Sisense Widget Scripting

To customize the Highcharts settings object within a Sisense widget, the beforeviewloaded event in a widget script can be used. This specific widget event is triggered immediately before Highcharts is used to begin rendering the already fetched and processed data from the Sisense data source, allowing customization of the chart options before the chart is displayed.

Implementation Steps

Add a Widget Script

Navigate to the pie chart widget in question. Open the widget's script editor to add a custom script.

Insert the Custom Script

Use the following code as a template:

// Increase or decrease the size of the offset when a slice in the pie/donut chart is selected
widget.on('beforeviewloaded', function (widget, env) {
    // Pixels to move the selected slice when selected
    var slicedOffset = 50; // Set the desired offset size here

    // Access Highcharts options for the widget
    var chartOptions = env.options;

    // Access pie chart specific Highcharts options
    var pieOptions = chartOptions.plotOptions.pie;

    // Set the offset of the selected slice
    pieOptions.slicedOffset = slicedOffset;
});

Customize the Offset Value

Modify the slicedOffset variable to the desired number of pixels. For example, to decrease the offset size, it might be set to 3, to increase it might be set to 50. Trial and error can be used to determine the best value for the use case.

Offset Increased to 50

Offset Increased to 50 in Donut Pie Chart

Save and Refresh

Save the script and refresh the dashboard. The pie chart will now reflect the new offset size when a slice is selected.

Important Considerations

Highcharts Version Compatibility

Sisense uses a specific version of Highcharts that may differ between Sisense versions and might not always be the latest available version of Highcharts. To ensure compatibility:

Check the Highcharts Version: In the browser's console, enter Highcharts.version to display the current Highcharts version used by Sisense.

Consult Appropriate Documentation: Use the version number to refer to the correct Highcharts documentation in case any settings have changed between versions.

Viewing Current Highcharts Settings

For advanced customizations, it can be helpful to view the existing explicitly defined by Sisense Highcharts options for a widget:

widget.on('beforeviewloaded', function (widget, env) {
    console.log('Highchart Options: ', env.options); // Logs the current Highcharts options to the console
});

By printing the env.options paramater, other customizable properties within the Highcharts configuration object can be viewed. Not all possible or relevant Highchart options are by default defined by Sisense when the default value is not being modified, for example, the slicedOffset parameter is not set directly by Sisense, it did not exist in the default Sisense Highchart Setting object before being defined in a script, the Highchart documentation contains the full list of possible Highcharts settings.

Extending Customizations

The scripting customization method described here isn't limited to adjusting the slicedOffset property. Any Highcharts setting available for the chart type by altering the env.options object within the beforeviewloaded event. This allows extensive visual customization of Sisense widgets.

Conclusion

Customizing the offset size of selected slices in Sisense pie chart widgets can enhances the interactivity and readability of pie chart visualizations. By tapping into the Highcharts settings through the beforeviewloaded event, it is possible to have granular control over the chart's behavior and appearance. Other Highcharts settings can also be modified using this script template.

References

Highcharts Documentation: Highcharts Reference

Sisense Documentation on Widget Scripts: Sisense Widget JavaScript

Sisense Academy course on Widget Plugins and Scripts: Advanced Dashboards with Plug-ins and Scripts