Within the story of SAP Analytics Cloud, different visualizations are needed for different scenarios. SAP Analytics Cloud offers a wide range of charts and widgets to help users with data visualization, but some are not perfectly suited to the needs of a wide variety of practical scenarios. The custom widget framework for SAP Analytics Cloud allows to add your own custom widgets that provide a specific visualization of user. At this point, customers can customize their widgets by uploading custom widgets and use them in stories.
Based on the demo of the custom widget in the Help Portal, I developed a tree custom widget. This blog focuses on the process and references I use to implement a custom widget from scratch, as well as sharing practical experience during development.
Click here for the demo video.
This blog will elucidate the process of implementing custom widgets, detailing how to upload and utilize them in SAP Analytics Cloud, and will be organized into four main sections for a comprehensive overview. The outline of the blog is as follows:
Introduction to Custom Widgets Custom Widget Development Process index.json main.js styling.js How to Upload Custom Widgets in SAP Analytics Cloud ？ Summary
1. Introduction to Custom Widgets
The SAP Analytics Cloud Custom Widget framework allows you to use your own custom widgets to extend the predefined set of widgets available in optimized stories. This can be useful, for example, if you need specific user interface elements, specific data visualizations, or specific features that aren’t available with a predefined set of widgets. Custom widgets can be seamlessly integrated into optimized stories for SAP Analytics Cloud. Like predefined widgets, custom widgets offer the following features:
It is listed in the widget menu list from where you can add it to the canvas. It can be moved and resized on the canvas. It appears in the widget outline. It can contribute script methods to the analytics designer script language. It can provide areas in analytics designer where you can set property values of the custom widget at design time (Styling Panel and Builder Panel).
The source file of a custom widget consists of two types of files: a JSON file and resource files (JavaScript files).
JSON File
JSON file contains metadata in widgets, URL references to resource files, and so on.
Resource Files main.js (the actual custom widget) styling.js (the Styling Panel of custom widget) builder.js (the Builder Panel of custom widget)
Each of these JavaScript files is a web component. Make your own custom widget to start with the files above.
2. Custom Widget Development Process
In the tree custom widget I developed, mainly contains the three files “index.json”, “main.js”, “styling.js”.
Index.json
The following properties must be included in the JSON file of a custom widget:
id version name newInstancePrefix webcomponents properties methods events dataBindings
Here you have to guarantee the uniqueness of the id, which is your custom widget’s unique ID. When you upload a custom widget that already exists, the system will remind you that if you proceed with the upload, it will overwrite the previously existing custom widget with the same id.
A web component object specifies a custom widget within a web component. For each web component object, three properties are necessary: “kind”, “tag”, and “url”. Kind can only be one of “main,” “styling,” or “builder,” and the url is the relative position of the JavaScript file corresponding to the web component.
Note: The tag is the unique identifier of the custom element of the web component whose name must contain at least one hyphen (-) to distinguish a custom element from a regular HTML element. And the tag must match the definition in the JavaScript file, or else the system will not be able to find the corresponding JavaScript file and will prompt the following error.
Inside my custom widget, only the two types “main” and “styling” are used. If you also want to customize the content of the builder panel, you also need to add a web component of type “builder”.
The properties object contains some properties of a custom widget and their default values. Each property name in the properties object must correspond to the property name of the custom widget. For example, in the properties, you can define properties of the custom widget such as width, height, node color, font size, etc., which can be used in the JavaScript file. The values of the properties can be modified through the styling panel and then passed to the main component for re-rendering, thereby changing the style of the custom widget.
The Methods object specifies the script methods included in a custom widget, including property setting methods. Each property name in the Methods object corresponds to a script method name in the custom widget. For example, in my widget, the setNodeFontSize method is defined to set the font size of a node. This method is used in main.js, and whenever the value of the nodeFontSize property changes, the function will retrieve the new value and update the corresponding font size in the component.
By defining dataBindings in JSON file, you can access data from the model within a custom widget. The data returned by dataBindings mainly consists of two parts:
data: This is an array containing all the returned data. Each object in the array represents a piece of data (the value of a measure corresponding to one or several “dimensions”). metadata: Metadata contains attribute information about some “measures” and “dimensions” present in the data.
The format of the data returned by dataBindings may not necessarily match the format required by the custom widget. You can reorganize the structure of the data based on the data format requirements of a Echarts chart. For more information on using dataBindings, please click here .
Examples of data returned by dataBindings are as follows.
For a more detailed description and usage of the individual valid attributes in the JSON file, see the documentation on the Help Portal .
main.js
In the main.js file lies the core part of my custom widget. As I aimed to create a tree structure, I referenced the tree component in the Echarts library for display. After obtaining data through dataBindings, I wrote a function to transform the data structure into a tree structure. Having the correct data structure is the most crucial step for the successful display of the component. Once the data is correctly integrated into the Echarts tree component, a basic tree display structure can be obtained, which can then be optimized and adjusted according to individual needs.
For instance, in my custom widget, I wanted the tree structure to support different orientations. This led to the issue of adjusting the direction of each node’s label. Therefore, I needed to consider every distribution scenario of the tree structure and set the direction of label display accordingly. For a tree distributed from left to right, the labels of leaf nodes are displayed to the right of the node, while labels of other nodes are displayed to the left. In a tree distributed from top to bottom, the labels of leaf nodes are shown below the node, while labels of other nodes are displayed above. Similar adjustments apply to other distribution scenarios. By default, my node labels display the node name and its corresponding value. In cases where a node has no value, only the node name is displayed. Of course, you can customize the display content according to your requirements.
The orthogonal layout effect is as follows:
The radial layout effect is as follows:
In the diagram below, you can see that the nodes in the tree structure are either hollow or solid. Hollow nodes indicate that the node cannot be further expanded, while solid nodes indicate that clicking on the node can expand its child nodes.
When a threshold is set in the style settings panel, nodes in the tree diagram with values exceeding the threshold will be highlighted in red. This helps us effectively display which nodes in different hierarchical structures exceed the threshold.
(Note: In my code, the default threshold value is set to 1,000,000,000. If you wish to modify this default value, you can edit the default value at line 233 in the sample code main.js, and also at line 79 in index.json.)
A threshold value of 50,000,000 is set in the styling panel, and the nodes in the tree chart with values over 50,000,000 are highlighted in red.
I chose to show the node name, value, and unit information inside the tooltip.
If you want to customize the tooltip format, you can modify this part of main.js.
Here need to point out that currently this version of the tree widget only implements a version that supports one measure, and if you want to implement a tree that supports multiple measures, you can add multiple series to your code to present the values of multiple measures.
styling.js
The content in the styling.js file controls the module for additional properties of the custom widget in the style settings panel.
In my custom widget, I aim to modify some basic properties of the tree component, change layout settings, and highlight nodes exceeding a threshold. Therefore, my style panel settings are as shown in the diagram below.
Layout settings are divided into two types: orthogonal layout and radial layout. The orthogonal layout allows for setting the distribution direction as “L-R,” “R-L,” “T-B,” and “B-T.”
It is important to note that only the orthogonal layout requires setting the direction and edge type. When selecting the radial layout, these two properties are not needed. To avoid unnecessary errors, I have set the selectors for direction and edge type to be hidden by default when the radial layout option is selected.
Regarding node color settings, the current version of this custom widget only supports manually entering some color names in English or hexadecimal and RGB color values, such as “dark blue,” “#00FF00,” “RGB(0,0,255),” etc. If you wish to further enhance this feature, you can consider integrating a color picker plugin.
3. How to Upload Custom Widgets in SAP Analytics Cloud
You can upload and host these resource files in SAP Analytics Cloud to use custom widgets in a story. You need to upload the JSON file of the custom widget along with the corresponding resource files to SAP Analytics Cloud.
Navigate to the story page, click on the custom widget, and select the add icon to upload the JSON file and its associated resource files separately.
Note: When uploading resource files, make sure to compress them into a .zip file format and ensure that the .zip file is smaller than 10MB.
In the story, add the custom widget by finding the widget you uploaded and inserting it into the story.
Open the builder panel, select your model, and add “Measures” and “Dimensions.”
Note: The dimensions you add must have a hierarchical structure. When setting up different hierarchical structures, make sure to check “Include Parent Node Elements” to correctly display the tree structure.
In the styling panel, you can modify and apply its properties in the Custom Widget Additional Properties module. The properties that can be modified in the styling panel are determined by your definitions in the styling.js resource file. In a tree custom widget, the styling panel can change the style of a tree, such as root node name, layout settings, direction settings, connection edge types, node types, and so on.
4. Summary
The above is the complete process of developing a tree custom widget, which can be applied to various data visualization and analysis scenarios with hierarchical structures.
For example, it can be used in:
Organizational structure display in human resources: Show the hierarchical relationships among departments and positions within a company through a tree structure, clarify employee responsibilities, and assist management in optimizing human resource allocation and adjusting organizational structures. BOM display in production scenarios: Utilize a tree structure to display the bill of materials (BOM) of products and their hierarchical relationships, supporting production planning and material management to help companies control costs and improve production efficiency. Display of account hierarchy structure in financial statements: Use a tree structure to display detailed information on the general ledger, sub-accounts, various expenses, and income levels, helping financial personnel and management analyze financial conditions more intuitively and identify potential issues. Sales performance display for different regions, departments, or product lines: Use a tree structure to display sales performance from global revenue down to sales performance at the continent, country, and regional levels, helping companies identify which regions or product lines contribute the most, or discover sales bottlenecks.
In the first version, there are still many incomplete aspects. If this tree diagram is helpful for you, you can download the source code for reference and make modifications and adjustments based on it.
During the implementation of the custom widget, I found some very helpful blogs. If you are interested in creating your own custom widget, you can refer to them:
Use Custom Widgets (Optimized) | SAP Help Portal
Custom Widgets | SAP Help Portal
SAP Analytics Cloud: Custom Widget Hands-on Guide – SAP Community
SAP Analytics Cloud: Custom Widget & Widget Add-On… – SAP Community
Your first SAP Analytics Cloud Custom Widget – Int… – SAP Community
Your first SAP Analytics Cloud Custom Widget – Par… – SAP Community
Your first SAP Analytics Cloud Custom Widget – Par… – SAP Community
Your first SAP Analytics Cloud Custom Widget – Par… – SAP Community
Your first SAP Analytics Cloud Custom Widget – Par… – SAP Community
Your first SAP Analytics Cloud Custom Widget – Par… – SAP Community
The above blog depicts my journey as a beginner learning and developing custom widgets, along with some insights gained along the way. I hope this blog proves to be helpful to you.
This sample package is for learning and communication only, not for production use. It is critical that you check and thoroughly read the licenses of any third-party libraries that may be used in it before using it. By using the examples in this repository, you confirm that you understand and agree to abide by all the terms and conditions set forth in those licenses. Please use this resource pack responsibly and any use of this resource pack will be at your own risk.
Within the story of SAP Analytics Cloud, different visualizations are needed for different scenarios. SAP Analytics Cloud offers a wide range of charts and widgets to help users with data visualization, but some are not perfectly suited to the needs of a wide variety of practical scenarios. The custom widget framework for SAP Analytics Cloud allows to add your own custom widgets that provide a specific visualization of user. At this point, customers can customize their widgets by uploading custom widgets and use them in stories.Based on the demo of the custom widget in the Help Portal, I developed a tree custom widget. This blog focuses on the process and references I use to implement a custom widget from scratch, as well as sharing practical experience during development.Click here for the demo video.This blog will elucidate the process of implementing custom widgets, detailing how to upload and utilize them in SAP Analytics Cloud, and will be organized into four main sections for a comprehensive overview. The outline of the blog is as follows: Introduction to Custom Widgets Custom Widget Development Process index.json main.js styling.js How to Upload Custom Widgets in SAP Analytics Cloud ？ Summary 1. Introduction to Custom Widgets The SAP Analytics Cloud Custom Widget framework allows you to use your own custom widgets to extend the predefined set of widgets available in optimized stories. This can be useful, for example, if you need specific user interface elements, specific data visualizations, or specific features that aren’t available with a predefined set of widgets. Custom widgets can be seamlessly integrated into optimized stories for SAP Analytics Cloud. Like predefined widgets, custom widgets offer the following features: It is listed in the widget menu list from where you can add it to the canvas. It can be moved and resized on the canvas. It appears in the widget outline. It can contribute script methods to the analytics designer script language. It can provide areas in analytics designer where you can set property values of the custom widget at design time (Styling Panel and Builder Panel). The source file of a custom widget consists of two types of files: a JSON file and resource files (JavaScript files). JSON File JSON file contains metadata in widgets, URL references to resource files, and so on. Resource Files main.js (the actual custom widget) styling.js (the Styling Panel of custom widget) builder.js (the Builder Panel of custom widget) Each of these JavaScript files is a web component. Make your own custom widget to start with the files above. 2. Custom Widget Development Process In the tree custom widget I developed, mainly contains the three files “index.json”, “main.js”, “styling.js”. Index.json The following properties must be included in the JSON file of a custom widget: id version name newInstancePrefix webcomponents properties methods events dataBindings Here you have to guarantee the uniqueness of the id, which is your custom widget’s unique ID. When you upload a custom widget that already exists, the system will remind you that if you proceed with the upload, it will overwrite the previously existing custom widget with the same id. A web component object specifies a custom widget within a web component. For each web component object, three properties are necessary: “kind”, “tag”, and “url”. Kind can only be one of “main,” “styling,” or “builder,” and the url is the relative position of the JavaScript file corresponding to the web component. Note: The tag is the unique identifier of the custom element of the web component whose name must contain at least one hyphen (-) to distinguish a custom element from a regular HTML element. And the tag must match the definition in the JavaScript file, or else the system will not be able to find the corresponding JavaScript file and will prompt the following error. Inside my custom widget, only the two types “main” and “styling” are used. If you also want to customize the content of the builder panel, you also need to add a web component of type “builder”. The properties object contains some properties of a custom widget and their default values. Each property name in the properties object must correspond to the property name of the custom widget. For example, in the properties, you can define properties of the custom widget such as width, height, node color, font size, etc., which can be used in the JavaScript file. The values of the properties can be modified through the styling panel and then passed to the main component for re-rendering, thereby changing the style of the custom widget. The Methods object specifies the script methods included in a custom widget, including property setting methods. Each property name in the Methods object corresponds to a script method name in the custom widget. For example, in my widget, the setNodeFontSize method is defined to set the font size of a node. This method is used in main.js, and whenever the value of the nodeFontSize property changes, the function will retrieve the new value and update the corresponding font size in the component. By defining dataBindings in JSON file, you can access data from the model within a custom widget. The data returned by dataBindings mainly consists of two parts: data: This is an array containing all the returned data. Each object in the array represents a piece of data (the value of a measure corresponding to one or several “dimensions”). metadata: Metadata contains attribute information about some “measures” and “dimensions” present in the data. The format of the data returned by dataBindings may not necessarily match the format required by the custom widget. You can reorganize the structure of the data based on the data format requirements of a Echarts chart. For more information on using dataBindings, please click here . Examples of data returned by dataBindings are as follows. For a more detailed description and usage of the individual valid attributes in the JSON file, see the documentation on the Help Portal . main.js In the main.js file lies the core part of my custom widget. As I aimed to create a tree structure, I referenced the tree component in the Echarts library for display. After obtaining data through dataBindings, I wrote a function to transform the data structure into a tree structure. Having the correct data structure is the most crucial step for the successful display of the component. Once the data is correctly integrated into the Echarts tree component, a basic tree display structure can be obtained, which can then be optimized and adjusted according to individual needs. For instance, in my custom widget, I wanted the tree structure to support different orientations. This led to the issue of adjusting the direction of each node’s label. Therefore, I needed to consider every distribution scenario of the tree structure and set the direction of label display accordingly. For a tree distributed from left to right, the labels of leaf nodes are displayed to the right of the node, while labels of other nodes are displayed to the left. In a tree distributed from top to bottom, the labels of leaf nodes are shown below the node, while labels of other nodes are displayed above. Similar adjustments apply to other distribution scenarios. By default, my node labels display the node name and its corresponding value. In cases where a node has no value, only the node name is displayed. Of course, you can customize the display content according to your requirements. The orthogonal layout effect is as follows: The radial layout effect is as follows: In the diagram below, you can see that the nodes in the tree structure are either hollow or solid. Hollow nodes indicate that the node cannot be further expanded, while solid nodes indicate that clicking on the node can expand its child nodes. When a threshold is set in the style settings panel, nodes in the tree diagram with values exceeding the threshold will be highlighted in red. This helps us effectively display which nodes in different hierarchical structures exceed the threshold. (Note: In my code, the default threshold value is set to 1,000,000,000. If you wish to modify this default value, you can edit the default value at line 233 in the sample code main.js, and also at line 79 in index.json.) A threshold value of 50,000,000 is set in the styling panel, and the nodes in the tree chart with values over 50,000,000 are highlighted in red. I chose to show the node name, value, and unit information inside the tooltip. If you want to customize the tooltip format, you can modify this part of main.js. Here need to point out that currently this version of the tree widget only implements a version that supports one measure, and if you want to implement a tree that supports multiple measures, you can add multiple series to your code to present the values of multiple measures. styling.js The content in the styling.js file controls the module for additional properties of the custom widget in the style settings panel. In my custom widget, I aim to modify some basic properties of the tree component, change layout settings, and highlight nodes exceeding a threshold. Therefore, my style panel settings are as shown in the diagram below. Layout settings are divided into two types: orthogonal layout and radial layout. The orthogonal layout allows for setting the distribution direction as “L-R,” “R-L,” “T-B,” and “B-T.” It is important to note that only the orthogonal layout requires setting the direction and edge type. When selecting the radial layout, these two properties are not needed. To avoid unnecessary errors, I have set the selectors for direction and edge type to be hidden by default when the radial layout option is selected. Regarding node color settings, the current version of this custom widget only supports manually entering some color names in English or hexadecimal and RGB color values, such as “dark blue,” “#00FF00,” “RGB(0,0,255),” etc. If you wish to further enhance this feature, you can consider integrating a color picker plugin. 3. How to Upload Custom Widgets in SAP Analytics Cloud You can upload and host these resource files in SAP Analytics Cloud to use custom widgets in a story. You need to upload the JSON file of the custom widget along with the corresponding resource files to SAP Analytics Cloud. Navigate to the story page, click on the custom widget, and select the add icon to upload the JSON file and its associated resource files separately. Note: When uploading resource files, make sure to compress them into a .zip file format and ensure that the .zip file is smaller than 10MB. In the story, add the custom widget by finding the widget you uploaded and inserting it into the story. Open the builder panel, select your model, and add “Measures” and “Dimensions.” Note: The dimensions you add must have a hierarchical structure. When setting up different hierarchical structures, make sure to check “Include Parent Node Elements” to correctly display the tree structure. In the styling panel, you can modify and apply its properties in the Custom Widget Additional Properties module. The properties that can be modified in the styling panel are determined by your definitions in the styling.js resource file. In a tree custom widget, the styling panel can change the style of a tree, such as root node name, layout settings, direction settings, connection edge types, node types, and so on.4. Summary The above is the complete process of developing a tree custom widget, which can be applied to various data visualization and analysis scenarios with hierarchical structures. For example, it can be used in: Organizational structure display in human resources: Show the hierarchical relationships among departments and positions within a company through a tree structure, clarify employee responsibilities, and assist management in optimizing human resource allocation and adjusting organizational structures. BOM display in production scenarios: Utilize a tree structure to display the bill of materials (BOM) of products and their hierarchical relationships, supporting production planning and material management to help companies control costs and improve production efficiency. Display of account hierarchy structure in financial statements: Use a tree structure to display detailed information on the general ledger, sub-accounts, various expenses, and income levels, helping financial personnel and management analyze financial conditions more intuitively and identify potential issues. Sales performance display for different regions, departments, or product lines: Use a tree structure to display sales performance from global revenue down to sales performance at the continent, country, and regional levels, helping companies identify which regions or product lines contribute the most, or discover sales bottlenecks. In the first version, there are still many incomplete aspects. If this tree diagram is helpful for you, you can download the source code for reference and make modifications and adjustments based on it. During the implementation of the custom widget, I found some very helpful blogs. If you are interested in creating your own custom widget, you can refer to them: Use Custom Widgets (Optimized) | SAP Help PortalCustom Widgets | SAP Help PortalSAP Analytics Cloud: Custom Widget Hands-on Guide – SAP CommunitySAP Analytics Cloud: Custom Widget & Widget Add-On… – SAP CommunityYour first SAP Analytics Cloud Custom Widget – Int… – SAP CommunityYour first SAP Analytics Cloud Custom Widget – Par… – SAP CommunityYour first SAP Analytics Cloud Custom Widget – Par… – SAP CommunityYour first SAP Analytics Cloud Custom Widget – Par… – SAP CommunityYour first SAP Analytics Cloud Custom Widget – Par… – SAP CommunityYour first SAP Analytics Cloud Custom Widget – Par… – SAP CommunityThe above blog depicts my journey as a beginner learning and developing custom widgets, along with some insights gained along the way. I hope this blog proves to be helpful to you. This sample package is for learning and communication only, not for production use. It is critical that you check and thoroughly read the licenses of any third-party libraries that may be used in it before using it. By using the examples in this repository, you confirm that you understand and agree to abide by all the terms and conditions set forth in those licenses. Please use this resource pack responsibly and any use of this resource pack will be at your own risk. Read More Technology Blogs by SAP articles
#SAP
#SAPTechnologyblog
