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

 

 

// 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/