Build a Custom Widget in SAP Analytics Cloud, Anal...
Technology Blogs by Members
Explore a vibrant mix of technical expertise, industry insights, and tech buzz in member blogs covering SAP products, technology, and events. Get in the mix!
In this tutorial, we will build a simple custom widget in SAP Analytics Cloud, Analytics Application to show the gauge chart as shown below.
A custom widgets are implemented as Web Components. The Web Components are made of HTML, CSS and JavaScript.
Custom Widgets
Custom widget consists of the following files:
Custom Widget JSON
The custom widget JSON file specifies the custom widget properties like id, version, name, description and so on.
Web Component JavaScript A custom widget is composed of one or more Web Components.
Each Web Component is implemented in a Web Component JavaScript file, which defines and registers a custom element and implements the custom element’s JavaScript API. It has the lifecyles: constructor(), onCustomWidgetBeforeUpdate(), onCustomWidgetAfterUpdate(), connectedCallback().
Web Component JavaScript of Styling Panel (optional) The Styling Panel of a custom widget is an area in analytics designer where you can set property values of the custom widget at design time. It is implemented as a Web Component.
Web Component JavaScript of Builder Panel (optional) The Builder Panel of a custom widget is an area in analytics designer where you can set property values of the custom widget at design time. It is implemented as a Web Component.
Icon file
Any icon file image in 16x16 pixels.
Prerequisites
You need a web server that hosts the resources of the custom widget files (JavaScript files, CSS files, images, and so on). Assume that your web server address is :
The Gauge Box custom widget consist of three Web Components: the actual Gauge Box, the Styling Panel and the Builder Panel of the Gauge Box and it consist the following files:
box.js
Web Component JavaScript file of the Gauge Box.
box_sps.js
Web Component JavaScript file of the Styling Panel of the Gauge Box.
box_bps.js Web Component JavaScript file of the Builder Panel of the Gauge Box.
icon.png
Icon of the Gauge Box in any 16x16 pixel icon.
1. Custom Widget JSON of Gauge Box (box.json)
The Gauge Box custom widget has the unique ID, version, and the name, which is displayed in the analytics designer, Styling Panel.
The Gauge Box custom widget is composed of the following three Web Components:
The first Web Component is the actual Gauge Box as indicated by the kind of "main". The second Web Component is the Styling Panel of the Gauge Box as indicated by the kind of "styling". The third Web Component is the Builder Panel of the Gauge Box as indicated by the kind of "builder".
Moving on, these are the properties of the Gauge Box custom widget: value, info, color, width and height.
The property value represents the value in percentage of the Gauge Box. The property info represents the title of the Gauge Box. The property color represents the color of the Gauge Box. And the properties width and height represent the initial width and height of the custom widget.
And then the script methods of the Gauge Box are defined:
The function setValue takes three parameters, newValue, newInfo and newColor. The body property contains the script code which sets the passed all the parameters to the respective Gauge Box's properties.
Function getValue takes no parameter and returns the percentage value of the Gauge Box.
Finally, an onClick event is defined:
Note that the event has no parameters.
2. Web Components JavaScript (box.js)
This section shows the Web Component JavaScript of the Gauge Box (box.js).
The following code creates a template HTML element:
The template element represents the gauge chart.
2.2 JavaSript API of the Custom Element
Constructor The first function in the JavaScript API is the constructor.
The super() function is called, then the shadow DOM root element is created. The copy of the template element is added as a child element to the shadow DOM root element. An element style and svg is selected by using querySelector where shadowRoot is a reference to the document fragment. Finally, an event listener is attached to the custom element, listening for click events. Lastly, to make managing the properties of the Web Component easier, an empty _props object is initialized.
Handling Custom Widget Updates
In the onCustomWidgetBeforeUpdate() function, the properties in the changedProperties are merged with the properties of the _props object. The _props contains the state of all Gauge Box properties before the Gauge Box is updated.
In the onCustomWidgetAfterUpdate() function, the properties in the passed changedProperties object is used to directly set the gauge value, info(text information) and color of Gauge Box.
And finally call the render() function to update the chart.
3. Web Components JavaScript of the Styling Panel (box_sps.js)
The Styling Panel lets you change the background color of the Gauge chart in analytics designer.
This following code shows the Web Component JavaScript of the Styling Panel (box_sps.js).
The Web Component JavaScript defines a new custom element com-demo-box-sps. The JavaScript API of the new custom element is implemented in the BoxSps class which extends the JavaScript API of the HTMLElement class.
3.1 Template Object
The following code creates a template HTML element:
This template HTML element is a template for the shadow DOM HTML element that represents the HTML DOM of the Styling Panel of the Gauge Box.
3.2 JavaSript API of the Custom Element
Constructor The first function in the JavaScript API is the constructor.
The super() function is called, then the shadow DOM root element is created. The copy of the template element is added as a child element to the shadow DOM root element.
Finally, an event listener is attached to form, listening for submit events. If one such event occurs, the event handler function _submit() is called. Calling bind() and passing this to _submit() ensures that in _submit() the keyword this references the custom element.The submit() function is implemented as follows:
The _submit() function calls function preventDefault() on the passed event object, which prevents submitting the form to the server.
Then, a custom event propertiesChanged is created, indicates a change of properties to the Custom Widget SDK framework. This custom event contains a JSON payload which is the color property of the custom widget.
Getters and Setters Property The following code shows the implementation of color setter and getter functions.
The color setter function places a text representation of the new color into the input field of the Gauge Box’s Styling Panel.
The color getter function returns the text of the input field (color value) of the Gauge Box’s Styling Panel.
4. Web Components JavaScript of the Builder Panel (box_bps.js)
This Builder Panel lets you change the text color of the Gauge Box in analytics designer.
The code is very similar to the Web Components JavaScript of the Styling Panel. The following code shows the Web Component JavaScript of the Builder Panel (box_bps.js).
The Web Component JavaScript defines a new custom element com-demo-box-bps. The JavaScript API of the new custom element is implemented in the BoxSps class which extends the JavaScript API of the HTMLElement class.
4.1 Template Object
The following code creates a template HTML element:
This template HTML element is a template for the shadow DOM HTML element that represents the HTML DOM of the Builder Panel of the Gauge Box.
4.2 JavaSript API of the Custom Element
Constructor The first function in the JavaScript API is the constructor.
The super() function is called, then the shadow DOM root element is created. The copy of the template element is added as a child element to the shadow DOM root element.
Finally, an event listener is attached to form, listening for submit events. If one such event occurs, the event handler function _submit() is called. Calling bind() and passing this to _submit() ensures that in _submit() the keyword this references the custom element.The submit() function is implemented as follows:
The _submit() function calls function preventDefault() on the passed event object, which prevents submitting the form to the server.
Then, a custom event propertiesChanged is created, indicates a change of properties to the Custom Widget SDK framework. This custom event contains a JSON payload which is the color property of the custom widget.
Getters and Setters Property The following code shows the implementation of color setter and getter functions.
The color setter function places a text representation of the new color into the input field of the Gauge Box’s Builder Panel.
The color getter function returns the text of the input field (color value) of the Gauge Box’s Builder Panel.
Construct All Files Together
Once we have created all the required files, we need to organize in the following structure:
Create a folder called customwidgets and put box.json into that folder.
Create another folder box inside customwidgets folder and put the rest of the files inside box folder.
Upload all files to the web server.
Adding the Custom Widget to Analytics Designer
In the Analytics Designer, navigate to Main Menu > Browse > Custom Widgets. If you don't see this option, check your security roles.
Click the Create toolbar icon.
In the Upload File dialog, click the Select File button.
Select the custom widget JSON file box.json.
Create a new analytic application. The custom widget is listed in the widget list of the dropdown menu of the Add menu.
Using the Custom Widget in Analytics Designer
Once you have added the Gauge custom widget, you can see the following functions.
The below code illustrates who to define the parameters for the setValue function. And how to call the getValue function.
A quick demo video to control the SAP Analytics Cloud Custom Widget with web Bluetooth and micro:bit. User presses the button A and B on micro:bit to fill in and out the cylinder gauge.
Control two Google Gauges widgets with two micro:bits and Web Bluetooth:
Hi Ferry, Is there a way to include additional javascript libraries into our custom widget json so that I can make use of them in my component javascript file. It was mentioned in SDK docs that we can include javascript libraries but the way to include those are not mentioned. Thanks in advance
It is indeed in the planned innovations for 2020 if I recall correctly. I believe David Stocker mentioned this during his custom widget hands on session in teched 19.
but after I upload the custom widget in SAC and add this widget into a new Analytic Application then I get the below error:
"Something went wrong. The system couldn't load the custom widget 'com.demo.gauge_1.x' (kind: 'main') for this reason: The system took too long to define the custom widget.'
Can I ask your help? Can you please tell me what I am doing wrong?
Let me add into this issue, the fact that all JS files and JSON files are accessible in GitHub without authentication (public files).
My guess is that something - some kind of configuration, is missing is SAC side. Do I need some extra step in SAC settings?
You are right. I was missing the customElements.define in the builder file - THANKS!, but even after ignoring the error and if I run the application it still throws the same error (F12 is showing the same errors as in previous post).
I was experiencing the same issue that armando_santos had described.
However, I ran the application and looked at the console log as you suggested and discovered it was an SSL issue: https://d.pr/i/egX16s
After applying a free SSL certificate to my domain, updating the URL in the JSON file, and uploading the new JSON file to my SAP Analytics Cloud tenant ... I am able to use the custom widget for the gauge chart type ? https://cloud.summerlinanalytics.com/2Nurjl10
I hope this helps anyone else who is trying to use the custom widgets!
In your case the error seems to be easier to understand and to fix as well:
"but requested an insecure script 'http://summerlinanalytics.com/customwidgets/gauge/box.js". This request has been blocked; the content must be served over HTTPS."
We can clearly see this is an SSL issue.
But in my example - within JSON file - I am using and HTTPS WEB server:
"https://github.com/armando-j-a-santos/SAPCustomWidget2/blob/master/coloredbox.js"
And after deleting the Widget in SAC, upload the new JSON file to my tenant and use it in SAC application I still get the same issue.
Any suggestion is more than welcome dear Hau/Ferry.
I don't know if it helps or not but in my test application in SAC onInitialization() I have the below code:
var ScriptVariable_1 = 10;
//Set value
Gauge_1.setValue(ScriptVariable_1, "Plus Gauge 1", "#e74c3c");
//Get percentage value
console.log(Gauge_1.getValue());
And I can see the Gauge_1 widget icon (please see attached image), so it means the icon.PNG file is being read from my Web Server GitHub (HTTPS). However I still get the same errors messages as shown in previous posts.
Any suggestion is more than welcome dear Hau/Ferry.
And after deleting the widget in SAC, upload the new JSON file to my tenant and use it in a SAC application I still get the same the error (the same as mention earlier in the beginning of my post):
Thanks a million Charlie for your valuable tip.
This was the setting that I needed. I thought it was something in SAC side but in fact it was in github side.
All your Demos look super cool. The Google Gauge demo is exactly what am looking for. I would be grateful if you can share some further information on how the google library could be integrated into the custom widget web component. Did you skip the shadow dom completely? Also, did you try experimenting with Polymer? What build tools do you use?
You have used the tag "com-demo-gauge-sps" in the JSON file, however in the box_sps.js has the tag defined as "com-demo-box-sps". that is why the error.
Can we use webcomponents built with polymer framework to create custom widget in SAC? If yes, could you please share one simple example?
Or, can we use third party js libraries like JQuery / D3 to create the custom widget? How to include those libraries and how to manipulate DOM elements inside shadow root using Jquery/D3?
Yes you can blend it with the existing JavaScript libraries. Most of the examples I built, I am basing on the existing libraries and not building it from the scratch.
Maybe I will post another blog on how to create a simple WebComponents and blend it with the external JS libraries like Amcharts.com once I have time. To put in this write up alone, it will be very long and messy.
Ping me if you are interested to know more details.
All your demos look amazing. We are really struggling with building custom JS widgets using 3rd party libraries. I would greatly appreciate if you can give some pointers for the below questions:
How did you manage to import external libraries into the web component? Any code snippets or tutorial links would help.
In most of your demos, you were able to consume data from SAC model. Could you please give some hints on how to bind data into a custom widget? As per the SAP documentation, the input data types of the methods and parameters support only 1 dimensional arrays, how can we pass table like data into the custom widget?
Any simple code snippets which shows the above concepts will really help with our POC. Am looking forward for your blog on Amcharts integrations. 🙂
The tutorial works perfect for me. Thank you a lot. I also like the examples you made!
I'm trying you implement 3rd part chart library on the custom widget just like you did, but I have no clue how to embed the chart libraries into the custom widget files. I know you are about to write a blog about it but can you share a sample code please?
is there a way to modify the Gauge box properties inside the box.js? Let's say I'd like to change the color property based on the value of the gauge, is it possible to do it on widget side (box.js) instead of managing it on Analytic Designer side?
Note that I'd like to change the propery in the way that the getter method will give me the new value modified in the box.js.
have u any instructions or step-by-step on how to embed m.components in App with CW? For example, DateTime.Picker or KPI.Tiles (like in your youtube videos)?
Do you have customise trend indicator arrow tutorial for analytics design, maybe? that will show the arrow trend if the value below 3% (or absolute number) the arrow will be red, more than 3% will green and in between will show a deep yellow colour with a horizontal arrow shape. Thanks in advance for any advice!
If using custom widget, we can define all those parameters in the styling or builder panel. I think is easy to achieve it. I don't have that tutorial yet at this moment. I will find some time to write it.
That would be great, Ferry! really appreciate if you can share the techniques. But maybe I describe it clear what I want to achieve.
So I'm goint to build a dashboard and might be use the structure as template structure. I need to build this in analytics designer mode (not story). The source is queries with live-connection. This dashboard have 40+ (numeric chart) KPI's. Build with 6 Panel. On initial the first three panels appears and switch to another panel with radiobutton (this is done). Each Panel contain four KPI's. On init the indicator should read each KPI value and show correspondent arrow trend indicator (this is still homework). Later on I will build dropdown for year, month, week, etc filter.
How I've done so far. I added three different gif images (green, red, yellow) on each KPI's. So, here are 40+ KPI's multiply by three. It's a lot small images placed by the KPI side-by-side. I have two global variable, one to control image, and the other one to control the value. I created global script for expected condition (>3%, below and in between). Still the result not really working as my expectation.
I don't find another solution so far, like using "Form" (circle shape) and controll the colour pallete through script (like ".setColor function). Well the setColor function is not available and furthermore there is only "onClick" event with "shape" instead of something like "onResultChanged".
Appreciate a lot if you can share or have any method to create less-complex trend arrow indicator. Terima kasih!