Introduction
Starting from the QRC Q4 2023 release of SAP Analytics cloud, users can take advantage of the new feature: Widget Add-on.
The SAP Analytics Cloud Widget Add-On framework will allow you to extend the predefined set of widget add-ons provided by Optimized Story Experience with your own.
You can develop widget add-ons to customize parts of the SAP Analytics Cloud built-in widgets, such as adding visual elements to a chart, modifying tooltip contents and overriding the existing styling.
Supported Add-on Types and Chart Types
As first phase, not all Chart types are supported, we enabled only some specific types for this first phase:
- Tooltip: Supported chart types exclude numeric point.
- Plot area (general): Supported chart types are bar/column, stacked bar/column, stacked area and line.
- Plot area (numeric point): Supported chart type is numeric point.
Permissions
There’re the following permissions for Widget Add-On that you need within your SAP Analytics Cloud tenant:
- Create: Lets you upload widget add-ons to SAP Analytics Cloud.
- Read: Lets you add widget add-ons to the widgets in your story.
- Update: Lets you update widget add-ons.
- Delete: Lets you delete widget add-ons from SAP Analytics Cloud.
Restrictions
You can learn more here about the different restrictions in widget add-ons during the Transport, Hosting, Export, Theming, and other.
Develop Your Own Widget Add-On
Building a Widget Add-on its pretty similar of building a Custom Widget, it consists of two types of files: the widget add-on JSON file and the resource files.
The widget add-on JSON file contains the metadata of a widget add-on. It defines all the ingredients of a widget add-on and references its resource files by their URLs. You need to upload the JSON file of your widget add-on to SAP Analytics Cloud. For more information, refer to Upload Your Widget Add-On to SAP Analytics Cloud (Optimized Story Experience).
The resource files are all the files of the widget add-on that make it work properly, for example, JavaScript files, CSS files, HTML files, image files, and so on. You can upload and host the resource files of your widget add-on in either your own web server or SAP Analytics Cloud. Learn more here about how to host your own Widget Add-Ons
As a developer, you can create 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:
{
"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",
"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": {
"sapHideOriginalDataPointMark": {
"type": "boolean",
"default": true
},
"sapHideOriginalDataPointLabel": {
"type": "boolean",
"default": true
},
"sapHideOriginalXAxisLabel": {
"type": "boolean",
"default": true
},
"sapHideOriginalYAxisLabel": {
"type": "boolean",
"default": true
},
"rounded": {
"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",
"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 Widget Add-On is similar to the one 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.
Currently, the following extension points are supported:
Extension Point
The extension points are exposed by SAP Analytics Cloud widget add-ons framework to developers. They specifies the part of built-in widget to be extended or replaced by webcomponents defined in the 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 widget add-ons are also implemented as web components. However, there're two major differences:- Web components defined in widget add-ons are to add or replace parts of a built-in widget, instead of creating a new widget;
- There're only two types of web components for each widget 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 widget 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 behaviour or the appearance of the built-in widget to better display or improve the extension. For example, the plot area extension is 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 ones provided by the extension won't overlap with the original ones.
The reserved settings can be defined directly in properties node, but its name and type must follow the API reference.
The reserved settings can be defined directly in properties node, but its name and type must follow the API reference.
Add a Widget Add-On to Your Widget (Optimized Story Experience)
To add widget add-ons, ensure that you have the permission Read for the object type Widget Add-On.
Video Demo
You can find the resource files of the Widget Add-On shown in my demo video here. You can download the files and use it as starting point while building your own Widget Add-On.
To resume I would like to say again that with this new feature you will have a new way of leveraging the SAC visualizations without building new widgets from scratch. In addition to the existing feature Custom Widget (which gives you the possibility to build a new type of chart) you can now by building your own Widget Add-ons, change the look and feel of the built-in set of widget that SAC already offers.
Future Direction
In the future we will support more chart types and enhance the extension points so you can extend the predefined set of widget even further.
More blogs to check out 👇
- SAP Managed Tags:
6 Comments
