Your first SAP Analytics Cloud Custom Widget – Part 5

[david_stocker]

This is part of a tutorial series on developing your first custom widget.  The landing post for the series can be found here.

This is part 5 and the conclusion of the Your first SAP Analytics Cloud Custom Widget tutorial series. As with the earlier instalments, the final results are on GitHub, for your perusal. If you have not been following since the beginning, I suggest going back to the introduction post and start from the beginning. Last time, we added some script APIs, for use in applications. This time, we’ll have a look at events.

Before we get too far, we need to distinguish between browser and scripting framework events, as custom widgets participate in both.

Scripting Events – These are the “events” that designers can work with when building applications. You can define whatever events that you want and trigger them at will. They are there so that you can give designers a chance to react to whatever it is that you want them to be able to react to. These run within the SAP Analytics Cloud scripting framework.

Browser Events – (HTML DOM events to be specific) these are events that happen in your browser’s JavaScript engine, in reaction to things that happen in the browser. If a user clicks somewhere, drags something, mouses over something, etc. Within your web component, you can react to these just as if you were writing any normal web page. Browser events are not available to the scripting framework, so a user click won’t translate into a scripting event; unless you want it to be so.

In this exercise, we will create an onClick scripting event for the designer and make it react to the browser’s click event. To do this, we will do three things:

• We will define a scripting event, called onClick.


• We will update the main web component to react to the browser click event.


• When we are reacting to the browser click event in the web component, we will trigger the scripting framework onClick event that we just defined.

Note that SAP Analytics Cloud usually uses the term onSelect. We are calling it onClick to show that it really is being created by us and is not inherited from SAP Analytics Cloud defaults.

As usual, we’ll start by making minor edits to the metadata and the web components to ensure that the version and tag id of the widget is unique, as far as SAP Analytics Cloud is concerned. Please increment the numeric suffixes of name, id, and newInstancePrefix. Inside the webcomponents element, increment the the tag element, so that it reads com-sap-sample-helloworld5. Repeat the increment to 5 for the stylesheet web component.

Define the onClick Event in the Metadata

Each child object of events defines a script event. As with properties, the name of the object is the name of the event. There is only one (optional) property; description. Let’s call our event onClick and give it a description.

"events": {

    "onClick": {

        "description": "Called when the user clicks the Gauge"

    }

}

 

That’s it. This is all we need to do in the metadata .json file.

 

Updating the Web Component

We are going to make a change to the constructor() method, because we want this new addition to run when the widget is first created.

• We will add an event listener to the main web component object, to listen for the browser “click” event.


• Well attach an anonymous function to this event.


• We’ll create an SAP Analytics Cloud widget SDK framework Event object, referring to the onClick event that we created in the metadata.


• We will dispatch this event over the SDK framework, so that the scripting event is fired.

constructor() {

    super(); 

    this._shadowRoot = this.attachShadow({mode: "open"});

    this._shadowRoot.appendChild(tmpl.content.cloneNode(true));

    this._firstConnection = false;

    this._tagContainer;

    this._tagType = "h1";

    this._tagText = "Hello World";

}



//Fired when the widget is added to the html DOM of the page

connectedCallback(){

    this._firstConnection = true;

    this.redraw(); 

}

That’s it! Go ahead and host the new JavaScript file. You are done working in the web component part of creating an event. Edit the web component url in the widget metadata to match the web component that you uploaded and install the widget.  As usual, there is a finished version of this step on GetHub.

Testing the Widget

Add a new HelloWorld5 widget. If you compare a HelloWorld5 widget with a HelloWorld4 (or earlier) widget, you will see that the five has a, onClick script event and the rest don’t.



 

Let’s add a script that will fire when a user clicks on the HelloWorld5 widget. Let’s cycle through the header tag options with each click.

• Last time, we created a getH() method, which returns the current header tag. We did not use it then, but we will use it now. Use getH() to get the current header tag.


• If the old header tag is “h1”, set it to “h2”


• Else if the old header tag is “h2”, set it to “h3”


• If the old header tag is not “h1” or “h2”, then it is “h3”. In this case, set it to “h1” to restart the cycle.

var oldH = this.getH();

if (oldH === "h1"){

	this.setH2();

} else if (oldH === "h2"){

	this.setH3();

} else {

	this.setH1();

}

 

Now you are ready to test it!

 



 

 

You have finished this tutorial and should now understand the basis of widget construction.  Congratulations!  The sky is the limit and remember, if you can do something in the web, you can do it in your own custom SAP Analytics Cloud custom widgets!