This is part of a tutorial series on developing your first custom widget. The landing post for the series can be found
here.
In our previous post, in the series Your first SAP Analytics Cloud Custom Widget, we took a tour of the
template repository project for creating a new widget. Now we are going to turn it into something that can be installed into SAP Analytics Cloud. The widget will do one thing, it will display a static html h1 tag, containing the text, “Hello World”. In each step of this series, you’ll be able to find the completed widget on github.
Here is the project for this step.
We’ll ignore the design panel for now and concentrate only on the “main” web component and the metadata; the minimum required to get a widget up and running.
webcomponent.js
We’re only going to do two things. We are going to update the hardcoded shadow DOM html to show the h1 tag with the Hello World text and we are going to rename the web component tag.
Renaming the tag
In the customElements definition, change the tagname parameter. We’ll call it com-sap-sample-helloworld1
This…
customElements.define('com-sap-sample-template', class WidgetTemplate extends HTMLElement {
Becomes This…
customElements.define('com-sap-sample-helloworld1', class HelloWorld1 extends HTMLElement {
Updating the shadow DOM.
We won’t be using the style element in our widget. We will be using the h1 element.
This…
tmpl.innerHTML = `
<style>
</style>
`;
Becomes This…
tmpl.innerHTML = `
<h1>Hello World</h1>
`;
Updating the Metadata
Let’s update the metadata. We’re going to use
HelloWorld1 as our new instance prefix and
com.sap.sample.helloworld1 as our id (the same as in the web component). In each step of the tutorial series, we’ll index the trailing number in these elements. We can make the version number anything we want, but we’ll say 0.0.1.
"name": "Hello World Step 1",
"description": "The first step in creating a minamilistic KPI tile",
"eula": "",
"vendor": "",
"license": "",
"id": "com.sap.sample.helloworld1",
"newInstancePrefix": "HelloWorld1",
"version": "0.0.1",
"icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAA3NCSVQICAjb4U/gAAAAb1BMVEX///+ZmZl4dXdBPj9hYGGOjpE6ODo8OjwvLC0lISIpJSaMiooyLzH/cjMxLi9GREb/ZSk2MzV9fX1MSks4NjcrJyn/WR9ycnJRT1AtKiv/TRVdXF1ra2v7VCfJyMk+PD6tra+rqqtUUlU0MTNqaGpjxDg2AAAAAXRSTlMAQObYZgAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAKhJREFUGNM9z9EagiAMBeDpEGkWNAGhqFTq/Z8xwK/+q7PtZgeg6npEMcBPJ0d1Kmg6ZnFGRZcLESnR7tpoouuVSCPPZYHWee+XxTsrvQeYQrwV97tL5uZigMeoqucTUSnWEVBX4fWaW2BYz1W3bXsLDPldcD8MoYZ3glmMjNbGLJk5igDgnLTGHazdAPo1Gdms2bZXhRmbMuNR5rNWJuX075sMYg57jV94IQ2Xqt1atQAAAABJRU5ErkJggg==",
The web component element
Let’s add an entry in the web component element. As it is a list, each entry is an object, enclosed in brackets. Let’s go through each of the five properties. We’ll handle url separately from the other properties.
"webcomponents": [
{
"kind": "main",
"tag": "com-sap-sample-helloworld1",
"url": "https://davidhstocker.github.io/SAC_CustomWidget_HelloWorld_1/webcomponent.js",
"integrity": "",
"ignoreIntegrity" : true
}
],
Properties not named url
- kind – Since this is the widget in the main canvas, we’ll use “main”
- tag – Should be whatever you defined in the customElements definition in your .js file, so that SAP Analytics Cloud can find the correct customElements definition. In this case, it is com-sap-sample-helloworld1. Again, we’ll be indexing this in each step.
- integrity – This is a SHA256-hash for the .js file. This is to ensure subresource integrity and protect your users by ensuring that the .js files have not been altered in any way by a malicious attacker. In a productive deployment, you’ll want to generate a new integrity hash on each deployment of a JavaScript file to its host location. During development, you’ll frequently be changing the JavaScript files and won’t want to bother with the subresource integrity check, so we’ll be leaving this blank.
- ignoreIntegrity – This tells SAP Analytics Cloud whether or not to use subresource integrity. We’ll set this to false for now. This is not recommended in a productive environment. If it is set to false, the administrator who installs the widget will get a security warning.
A word on the
id and
tag. Note that we try to keep them using the same pattern. This is not mandatory but may help you manage your widget and we recommend it as a best practice
The url property
In this property, you are telling SAP Analytics cloud where the user’s browser needs to get the actual webcomponent JavaScript from. This will be hosted somewhere. Normally, you’d host it as static content on a web server. You have many options on where to host:
- You might want to host it on your favorite cloud hosting provider. AWS and Azure both have easy options for setting up such static hosting.
- In the example, you’ll notice that it points to a github url. This makes use of github pages, a quick and dirty option for low traffic web content. You toggle an option in your project setting and then whenever you check in changes to your project, they are automatically hosted. This is very convenient for development, testing, POCs, etc. We use it in this project. Bear in mind that this is not for high volume use.
- Local hosting. Suppose you want to keep your hosting inside your firewall and not expose it to the outside world. In this case, you can run a webserver on your landscape and host it there. Node.js with the http-server plugin makes an excellent static content server. You can server it up with a single command.
Once you have your JavaScript hosted, you can enter the url into this property. Now you are ready to load your first widget.
Note that you can overwrite and update widget metadata!
Next time, we'll add properties and make our widget configurable.