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