15th May 2019Embedded Analytics truly means allowing for a seamless integration of icCube into other softwares or webpages, not only from a technical point of view, but also from a design point of view.
The possibility of adding your own HTML, CSS and JS codes allows the report builder to design dashboards that precisely fit with your very own corporate branding and expectations.
This article explains step-by-step how to create the following customized HTML widget based on an HTML-based report (download available on page bottom).
Custom widgets can in fact be saved as templates and reused for future reports in icCube. Let’s get started!
STEP 0 – Knowing your data & define what you would like to display
This first step seems trivial, but you don’t want to underestimate it. Make a prototype of the data you would like to show on your new widget.
For this example, we are using the default Sales schema available when you download icCube. As the image shown above, we would like to:
- display the measure “Amount” by support product (“Silver”, “Gold”, “Platinum”) contained in the Dimension called “Products”,
- Display the total of those 3 products,
- and have the widget respond to a filter by “Country”.
STEP 1 – Defining your widget’s style
Use a styling tool such as CodePen, to build your very own widget’s design. This step is usually done by a designer to ensure a professional and brand-consistent look to your widget and report.
Find our code example here.
Once you’re happy with your widget’s look, you can implement it into icCube.
Go to icCube’s Reporting Editor, start a new report and create a new widget template:
Insert your HTML code on the “HTML data received” field:
STEP 2 – Defining your widget’s properties
Your widget will depend on certain properties, which are values coming from your cube. In our case, as previously mentioned on Step 0 and again shown below, the properties are: the measure “Amount” for the Silver, Gold and Platinum products, as well as the total of these 3.
Write the following JS code to create these 4 properties and add it to the “After Render” field of your Widget Template:
function(context, node, props, onRenderedCallback) {
$(node).find("span[idccube='amount']").html(''+props.amount());
$(node).find("span[idccube='silver']").html(''+props.silver());
$(node).find("span[idccube='gold']").html(''+props.gold());
$(node).find("span[idccube='platinum']").html(''+props.platinum());
}
This code simply binds variables placeholders from your HTML template.
For instance, whenever you insert the following HTML code in your HTML template:
<span idccube='amount'></span>
it will be replaced by the icCube-defined property ‘amount’, provided that you also insert the following JavaScript statement:
$(node).find("span[idccube='amount']").html(''+props.amount());
‘amount’ is simply the property ‘Value Reference’ field content.
Under the configuration wheel of the Properties, attribute the titles that will be displayed on your widget to each of the properties. For instance, we want to call the total sum “Total Support Amount”. As mentioned above, the “Value Reference (in Properties)” should correspond to the one defined on your JS code.
STEP 3 – Data definition
Now that we have created the properties, we need to have the data definition that will “populate” your widget.
We want to show sales for selected members (a subset) of the Products’ dimension, i.e. only Silver, Gold and Platinum products, as well as their total.
Please note that the widget has a limitation, each data retrieved should be defined as a measure, so you can’t simply have the single measure Amount on your query, you need to create an Amount measure for each of those specific products, including the (sub)total.
Therefore, create a new Amount measure per product, e.g. the “Silver Amount” measure is the tuple:
([Measures].[Amount],[Product].[Product].[Article].[Silver]), FORMAT_STRING="#'###"
STEP 4 – Link properties to its according data
Going back to the widget design, select the according measure to its respective property thanks to the drop down menu. As shown below, Under the “Silver” property, the value displayed is “Silver Amount” that was just created on the previous step.
Note that you have a Save button on the widget allowing you to reuse this Widget Template for future reports.
Your very own, newest widget template is now done!
STEP 5 (bonus) – Adding events
Widget Templates, as all other available widgets in icCube, can respond to actions. Let’s add a map widget that includes an event by Country updating your Widget Template accordingly.
To do so, create a new Geo Chart, add Amount on Measures and the dimension [Customers].[Geography].[Country] on rows, and create an event on row click as shown below.
Simply add this event as a filter on your Widget Template’s data definition, as well as on the header of your widget (see HTML code).
Now, once you click on a country, your new Widget Template will respond and update according to your country selection.
Find the report file with this full example here.
Other HTML example
Make sure to check this other article on how to create a different HTML box (containing an icon/image), this widget example is available live here.
By Nathalie Leroy Tapia Heredia