Build a Custom Widget in SAP Analytics Cloud, Analytics Application

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 16×16 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 :

https://example.demo/customwidgets

Create a Custom Widget

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.json
  Custom Widget JSON of Gauge Box.
• 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 16×16 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).

(function() { 
	let template = document.createElement("template");
	template.innerHTML = `
		<style>
		:host {
			border-radius: 10px;
			border-width: 2px;
			border-color: black;
			border-style: solid;
			display: block;
		} 

		body {
		  background: #fff;
		}
		
		.metric {
		  padding: 10%;
		}
		
		.metric svg {
		  max-width: 100%;
		}
		
		.metric path {
		  stroke-width: 75;
		  stroke: #ecf0f1;
		  fill: none;
		}
		
		.metric text {
		  font-family: "Lato", "Helvetica Neue", Helvetica, Arial, sans-serif;
		}
		
		.metric.participation path.data-arc {
		  stroke: #27ae60;
		}
		
		.metric.participation text {
		  fill: #27ae60;
		}		
		</style>
		
		<div class="container">
		  <div class="row">
		    <div class="col-md-4 col-sm-4">
		      <div class="metric participation" data-ratio=".95">
		        <svg viewBox="0 0 1000 500">
			        <path d="M 950 500 A 450 450 0 0 0 50 500"></path>
					<text class='percentage' text-anchor="middle" alignment-baseline="middle" x="500" y="300" font-size="140" font-weight="bold">0%</text>
					<text class='title' text-anchor="middle" alignment-baseline="middle" x="500" y="450" font-size="90" font-weight="normal"></text>
  	            </svg>
		      </div>
		    </div>
		  </div>
		</div>
	`;

	class Box extends HTMLElement {
		constructor() {
			super(); 
			let shadowRoot = this.attachShadow({mode: "open"});
			shadowRoot.appendChild(template.content.cloneNode(true));
			
			this.$style = shadowRoot.querySelector('style');			
			this.$svg = shadowRoot.querySelector('svg');
			
			this.addEventListener("click", event => {
				var event = new Event("onClick");
				this.dispatchEvent(event);
			});
			
			this._props = {};
		}
		
		render(val, info, color) {
			var val1 = val * 0.01;
			var x = this.svg_circle_arc_path(500, 500, 450, -90, val1 * 180.0 - 90);
			var rounded = Math.round( val * 10 ) / 10;

			
			if(rounded >=0 && rounded <=100) {
				this.$style.innerHTML = ':host {border-radius: 10px;border-width: 2px;border-color: black;border-style: solid;display: block;}.body {background: #fff;}.metric {padding: 10%;}.metric svg {max-width: 100%;}.metric path {stroke-width: 75;stroke: #ecf0f1;fill: none;}.metric text {font-family: "Lato", "Helvetica Neue", Helvetica, Arial, sans-serif;}.metric.participation path.data-arc {stroke: ' + color + ';}.metric.participation text {fill: ' + color + ';}';
				this.$svg.innerHTML = '<path d="M 950 500 A 450 450 0 0 0 50 500"></path><text class="percentage" text-anchor="middle" alignment-baseline="middle" x="500" y="300" font-size="140" font-weight="bold">' + rounded + '%</text><text class="title" text-anchor="middle" alignment-baseline="middle" x="500" y="450" font-size="90" font-weight="normal">' + info + '</text><path d="' + x + '" class="data-arc"></path>"';
			}
		}
		  
		polar_to_cartesian(cx, cy, radius, angle) {
		    var radians;
		    radians = (angle - 90) * Math.PI / 180.0;
		    return [Math.round((cx + radius * Math.cos(radians)) * 100) / 100, Math.round((cy + radius * Math.sin(radians)) * 100) / 100];
		}
		
		svg_circle_arc_path(x, y, radius, start_angle, end_angle) {
		    var end_xy, start_xy;
		    start_xy = this.polar_to_cartesian(x, y, radius, end_angle);
		    end_xy = this.polar_to_cartesian(x, y, radius, start_angle);
		    return "M " + start_xy[0] + " " + start_xy[1] + " A " + radius + " " + radius + " 0 0 0 " + end_xy[0] + " " + end_xy[1];
		  };
		  

		onCustomWidgetBeforeUpdate(changedProperties) {
			this._props = { ...this._props, ...changedProperties };
		}

		onCustomWidgetAfterUpdate(changedProperties) {
			if ("value" in changedProperties) {
				this.$value = changedProperties["value"];
			}
			
			if ("info" in changedProperties) {
				this.$info = changedProperties["info"];
			}
			
			if ("color" in changedProperties) {
				this.$color = changedProperties["color"];
			}
			
			this.render(this.$value, this.$info, this.$color);
		}
	}	
	customElements.define("com-demo-gauge", Box);
})();

2.1 Template Object

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

(function()  {
	let template = document.createElement("template");
	template.innerHTML = `
		<form id="form">
			<fieldset>
				<legend>Color Properties</legend>
				<table>
					<tr>
						<td>Color</td>
						<td><input id="sps_color" type="text" size="40" maxlength="40"></td>
					</tr>
				</table>
				<input type="submit" style="display:none;">
			</fieldset>
		</form>
	`;

	class BoxSps extends HTMLElement {
		constructor() {
			super();
			this._shadowRoot = this.attachShadow({mode: "open"});
			this._shadowRoot.appendChild(template.content.cloneNode(true));
			this._shadowRoot.getElementById("form").addEventListener("submit", this._submit.bind(this));
		}

		_submit(e) {
			e.preventDefault();
			this.dispatchEvent(new CustomEvent("propertiesChanged", {
					detail: {
						properties: {
							color: this.color
						}
					}
			}));
		}

		set color(newColor) {
			this._shadowRoot.getElementById("sps_color").value = newColor;
		}

		get color() {
			return this._shadowRoot.getElementById("sps_color").value;
		}
	}

customElements.define("com-demo-box-sps", BoxSps);

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

(function()  {
	let template = document.createElement("template");
	template.innerHTML = `
		<form id="form">
			<fieldset>
				<legend>Color Properties</legend>
				<table>
					<tr>
						<td>Color</td>
						<td><input id="bps_color" type="text" size="10" maxlength="10"></td>
					</tr>
				</table>
				<input type="submit" style="display:none;">
			</fieldset>
		</form>
		<style>
		:host {
			display: block;
			padding: 1em 1em 1em 1em;
		}
		</style>
	`;

	class BoxBps extends HTMLElement {
		constructor() {
			super();
			this._shadowRoot = this.attachShadow({mode: "open"});
			this._shadowRoot.appendChild(template.content.cloneNode(true));
			this._shadowRoot.getElementById("form").addEventListener("submit", this._submit.bind(this));
		}

		_submit(e) {
			e.preventDefault();
			this.dispatchEvent(new CustomEvent("propertiesChanged", {
					detail: {
						properties: {
							color: this.color
						}
					}
			}));
		}

		set color(newColor) {
			this._shadowRoot.getElementById("bps_color").value = newColor;
		}

		get color() {
			return this._shadowRoot.getElementById("bps_color").value;
		}
	}

	customElements.define("com-demo-box-bps", BoxBps);
})();

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.

ScriptVariable_1 = ScriptVariable_1 + 1;
ScriptVariable_2 = ScriptVariable_2 - 1;

//Set value
Gauge_1.setValue(ScriptVariable_1, "Plus Gauge 1", "#e74c3c");
Gauge_2.setValue(ScriptVariable_2, "Plus Gauge 2", "#3498db");

//Get percentage value
console.log(Gauge_1.getValue());

See it in action:

Here is another demo of Google Gauge widget:

Chill the Lion:

Integration between amCharts and SAC:

Another integration with amChart and SAC:

Highcharts 3D Cylinder:

Google Map widget:

YouTube Player widget:

Multiple Instances of Google Gauges widget:

Another version of Google Map widget:

Singapore map widget:

Clock widget:

Geo Chart widget:

Rotate Globe widget:

Another Rotate Globe widget:

Liquid Fill Gauge widget:

QR code generator widget:

Word Cloud widget:

Solid Gauge widget:

Amchart Gauge widget:

Heat map widget:

Compass widget:

Text widget:

Linear Gauge widget:

Three.js custom widget:

3D object widget (with mouse controls):

 

3D scatter widget:

Bubble chart widget:

Barcode generator widget:

Pie Chart widget:

Day & Night World Map widget:

amCharts Serpentine timeline:

Column with Rotated Series from amCharts:

Stadium track chart from amCharts:

Radar Timeline chart from amCharts:

Dragging Pie Slices from amCharts:

Pictorial Chart from amCharts:

Radial Bar Chart with Highcharts:

Surface Chart with Anychart:

Seat Map Chart with Anychart:

Connector Map with Anychart:

Gauge with FusionCharts:

Cylinder Fill Chart with FusionCharts:

Gantt Chart with FusionCharts:

Map chart with FusionCharts:

Gauges with FusionCharts:

Google Poly:

Org chart with FusionCharts:

Radar (Spider) custom widget with FusionCharts:

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:

Grouped Location Chart with ZoomCharts:

Another custom widget with ZoomCharts:

Google Translate Custom Widget:

Currency conversion custom widget with Google Finance:

Display stock price information from Google Sheets function “=GOOGLEFINANCE(“NYSE:BABA”,“price”,TODAY()–180,TODAY())”

Currency exchange trends:

Object detection with TensorFlow JS:

 

Tracking Coronavirus COVID-19 with Here:

Novel Coronavirus (COVID-19) Infection Map:

3D map with wrld3d.com:

Real-time temperature monitoring with WhatsApp notification:

SAPUI5 Date Picker Custom Widgets:

SAPUI5 KPI Tile Custom Widget:

SAP ChatBot Custom Widget with SAP Conversational AI:

SAPUI5 sap.suite.ui.commons.networkgraph.Graph:

SAC Visual Tree Mapper:

SAC Widget to Send and Receive Messages with RabbitMQ:

SAC Widget to Send and Receive Messages with Kafka:

Generic Tile Custom Widget:

Launch Zoom Meeting from Analytic App:

Custom Chat Bot Widget:

Covid-19 Widget:

Real Time Notification Custom Widget:

Zoom Meeting:

More Tutorials Related to SAC Custom Widget

• Adding LED Display as an Threshold Indicator in SAP Analytics Cloud
• Display Stock Price with SAP Analytics Cloud Custom Widget and Google Sheets
• SAP Analytics Cloud Barcode Scanner Custom Widget
• Add and Use SAPUI5 Elements in SAP Analytics Cloud Custom Widget
• How to Build a Chatbot for SAP Analytics Cloud with SAP Conversational AI
• Execute Stored Procedure from SAP Analytics Cloud with NodeJS App
• SAP Analytics Cloud REST API Custom Widget
• SAP Analytics Cloud Custom Widget REST API with OAuth 2.0 and SAP HANA XSA
• SAP Analytics Cloud MultiInput Custom Widget
• Excel File Upload From SAP Analytics Cloud Analytic Application
• Populate Master Data in SAC Planning Model from an Excel File Upload with Analytic Application
• Protect SAP Analytics Cloud Analytic Application Code from Illegal Copy
• Network Graph Visualization in SAP Analytics Cloud Analytic App
• Build SAP Analytics Cloud QR Code Generator Custom Widget
• SAP Analytics Cloud Custom Widget to Send and Receive Messages with RabbitMQ
• SAP Analytics Cloud Custom Widget to Send and Receive Messages with Kafka
• Create Generic Tiles in SAP Analytics Cloud Analytic App
• Displaying a PDF File in SAP Analytics Cloud, Analytic App with Custom Widget
• Add Zoom Meeting Custom Widget in SAP Analytics Cloud, Analytic Application
• Build a Chat Bot Interface Custom Widget in SAP Analytics Cloud
• SAP Analytics Cloud Real Time Notification List Custom Widget
• SAP Analytics Cloud Zoom Meeting Custom Widget
• SAP Analytics Cloud, Analytics Application Slideshow Controller
• Interface SAP Analytics Cloud Google Gauge Custom Widget with RGB LED
• Control SAP Analytics Cloud, Analytics Designer App Remotely with Mobile Phone
• Build SAP Analytics Cloud QR Code Generator Custom Widget

Reference

SAP Analytics Cloud Custom Widget Developer Guide

SAC Custom Widget Facebook Page