2/9/25, 4:40 PM

SAP Analytics Cloud Widget Add-On

Developer Guide
Generated on: 2025-02-09 16:40:24 GMT+0000

SAP Analytics Cloud | Q4 2024 (2024.21)

Public

Original content: https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/35a443e276964981a85bf2b0cb58e180?locale=en-

US&state=PRODUCTION&version=release

Warning

This document has been generated from SAP Help Portal and is an incomplete version of the official SAP product documentation.
The information included in custom documentation may not reflect the arrangement of topics in SAP Help Portal, and may be
missing important aspects and/or correlations to other topics. For this reason, it is not for production use.

For more information, please visit https://help.sap.com/docs/disclaimer.

This is custom documentation. For more information, please visit SAP Help Portal. 1
 2/9/25, 4:40 PM

Develop Your Own Widget Add-On

As a developer, you can develop your own widget add-on, which customizes parts of the SAP Analytics Cloud to meet your
requirements.

You can define the widget add-on using JavaScript in a contribution JSON file. Here's the sample code:

 Sample Code

{
"id": "com.demo.localVizAddOns",
"version": "1.0.0",
"name": "Widget Customization Local Add-on",
"description": "A widget customization add-on demo",
"icon": "undefined",
"vendor": "Demo",
"eula": "EULA",
"license": "1.0",
"extensions": [
{
"extensionPoint": "sap.addOn.viz.tooltip",
"webcomponents": [
{
"kind": "main",
"tag": "viz-tooltip",
"url": "http://localhost:8088/viz-tooltip.js",
"integrity": "",
"ignoreIntegrity": true
},
{
"kind": "builder",
"tag": "viz-tooltip-build",
"url": "http://localhost:8088/viz-tooltip-builder-panel.js",
"integrity": "",
"ignoreIntegrity": true
}
],
"properties": {
"max": {
"type": "number",
"description": "The max of range value",
"default": "100"
},
"color": {
"type": "string",
"description": "Text Color info",
"default": "lightblue"
}
}
},
{
"extensionPoint": "sap.addOn.viz.plotarea.barColumn",

This is custom documentation. For more information, please visit SAP Help Portal. 2
 2/9/25, 4:40 PM
"webcomponents": [
{
"kind": "main",
"tag": "viz-overlay",
"url": "http://localhost:8088/viz-plotarea.js",
"integrity": "",
"ignoreIntegrity": true
},
{
"kind": "builder",
"tag": "viz-plotarea-build",
"url": "http://localhost:8088/viz-plotarea-builder-panel.js",
"integrity": "",
"ignoreIntegrity": true
}
],
"properties": {
"sapHideOriginalDataPointMarks": {
"type": "boolean",
"default": true
},
"sapHideOriginalDataPointLabels": {
"type": "boolean",
"default": true
},
"sapHideOriginalXAxisLabels": {
"type": "boolean",
"default": true
},
"sapHideOriginalYAxisLabels": {
"type": "boolean",
"default": true
},
"sapHideOriginalXAxisStackLabels": {
"type": "boolean",
"default": true
},
"sapHideOriginalYAxisStackLabels": {
"type": "boolean",
"default": true
},
"sapHideOriginalLegendLabels": {
"type": "boolean",
"default": true
},
"sapHideOriginalLegendSymbols": {
"type": "boolean",
"default": true
},
"sapHideOriginalLegendLines": {
"type": "boolean",
"default": true
},
"rounded": {

This is custom documentation. For more information, please visit SAP Help Portal. 3
 2/9/25, 4:40 PM
"type": "boolean",
"description": "Should bar/column be rounded",
"default": true
},
"sizeIncrement": {
"type": "number",
"description": "The increment rate of bar/column size",
"default": 0
},
"axisLabelColor": {
"type": "string",
"description": "The chart axis label color",
"default": "#fff"
}
}
},
{
"extensionPoint": "sap.addOn.viz.plotarea.numericPoint",
"webcomponents": [
{
"kind": "main",
"tag": "viz-metric-plotarea",
"url": "http://localhost:8088/viz-metric-plotarea.js",
"integrity": "",
"ignoreIntegrity": true
},
{
"kind": "builder",
"tag": "viz-metric-plotarea-build",
"url": "http://localhost:8088/viz-metric-plotarea-build.js",
"integrity": "",
"ignoreIntegrity": true
}
],
"properties": {
"sapHideOriginalPrimaryNumber": {
"type": "boolean",
"default": true
},
"sapHideOriginalPrimaryLabel": {
"type": "boolean",
"default": true
},
"sapHideOriginalSecondaryNumber": {
"type": "boolean",
"default": true
},
"sapHideOriginalSecondaryLabel": {
"type": "boolean",
"default": true
},
"labelColor": {
"type": "string",
"description": "The chart axis label color",

This is custom documentation. For more information, please visit SAP Help Portal. 4
 2/9/25, 4:40 PM
"default": "red"
},
"numberColor": {
"type": "string",
"description": "The chart axis number color",
"default": "green"
},
"max": {
"type": "number",
"description": "The max of range value",
"default": "100"
}
}
}
]
}

The JSON file format of a custom add-on is similar to that of a custom widget. The difference mainly lies in the extensions node,
which is an array of add-on specifications comprising of extension point, web components, properties and reserved settings. Refer
to the following sections for more information about them.

Extension Point

The extension points are exposed by SAP Analytics Cloud custom add-ons framework to developers. extensionPoint specifies
the part of built-in widget to be extended or replaced by webcomponents defined in extensions.

Currently, the following extension points are supported:

sap.addOn.viz.tooltip

sap.addOn.viz.plotarea.general

sap.addOn.viz.plotarea.numericPoint

Web Components

Similar to custom widgets, the extensions of custom add-ons are also implemented as web components. However, there're two
major differences:

1. Web components defined in custom add-ons are to add or replace parts of a built-in widget, instead of creating a new
widget;

2. There're only two types of web components for each custom add-on: one is main component, and the other is builder panel
component. There's no styling panel component.

Properties

Similar to custom widgets, the properties of the custom add-ons can be defined.

Reserved Settings

Different from the properties defined in custom widgets, there're pre-defined property settings for custom add-ons that change
the behavior or appearance of the built-in widget to better display or improve the extension. For example, the plot area extension is

This is custom documentation. For more information, please visit SAP Help Portal. 5
 2/9/25, 4:40 PM
displayed as an overlay over the original chart. To have better visual effects, you can choose to hide data point markers, data point
labels or axis labels on original chart so that the the ones provided by extension won't overlap with original ones.

The reserved settings can be defined directly in properties node, but its name and type must follow the API reference.

API Reference
Look up APIs related to custom add-ons.

IAddOnComponent
To make the communication between custom extensions and SAP Analytics Cloud framework possible, and also to manage the
custom extension's lifecycle, the custom component provided in add-on extension should extend following interface:

 Code Syntax

export type ExtensionDataType = IVizTooltipExtensionData | IVizGeneralPlotareaExtensionData | IV

export interface IAddOnComponent {

/**
* Called by SAC add-on extension framework to set exposed extension data to custom add-on co
* @param {ExtensionDataType} extensionData The extension data that SAC exposed to custom ele
*/
setExtensionData(extensionData: ExtensionDataType);

/**
* Called before the custom settings properties changed.
* @param {Object} changedProps The changed settings properties of this custom element;
*/
onBeforeUpdate?(changedProps: any): void;

/**
* Called after the custom settings properties changed.
* @param {Object} changedProps The changed settings properties of this custom element;
*/
onAfterUpdate?(changedProps: any): void;
}

IVizTooltipExtensionData

 Code Syntax
/**
* Interface to describe a row displayed on chart tooltip
*/
export interface IVizTooltipRow {
/**
* The title of the row
*/
title: string;

/**
* The value of the row
*/
value: string;
This is custom documentation. For more information, please visit SAP Help Portal. 6
 2/9/25, 4:40 PM

/**
* The key of the row
*/
key?: string;
}

export interface IVizTooltipHeaderRow extends IVizTooltipRow {

/**
* The warnings displayed on chart tooltip header
*/
warnings?: string[];
}

/**
* Interface of chart tooltip extension data
*/
export interface IVizTooltipExtensionData {
/**
* The header row data of chart tooltip
*/
header: IVizTooltipHeaderRow;
/**
* The details rows data of chart tooltip
*/
details: IVizTooltipRow[];
}

IVizGeneralPlotareaExtensionData and Reserved Settings

 Code Syntax
export interface ISize {
width: number;
height: number;
}

export interface IPoint {

x: number;
y: number;
}

export type IRect = IPoint & ISize;

export interface IRectWithValue extends IRect {

/**
* The value that current rect element is representing
*/
pointValue: string | number;
/**
* The displayed/formatted value of current rect element is representing
*/
formattedValue: string;
}

export interface ILabelRect extends IRect {

/**
* The color of this label
*/
color: string;
/**
* A string of a number ending with 'px' indicating the font size of this label
*/
fontSize: string;
/**
* A string of number between 0 and 1 indicating the opacity of this label
*/
opacity?: string;
}

/**
This is custom documentation. For more information, please visit SAP Help Portal. 7
 2/9/25, 4:40 PM
* Defines CSS properties of a rect.
*/
export interface IRectStyles {
/**
* The font family to use for the text.
* e.g., "Arial", "Helvetica", "Times New Roman"
*/
fontFamily?: string;
/**
* The font style to apply.
* e.g., "normal", "italic", "oblique"
*/
fontStyle?: string;
/**
* The font weight (thickness).
* e.g., "normal", "bold", "bolder", "lighter",
* or numeric values (100-900)
*/
fontWeight?: string;
/**
* Text decoration to add.
* e.g., "none", "underline", "overline",
* "line-through"
*/
textDecoration?: string;
/**
* Text shadow effect.
* Format: "h-shadow v-shadow blur color"
* e.g., "2px 2px 5px rgba(0, 0, 0, 0.5)" for
* a semi-transparent black shadow
*/
textShadow?: string;
};

interface ISeries {
/**
* The layout information of data points in current series
*/
dataPoints: IDataPoint;
/**
* If current series is selected
*/
selected: boolean;
/**
* The name of the series;
*/
name: string;
/**
* The color of the data point marks in current series.
* In the format of either "[css_color]" or "[pattern_id] [css_color]".
* eg. "#CCCCCC" or "hatch2 #CCCCCC"
* The pattern_id has no significance to developers.
*/
color: string;
/**
* If Show-as Triangle is enabled on current series
*/
showAsTriangle?: boolean;
/**
* The layout information of the legend item in current series
*/
legendInfo?: ILegendInfo;
}

interface IDataPoint {
/**
* Provide data mark layout information of current data point;
*/
dataInfo: IDataInfo;
/**
* Provide data label layout information of current data point;
*/
labelInfo: ILabelInfo;
}

This is custom documentation. For more information, please visit SAP Help Portal. 8
 2/9/25, 4:40 PM

interface IDataInfo extends IRectWithValue {

pointValue: number;
/**
* Color of current data point mark in original chart
*/
color: string;
/**
* The border color of current data point mark in orignal chart
*/
borderColor: string;
/**
* If current data point is selected
*/
selected?: boolean;
}

interface ILabelInfo extends ILabelRect {

pointValue: string;
/**
* If this label is a variance label, then it will have this property indicating
* the type of this variance label
*/
varianceLabelType?: 'positive' | 'negative' | 'nullzero';
}

interface IAxisLabel extends ILabelRect {

pointValue: string;
}

interface ILegendLabel extends ILabelRect {

/**
* The text string of the legend item.
*/
textStr: string;
/**
* The extra styles of the legend label text.
*/
styles: IRectStyles;
}

interface ILegendInfo {
/**
* The layout information of the legend label.
*/
label?: ILegendLabel;
/**
* The layout information of the legend symbol.
*/
symbol?: IRect;
/**
* The layout information of the legend line.
*/
line?: IRect;
}

interface ILegendContainer extends IRect {

/**
* The view range of legend section in the chart. It should
* be applied to custom add-on component's clip-path style
* so that the legend items out of view range are not
* displayed.
* Could be undefined if the legend is not shown in
* multi-pages.
*/
clipPath?: IRect;
}

export interface IVizGeneralPlotareaExtensionData {

/**
* The size of original chart
*/
chartSize: ISize;
/**

This is custom documentation. For more information, please visit SAP Help Portal. 9
 2/9/25, 4:40 PM
* If true, it's a bar chart, otherwise it's a column chart
*/
isHorizontal: boolean;
/**
* The view range of current chart. It should be applied to
* custom add-on component's clip-path style so that the
* elements (data points, labels) out of view range are not
* displayed.
*/
clipPath: IRect;
/**
* The series of the chart
*/
series: ISeries[];
/**
* The layout information of x-aixs labels
*/
xAxisLabels?: IAxisLabel[];
/**
* The layout information of y-axis labels
*/
yAxisLabels?: IAxisLabel[];
/**
* The layout information of x-aixs stacked labels
*/
xAxisStackLabels?: IAxisLabel[];
/**
* The layout information of y-aixs stacked labels
*/
yAxisStackLabels?: IAxisLabel[];
/**
* The layout information of the whole container of legends
*/
legendContainer?: ILegendContainer;
}

 Code Syntax
export const AddOnsReservedSettings = {
['sap.addOn.viz.plotarea.general']: {
['sapHideOriginalDataPointMarks']: {
'type': 'boolean',
'description': 'If the data point marks should be hidden on original chart',
'default': false
},
['sapHideOriginalDataPointLabels']: {
'type': 'boolean',
'description': 'If the data point labels should be hidden on original chart',
'default': false
},
['sapHideOriginalXAxisLabels']: {
'type': 'boolean',
'description': 'If the x-axis labels should be hidden on original chart',
'default': false
},
['sapHideOriginalYAxisLabels']: {
'type': 'boolean',
'description': 'If the y-axis labels should be hidden on original chart',
'default': false
},
['sapHideOriginalXAxisStackLabels']: {
'type': 'boolean',
'description': 'If the stack labels on x-axis should be hidden on original chart',
'default': false
},
['sapHideOriginalYAxisStackLabels']: {
'type': 'boolean',
'description': 'If the stack labels on y-axis should be hidden on original chart',
'default': false
},
['sapHideOriginalLegendLabels']: {
'type': 'boolean',

This is custom documentation. For more information, please visit SAP Help Portal. 10
 2/9/25, 4:40 PM
'description': 'If the legend labels should be hidden on original chart',
'default': false
},
['sapHideOriginalLegendSymbols']: {
'type': 'boolean',
'description': 'If the legend symbols should be hidden on original chart',
'default': false
},
['sapHideOriginalLegendLines']: {
'type': 'boolean',
'description': 'If the legend lines should be hidden on original chart',
'default': false
},
},
};

IVizNumericPointPlotareaExtensionData and Reserved Settings

 Code Syntax
interface INumber extends ILabelRect {
pointValue: string | undefined;
}

interface ILabel extends ILabelRect {

pointValue: string | undefined;
}

interface IRow {
/**
* The layout information of row number
*/
number: INumber;
/**
* The layout information of row label
*/
label: ILabel;
}

export interface IVizNumericPointPlotareaExtensionData {

/**
* The size of original chart
*/
chartSize: ISize;
/**
* The layout information of primary values
*/
primaryRows: IRow[];
/**
* The layout information of y-axis labels
*/
secondaryRows: IRow[];
}

 Code Syntax
export const AddOnsReservedSettings = {
['sap.addOn.viz.plotarea.numericPoint']: {
['sapHideOriginalPrimaryNumber']: {
'type': 'boolean',
'description': 'If the numbers of primary values should be hidden on original chart'
'default': false
},
['sapHideOriginalPrimaryLabel']: {
'type': 'boolean',
'description': 'If the labels of primary values should be hidden on original chart',
'default': false
},

This is custom documentation. For more information, please visit SAP Help Portal. 11
 2/9/25, 4:40 PM
['sapHideOriginalSecondaryNumber']: {
'type': 'boolean',
'description': 'If the numbers of secondary values should be hidden on original char
'default': false
},
['sapHideOriginalSecondaryLabel']: {
'type': 'boolean',
'description': 'If the labels of secondary values should be hidden on original chart
'default': false
}
},
};

This is custom documentation. For more information, please visit SAP Help Portal. 12