Widget

Definition

A private widget plugin is a custom-developed widget that is made available as if they were Ubidots native. As any other widget, it offers both, logic execution and a user graphical interface for interaction.

Its visuals displaying and logic execution are performed at the moment of loading the dashboard and will only take place as long as the dashboard containing it remains open.

For instance, consider the following widget using the JavaScript HighCharts library for data plotting:

When a user accesses the dashboard containing this widget, the browser renders its visuals, and the logic—fetching and plotting the data—runs during the dashboard's load time.

After leaving the dashboard containing the widget, all tasks within its logic will stop.

Required files

As stated before any Private plugin regardless of its type, and, particularly, a private widget plugin, is composed by the file structure shown below:

├── src
│   ├── static                    
│   │   ├── widget.css      
│   │   ├── widget.html 
│   │   ├── widget.js             
│   ├── view.xml
│   ├── view_widget.xml           
├── LICENSE
├── README.md
├── manifest.toml

src and static directory

Unlike Cron and Webhook plugins, the Widget plugin includes an additional directory called static. This directory holds the widget's HTML, CSS and JavaScript files.

Placing the CSS, HTML and JS files within the root of src and not inside static will cause deployment errors.

widget.css

Written in CSS, it styles the widget's visual components.

widget.html

Written in HTML, this file dictates the arrangement of the widget's visual elements.

widget.js

Written in JavaScript, this handles the plugin's core logic and potentially altering the CSS styles and HTML dynamically.

Naming convention

You ought to retain the names of all files and directories mentioned in the "required files" section, as the plugins engine specifically searches for these files and their extensions.

If the name of a file or directory is changed, the plugin won't be able to be deployed.

view.xml

Though this file is only relevant when using Cron and Webhook type plugins, it still must contain valid placeholder data to deploy the plugin.

view_widget.xml

The form to display its required parameters is created using view_widget.xml, not the view.xml file.

For example, suppose that you are creating a widget that uses HighCharts to plot data, for that reason, the widget requires the following information from the user :

• Variable label

• Title

• Subtitle

• X axis label

• Y axis label

• Series name

A form containing those fields might look like this:

The form above can be built using the view_widget.xml as:

<form>
    <inputcombo
        id="variable_label"
        type="text"
        label="Variable label"
        description="Device's variable label to which send the data"
        placeholder=""
        value=""
    />
    <inputcombo
        id="title"
        type="text"
        label="Chart's title"
        description="Chart's title"
        placeholder=""
        value=""
    />
    <inputcombo
        id="subtitle"
        type="text"
        label="Chart's subtitle"
        description="Chart's subtitle"
        placeholder=""
        value=""
    />
    <inputcombo
        id="x_axis_name"
        type="text"
        label="X-axis name "
        description="X-axis subtitle"
        placeholder=""
        value=""
    />
    <inputcombo
        id="y_axis_name"
        type="text"
        label="Y-axis name "
        description="Y-axis subtitle"
        placeholder=""
        value=""
    />
    <inputcombo
        id="series_name"
        type="text"
        label="Series name"
        description="Name for the Series"
        placeholder="series 1"
        value=""
    />
</form>

All of these parameters in the form are accessible to the widget.js script using the Ubidots JavaScript class.

For detailed information regarding how to access the XML properties from within the widget.js script, refer to the its corresponding section in the Plugins development page

pageWidget

For detailed information about the supported form elements, please head to the view_widget.xml section in the Plugins development page

pageview_widget.xml

LICENSE and README.md files

Refer to Private Plugins page to get detailed information:

pagePrivate Plugins

Manifest.toml

Aside from previously mentioned manifest components common to all plugin types, the following ones are specific to Widget type plugin:

Section/subsection	key	Value	Description	Example
[settings.widget]	name	Any string	This is the name that the Widget will display on the plugins drawer	nae = " my first Widget plugin"
[settings.widget]	js_thirdparty_libraries*	A list of valid CDN URL	This is the list of libraries that the widget will import to be used on its logic	js_thirdparty_libraries = [ "https://code.jquery.com/jquery-3.6.0.min.js", "https://code.jquery.com/moment-3.6.0.min.js" ]
[settings.widget]	css_thirdparty_libraries*	A list of valid CDN URL	This is the list of libraries that the widget will import to be used on its styling	css_thirdparty_libraries = [ "https://code.jquery.com/jquery-3.6.0.min.css", "https://code.jquery.com/moment-3.6.0.min.css" ]
[settings.widget]	enable_lazy_load	true or false	Enables or disables lazy load for the widget's visual components	enable_lazy_load = true

With this in mind, a typical Widget plugin manifest file looks like:

manifest_version = 2.0

[settings]
version = "1.1.1"
plugin_type = "widget"
license_name = "MIT license"

[settings.widget]
name = "Send data to device widget"  
js_thirdparty_libraries = [
  "https://code.jquery.com/jquery-3.6.0.min.js",
  "https://code.jquery.com/moment-3.6.0.min.js"
]
css_thirdparty_libraries = [
  "https://code.jquery.com/jquery-3.6.0.min.css",
  "https://code.jquery.com/moment-3.6.0.min.css"
]
enable_lazy_load = true

The keys marked with a * in the table, are not mandatory to be set, that is, you are not complied to import either JS or CSS libraries, however, you should define the key as an empty list.

For instance, if no JS or CSS libraries want to be imported, the manifest will look like:

manifest_version = 2.0

[settings]
version = "1.1.1"
plugin_type = "widget"
license_name = "MIT license"

[settings.widget]
name = "Send data to device widget"  
js_thirdparty_libraries = [ ] //No JS libraries are imported
css_thirdparty_libraries = [ ] //No CSS libraries are imported
enable_lazy_load = true