Custom Widget (iFrame)
Hello everyone,
In this tutorial I’ll explain the ins and outs of Custom widgets, as well as how to build one yourself.
The new custom widgets type is now available in the latest version; this type allows you to create a widget with custom content and then display it on your dashboards. To learn more about Custom widgets, click here.
In the following paragraphs, I’ll teach you how to build your own Custom widget. Before you proceed, I recommend that you read about the specifications of this type of widget in our help center.
Creating your own
You can build your widget using any kind of web technology, such as Angular, React, Vue, or even plain old Javascript.
For the sake of simplicity, I’ll be using plain old Javascript, HTML and css. For a text editor I’ll be using Visual Studio Code version 1.44.2, but you can use even the simplest of text editors and follow along.
The screenshot below is the smallest working example of a Custom widget.
Don’t worry if you find this challenging, we’ll go step-by-step and understand the code together. The code in the screenshot above will produce the following result:
As you can see, we’ve created a simple button. Once the button is pressed, a random decimal value will be sent to the Dynamic Table.
To download this sample HTML file, click here (Right and click → Save as).
Step-by-step
Let’s walk this through step-by-step and understand our code.
These first two lines are just setting up our structure, telling the browser that the language is english and that the content of this file is html.
Here we define the configuration for the html file. There are two <meta> tags, the first one allows the use of accents in your texts (e.g. é, á, í), and the second one allows your widget to be correctly visualized in a mobile browser.
[IMPORTANT] The <script> tag tells the browser that this html file will use an external script; in this case, the external script is the TagoIO toolkit. In summary, this toolkit allows you to connect and communicate from your widget to TagoIO.
The <title> is used by the browser in case the widget goes fullscreen. This does NOT define the title of widget in the dashboard.
Here we define the initial <body> tag, which is used in html to signal we are about to start displaying content on the user’s screen.
The first tag after the <body> is the <button> tag. This tag will display a button in the page with the text inside of it, which in this case is “Send data”.
You may have noticed that there is a property called onclick in the button, this property is a function, and it is called every time the button is pressed. We’ll use this event to insert the random decimal value into our bucket.
Next up, we have the start of another <script> tag; you will notice that this tag is a bit different than the last one, because this one has content inside of it. When you put code inside of an html <script>, you’re telling the browser that this script is not external, in fact, it’s right here.
Highlighted in the screenshot above, you will see that we have created a new Javascript function called sendData, which should be the same name as the onclick event we defined in our button earlier. This function will be executed whenever the user presses our button.
In this sendData function, we are creating a JSON object and using the window.TagoIO.sendData function to send our JSON over to TagoIO.
Keep in mind that the window.TagoIO.sendData function only works because we requested it in our first <script> tag, over on line 6 of the html file.
Here we define the onStart event of our widget, and this event will fire whenever the user enters to see the dashboard. The first parameter received by this event is the widget object, this object will have all the properties of your custom widget, such as the title, parameters, variables, and more.
A good use of this function is to “save” the widget object globally, which is what we are doing in the highlighted code. You will notice we execute the code window.widget = widget, which means that we are saving the widget object globally so we can use it later.
Believe or not, this last screenshot ties the whole code together. This is the heart of your Custom widget.
Your custom widget will only appear on the screen if you call the window.TagoIO.ready() function, which means that you control whenever your widget is displayed.
We made the code like this because there were some cases where you had to perform a calculation or a request, and only then display the widget.
Until you call the ready function, your widget will keep loading, like this:
That’s it! That’s all the code you need to build your own widget. The next step is publishing it to acquire a link.
Publishing your widget
Now that you finished your widget, let’s publish it! The easiest way to publish your Custom widget is by using our Files page. To go there, press the Files button on the sidebar.
On the Files page, press the Upload File button in the top right corner:
Now select your HTML file and press upload; once your file is uploaded, select it and press Copy Url in the top right corner.
Next up, we have to create our widget. Head over to a dashboard, add a new widget, and select the Custom widget option, which looks like this:
Once you are inside of the Custom widget configuration, you should set its title and the link. The link will be the url that you just copied from the Files page.
Every variable that was used in the HTML code should be added to the widget’s configuration. For instance, if you used the variable my_variable in your HTML code, you should also add this variable to your widget’s configuration.
The configuration for your custom widget should look something like this:
That’s it! Your Custom widget should now be up and running. Once again, I recommend that you take a look at the overview documentation about the Custom widget over on our help center.