ROA_general_gerneric_Template.png

Check your email or visit Credly to claim and share this badge

View on Credly

Go to My Home

Congratulations

Certificate_icon.png

By completing this SAP Learning Journey, you are now prepared to book your certification exam.

Congratulations!

Mountain_White_background.png

Creating Custom Widgets for SAP Analytics Cloud Stories

Congratulations Modal

cleanFiles/bookmap_Developing_Custom_Widgets_for_SAP_Analytic_en-US_learning-sap-com_lsc-prod.zip (MMCP-DROPZONE) - 2023-12-11T11:14:35.000Z

Creating a Custom Widget for Use in Stories

<div id="content"><p tabindex="0">Custom widgets are used when story creators need a specific user interface element, a particular visualization of data, or a certain functionality in your analytic application that is not provided by the predefined set of widgets.</p><p tabindex="0">Custom widgets seamlessly integrate into SAP Analytics Cloud. Like any other widget used for a story, a custom widget provides the following capabilities:</p><ul style="list-style-type:disc"><li tabindex="0">It is listed in the widget menu list from where you can add it to the canvas.</li><li tabindex="0">It can be moved and resized on the canvas.</li><li tabindex="0">It appears in the widget outline.</li><li tabindex="0">It can contribute script methods to the javascript language.</li><li tabindex="0">It can provide configuration options in the Styling Panel and Builder Panel.</li></ul></div>

Custom Widget Defined

<div id="content"><p tabindex="0">Custom widgets are technically a simple set of files. The most basic custom widget consists of simply a JSON file and a JavaScript file.</p><p tabindex="0">The JSON file specifies the custom widget and contains specific properties of the custom widget, including references to the JavaScript file that defines it. You can also create a JavaScript file to customize the SAP Analytics Cloud Builder and Styling panes for the widget, but those are optional.</p><p tabindex="0">To create custom widgets, you do not need special software. At the beginning, a simple text editor will do. However, when your custom widgets get more complex, a good JavaScript text editor will make your development efforts easier.</p><p tabindex="0">An SAP Analytics Cloud custom widget is implemented as a Web Component in the HTML Document Object Model (or DOM) of a web page that will not interfere with the rest of the HTML DOM. We achieve this by separating a custom widget’s HTML DOM from the HTML DOM of the web page in a shadow DOM.</p><p tabindex="0">Let's check in with Julie to see how she is designing the custom widget for Dirk. She will refer to the <a href="https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/0ac8c6754ff84605a4372468d002f2bf/75311f67527c41638ceb89af9cd8af3e.html" target="_blank">SAP Analytics Cloud Custom Widget Developer Guide</a>, so you may want to download a copy of it and keep it handy for your custom widget projects.</p><div class="kalturaVideoLessonWrapper"><div id="1_40i88n7s" data-testid="video" class="kalturaVideoLessonContainer"></div></div></div>

Custom Widget Creation

<div id="content"><p tabindex="0">The JSON file defines the custom widget. Juile explains the logic of her JSON file in this video.</p><div class="kalturaVideoLessonWrapper"><div id="1_44ot49m7" data-testid="video" class="kalturaVideoLessonContainer"></div></div></div>

The JSON File Explained

<div id="content"><p tabindex="0">The Javascript files Implement the custom elements of the custom widget. You can define up to three files:</p><ul style="list-style-type:disc"><li tabindex="0"><i>Main</i> file - defines the custom widget</li><li tabindex="0"><i>Styling</i> file - defines the styling pane options for the custom widget</li><li tabindex="0"><i>Builder</i> file - defines the builder pane options for the custom widget</li></ul><p tabindex="0">The <i>Main</i> files is mandatory, but the other two are optional.</p><p tabindex="0">In this video, Julie explains the logic of her <i>Main</i> and <i>Sytling</i> JavaScript files.</p><div class="kalturaVideoLessonWrapper"><div id="1_ep6izsko" data-testid="video" class="kalturaVideoLessonContainer"></div></div></div>

The JavaScript Files Explained

In this video, Julie explains how to create a custom widget using JavaScript in SAP Analytics Cloud. She walks through the process of creating a JSON file and discusses the required properties. Learn different approaches and unleash the possibilities of scripting!<br><br># This description was auto-generated #

Julie Intro2.mp4

I'm Julie. Dirk explained what he needs and showed me the original JavaScript he wrote to create the image that displays the top three countries. But before we get started, I just want to point out that because these custom widgets are created with JavaScript, there is definitely more than one approach to take. In other words, just because I create the custom widget for Dirk one way doesn't mean you must use my methods. The beauty of scripting is that it gives you a lot of possibilities. First, I created a JSON file. One thing to be aware of with the custom widget JSON file is that any properties present in the file besides the required ones, even valid JSON properties, make the file invalid. I won't bore you with a list of these required properties when you can read about them in the SAP Analytics Cloud Custom Widgets Developer's Guide. Instead, let's go through the JSON file that I created for Dirk.

Learn how to create a custom widget in SAP Analytics Cloud. This video tutorial covers the Web Components area, Kind parameter, Properties area, Data Bindings, and more.<br><br># This description was auto-generated #

Julie JSON.mp4

The first few lines are just metadata about the custom widget. The Web Components area, though, specifies what makes up the custom widget. The Kind parameter defines that there are two JavaScript files that will construct the custom widget. The Properties area defines the size and font style of the widget. There are two areas that we will not define, Methods and Events. This is simply because our custom widget doesn't provide any scripting options. Finally, the Data Bindings area feeds the Custom Widget with the top three countries and their values. In just a bit, I will show you how to upload the Custom Widget to an SAP Analytics Cloud tenant. To do that, I need this forward slash in the URL property for the JavaScript files.

This video explores JavaScript files referenced by the kind properties and demonstrates how to create a custom widget that displays top values and their names. Learn about encapsulation, rendering, and more.<br><br># This description was auto-generated #

Julie JavaScript.mp4

Now that we've talked about the JSON file, let's look at the JavaScript files referenced by the Kind properties. Again, I won't bore you by explaining the JavaScript commands, but I want to make sure you understand the logic of the script. In general, this main script defines a custom widget that displays a podium with three top values and their corresponding names. When the widget's data is updated, it automatically sorts the data and displays the top three entries. First, a self-invoking function wraps the entire code. This ensures that the code runs immediately after it's defined, and prevents polluting the global namespace. Next, a template element is created which will hold the HTML content and styling for the custom widget. Within the template, there are styles defined for various classes. The .ImageContainer class has a CSS background property that defines the podium image via Base64 encoding, so we don't need a separate image file. The template also defines a structure where there's an ImageContainer and six input text boxes. Three for values, and three for names. Each input box has a unique ID. After we create the template element, we define a custom HTML element class named podium. The constructor part attaches a shadow root to the custom element, providing encapsulation for its internal structure and styling. The shadow root ensures that the widget styles and structure won't interfere with other parts of the web page, and vice versa. The content of the template element is appended to the shadow root, and references to the six input boxes are stored in class properties for easy access later. We also define two methods. The onCustomWidgetAfterUpdate method is called after the widget receives updated properties, and then it calls the render method to update the widget's display based on the new data. The asynchronous render method first checks to see if the myDataBinding property exists and if its state is success. If not, the function returns without making any updates. But if so, the data is extracted from the MyDataBinding property, processed, and sorted. Then the three highest values and their corresponding labels are extracted from the sorted data and pushed to the three value and name input boxes. Finally, the Podium class is registered as a custom element with the tag name, PodiumWidget. Now let's take a look at the JavaScript that allows us to make the font of the Podium text and values bold. The function expression ensures that the styling changes happen as soon as they are defined. We start by creating a template for the CustomPropertyPanel. This template is really simple, with only two input fields, one to set the bold factor for the numeric values on the podium, and one to set the bold factor for the text. The PodiumStylingPanel class is defined with three tasks. First, the constructor method initializes the custom element, attaches a shadow root to the element for encapsulation for the styles and the markup, and then appends the template content to the shadow root. It also adds an event listener to detect when the template is submitted. Second, the submit method says that when the template is submitted, the default form submission behavior is prevented. Instead, it dispatches a custom event called propertiesChanged to notify other parts of the widget that the properties for bold factors for both values and names have changed. The new bold values are then passed along. And third, the setters and getter methods allow other parts of the widget to get or set the new bold values of these properties. When set, they update the respective input fields in the shadow DOM. When fetched (or the get) they retrieve the current values from the input fields. Finally, our styling panel is registered with the browser using the customElements.define method.

Share feedback

Follow guided learning and develop the skills you need at your own pace

Join a moderated learning group to engage with our experts and peers

Find the right learning resources to drive your career as a developer

Sign up to access exclusive student learning journeys

Discover the SAP product knowledge you need to help you progress in your career

Develop your skills

Learn.png

Want to learn more about the value of learning with SAP?

View available SAP Certifications on SAP Learning 

Purchase a subscription and book your exam

Validate your SAP expertise

SAP Certification validates your skills, sets you apart from the crowd, and demonstrates you have the knowledge you need to succeed.

Certify.png

Accelerate your career 

Upskill in key innovation topics through openSAP's free, expert-led online courses, microlearning, and podcasts.

Join SAP Community and connect with a global network of experts and peers to ask and answer questions.

Search for SAP product documentation or browse all SAP Learning Journeys to become competent in the SAP solutions you need.

Log in to SAP Learning Hub and access the entire SAP Learning portfolio, live practice systems, and social learning opportunities.

Find free tutorials, trials, downloads, and technical product information in the SAP Developer Center.

Book live classes (online and in person) and purchase SAP Certification and SAP Learning Hub subscriptions.