Customizing Upper Label (PlotBands) Labels in Sisense Column Chart Widgets for Long Category Labels

[JeremyFriedel]

Customizing Upper Label (PlotBands) Labels in Sisense Column Chart Widgets for Long Category Labels

Sisense allows customization of chart settings through Highchart option configurations, as documented in this community post leveraging the Highcharts settings of the widget using Sisense widget scripting capabilities.

When creating Sisense column chart widgets with two fields in the "Categories" panel, an upper label is created. These labels can be long, requiring management of lengthy category labels in column chart widgets. In the Highcharts library terminology, these upper labels are called plotBands. This article explains how to modify plotBand label settings in Sisense column chart widgets to support long upper category labels by adjusting font size and enabling multi-line labels. This method demonstrates another use of the beforeviewloaded widget event to adjust Highcharts configurations in a Sisense widget, similar to adjusting offset sizes in pie charts as discussed in this article.

PlotBand Labels in Column Charts

In Sisense, plotBands appear on the upper level of a column chart when two fields are added to the "Categories" panel. The first field defines the upper plotBands, serving as high-level categories for bar groups. The second field defines the individual columns or bars within each group. Lengthy upper category labels can cause display issues:

• Truncation: Long labels may be cut off, hiding important information.
• Overlap: Labels may overlap with other labels or elements, reducing readability.
• Aesthetic Issues: Large labels can appear crowded, especially in compact widgets.

To address these issues, font size can be reduced and labels can be split into multiple lines, ensuring they are readable within the available space.

Accessing and Customizing Highcharts Options with beforeviewloaded

The beforeviewloaded event in Sisense triggers just before Highcharts renders the chart with fetched data. By accessing the options parameter in this event, plotBand label settings can be adjusted to:

• Set Font Size: Use a smaller font size for upper plotBand labels to accommodate lengthy text.
• Enable Multi-Line Labels: Break longer labels into multiple lines, up to a defined maximum line count.

Implementing Custom PlotBand Labels in Column Chart Widgets

Define Configuration Variables

Two variables control label appearance:

• Font Size: Set an appropriate font size for the widget's dimensions, such as '10px' for narrower widgets.
• Max Lines: Specify the maximum number of lines to split labels into; for example, 4 allows labels to wrap across up to four lines.

Add a Custom Script in Sisense

In the column chart widget's script editor, enter the following code:

// Customizes Sisense Highcharts label settings to support long plotBand (upper category) labels
// by reducing font size and enabling multi-line labels.

widget.on('beforeviewloaded', function (widget, env) {

    // Set font size for upper category labels
    const upperLabelFontSize = '10px';

    // Set the maximum number of lines for upper category labels
    const maxUpperLabelLines = 4;

    // Modify each plotBand's label settings
    env.options.xAxis.plotBands.forEach((plotBand) => {
        // Set font size for plotBand labels
        plotBand.label.style["font-size"] = upperLabelFontSize;

        // Apply a custom formatter to split labels into multiple lines
        plotBand.label.formatter = function () {
            const label = this.options.label.text;
            return splitLabel(label, maxUpperLabelLines);
        };
    });

    // Helper function to split labels into lines based on max line count
    function splitLabel(label, maxLines) {
        const words = label.split(' ');
        let bestConfiguration = [];
        let minMaxLineLength = Infinity;

        // Attempt to split the label into lines up to the max allowed
        for (let lines = 1; lines <= maxLines; lines++) {
            const avgLength = Math.ceil(label.length / lines);
            const currentLines = [];
            let currentLine = '';

            for (const word of words) {
                const newLength = currentLine ? currentLine.length + word.length + 1 : word.length;
                if (newLength <= avgLength) {
                    currentLine += (currentLine ? ' ' : '') + word;
                } else {
                    currentLines.push(currentLine);
                    currentLine = word;
                }
            }

            if (currentLine) {
                currentLines.push(currentLine);
            }

            if (currentLines.length > maxLines) {
                continue;
            }

            const maxLineLength = Math.max(...currentLines.map(line => line.length));

            if (maxLineLength < minMaxLineLength) {
                minMaxLineLength = maxLineLength;
                bestConfiguration = currentLines;
            }
        }

        return bestConfiguration.join('<br>');
    }

});

Adjust Variables as Needed

Modify `upperLabelFontSize` and `maxUpperLabelLines` to suit the widget's dimensions:

• `upperLabelFontSize`: Smaller values like '8px' can be used for compact widgets
• `maxUpperLabelLines`: Increase if labels are especially long; setting to 4 or 5 allows multi-line labels without cluttering.

Save and Refresh

After saving the script, refresh the dashboard. The plotBand labels should now reflect the customizations:

• Font size is adjusted as specified.
• Long labels wrap based on the `maxUpperLabelLines` setting.
  
  

How the Script Works

Modifying Label Styles

The script iterates through each `plotBand` in `xAxis.plotBands` to set font size and apply a custom formatter:

• Font size is set via `plotBand.label.style["font-size"]`.
• A custom formatter function formats labels into multiple lines based on the maximum line count.

Splitting Labels into Multiple Lines

The `splitLabel` function processes labels by:

• Splitting the label into words.
• Distributing words across lines to minimize the length of the longest line, adhering to the maximum line count.
• Returning the label with `<br>` tags for multi-line display.

Additional Considerations

Highcharts Version Compatibility in Sisense

The Highcharts version used by Sisense may vary. Check compatibility by entering `Highcharts.version` in the browser console and refer to the corresponding Highcharts documentation.

Widget Size and Label Configuration

Adjust font size and line count based on widget dimensions:

• Narrow widgets benefit from smaller font sizes and fewer lines.
• Wider widgets can use larger font sizes and more lines for better readability.

Larger Font Size and Max Lines Reduced to 3

Extending Customizations

This approach can be extended to customize other label attributes, such as color or weight, and applied to other Highcharts elements like data labels or tooltips. This article discusses further on viewing existing default Highchart settings.

Conclusion

Customizing plotBand labels settings in Sisense column chart widgets can enhances readability, especially for long upper category names. Using the `beforeviewloaded` widget event to modify Highcharts settings allows tailoring plotBand label configurations to meet specific dashboard requirements. This method demonstrates the versatility of the `beforeviewloaded` event for creating clear and effective visualizations in Sisense via modifying Highcharts settings.

Related Content:

Docs: https://docs.sisense.com/main/SisenseLinux/customizing-sisense-using-code.htm

Dev Docs: https://sisense.dev/guides/customJs/extensions/