view_widget.xml

This page lists all of the available tags within the view_widget.xml file and how to access them from within the widget

As described before, this file allows the developer to create a form so that it can be displayed as a GUI at the moment of creating the Widget on a dashboard.

The contents of this file are Ubidots-mapped XML-like tags to React elements, so it actually differs from the traditional XML supported tags. Also, view.xml and view_widget.xml are implemented differently, so their supported tags are different.

Please check our Custom UI documentation in order to know the available elements and how to use them:

Custom UI

Basic structure

Note that Ubidots native widgets feature two configuration tabs as shown below:

• Settings.

• Appearance.

The same can be implemented within plugin widget's drawer by using the tabs element in the view_widget.xmlfilie. The following is a valid configuration featuring 3 different tabs: Settings, Appearance, Advanced:

<form>
    <tabs selected="settings">
        <tab id="settings" padded="false" title="Settings">
            <addvariable
                id="settings.variable-picker"
                maxvariables="1"
                dividername="Add Variables"
                widgetbehavior="true"
            >
                <variablelabel/>
                <inputcombo
                    id="custom-label"
                    label="Custom name"
                    placeholder="Water level"
                    type="text"
                />
            </addvariable>
        </tab>
        <tab id="appearance" title="Appearance">
            <inputcombo 
                id="appearance.title" 
                type="text" 
                label="Widget title" 
                placeholder="Water level" 
            />
            <inputcombo
                id="appearance.subtitle"
                type="text"
                label="Widget subtitle"
                placeholder="Water level in the tank"
            />
            <inputcombo
                id="appearance.external-item-text"
                type="text"
                label="External item text"
                placeholder="External item"
            />
            <inputcombo
                id="appearance.external-item-url"
                type="text"
                label="External item URL"
                placeholder="http://example.com"
            />
        </tab>
        <tab id="advanced" title="Advanced">
            <inputcombo
                id="advanced.widget-id"
                type="text"
                label="Widget ID"
                placeholder="widget-1"
            />
            <inputcombo
                id="advanced.widget-class"
                type="text"
                label="Widget class"
                placeholder="widget-class"
            />
            <inputcombo
                id="advanced.widget-style"
                type="text"
                label="Widget style"
                placeholder="width: 100%;"
            />
        </tab>
    </tabs>
</form>

The configuration above renders the following drawer:

Settings tab	Appearance tab	Advanced tab

The name and number of tabs is not fixed, that is, you can add and name tabs as you require other than settingsand appareance.

To ensure that the ubidots.getWidget().getSettings() method returns a structured object where child elements are correctly nested under their respective tabs, element IDs should follow the format:

parent-tab-id.child-element-id

Tabs

Tabs within the widget drawer help developers organize user input more effectively, making the interface clearer and more structured. Tabs have 2 attributes:

• id: Unique identifier for tab element.

• title: This is the text that will be displayed in the drawer to identify the tab.

Within a tab you can place all form elements available in the Custom UI.

ID Naming Conventions

Using Parent-Referenced IDs

This method explicitly associates each element with its parent tab. The resulting xmlSettings object maintains a structured hierarchy, grouping settings under their respective tabs.

Example XML:

<tab id="settings" title="Settings">
    <inputcombo id="settings.title" type="text" label="Title"/>
    <inputcombo id="settings.subtitle" type="text" label="Subtitle"/>
</tab>

<tab id="appearance" title="Appearance">
    <inputcombo id="appearance.widget-title" type="text" label="Widget Title"/>
</tab>

Resulting JSON (ubidots.getWidget().getSettings()):

{
   "xmlSettings": {
      "settings": {
         "title": "Title",
         "subtitle": "Subtitle"
      },
      "appearance": {
         "widget-title": "Widget Title"
      }
   }
}

This structure ensures that settings remain grouped under their corresponding tab.

Using Flat IDs (Without Parent Reference)

If element IDs do not reference their parent tab, all elements will be placed at the root of xmlSettings, making it harder to determine which tab they belong to.

Example XML:

<tab id="settings" title="Settings">
    <inputcombo id="title" type="text" label="Title"/>
    <inputcombo id="subtitle" type="text" label="Subtitle"/>
</tab>
<tab id="appearance" title="Appearance">
    <inputcombo id="widget-title" type="text" label="Widget Title"/>
</tab>

Resulting JSON (ubidots.getWidget().getSettings()):

{
   "xmlSettings": {
      "title": "Title",
      "subtitle": "Subtitle",
      "widget-title" : "Widget Title"
   }
}

In this case, all child elements appear at the root level, losing their association with their parent tab.

Best Practice

To maintain a well-structured configuration it is strongly recommended to follow the parent-tab-id.child-element-id convention when defining IDs for elements inside tabs.

'Add Variables' element

Ubidots native widgets offer the capability to select the target variables for the widget as well as the widget behavior (static or dynamic):

The same can be achieved by using the addvariableelement in the view_widget.xmlfile For example, in order to replicate the Metric widget's UI shown above, you can use the following view_widget.xml:

<form>
    <addvariable
        id="variables"
        maxvariables="1"
        dividername="ADD VARIABLES"
    >
        <variablelabel
            label="Variable label"
            description=""
        />
        <inputcombo
            type='dropdown.list'
            id='aggregationMethod'
            label="Aggregation method"
            description=""
            placeholder='Last value'
        >
            <menu>
                <item id='last_value'>Last value</item>
                <item id='average'>Average</item>
                <item id='minimum'>Minumum</item>
                <item id='maximum'>Maximum</item>
                <item id='sum'>Sum</item>
                <item id='count'>Count</item>
            </menu>
        </inputcombo>
        <inputcombo
            type="span"
            id="span"
            label="Span"
            description=""
        />

    </addvariable>
</form>

Note that within the addvariable tag, you can use any of the elements described in the Custom UI documentation.

addvariable tag

This element is interpreted such that it displays the whole modal for adding variables. The following are its attributes:

Attribute	Mandatory	Description
id	Yes	Unique identifier used internally. Don't modify its default value.
maxvariables	Yes	Max number of variables that can be added.
dividername	Yes	Unique identifier used internally. Don't modify its default value.

variablelabel tag

This element displays a label and a description within a container in order to provide detailed information.

Attribute	Mandatory	Description
label	Yes	Message displayed when selecting a variable.
description	No	Message displayed below the label message

With this in mind, if you changed the label attribute from Variable label to Variables , such message will be displayed instead.

Adding variables' Aggregation methods

If your Plugin widget requires information about the variable's aggregation method, you can use a inputcombo of the dropdown.list type as shown above, however, for it to work correctly, it is mandatory that the id attribute has the value aggregationMethod

Adding variable's time-span

If your Plugin widget requires a time span for the variable's data, you can use a inputcombo of the span type as shown above, however, for it to work correctly, it is mandatory that the id attribute has the value span

Accessing `view_widget.xml` data from the Widget's script

The view_widget.xml elements can be accessed from within the widget.js script using the input combo id attribute.

For example, suppose your Widget is implementing the following view_widget.xml file:

<form>

    <inputcombo 
        id="device_label" 
        type="text" 
        label="Device label" 
        description="Device's label to which send the data" 
        placeholder="" 
    />
    <inputcombo 
        id="title" 
        type="text" 
        label="Chart's title" 
        description="Chart's title" 
        placeholder="" 
    />
    <addvariable
        id="variables"
        maxvariables="1"
        dividername="ADD VARIABLES"
    >
        <variablelabel
            label="Variable label"
            description=""
        />
        <inputcombo
            type='dropdown.list'
            id='aggregation_method'
            label="Agregation method"
            description=""
            placeholder='Last value'
        >
            <menu>
                <item id='last_value'>Last value</item>
                <item id='average'>Average</item>
                <item id='minimum'>Minumum</item>
                <item id='maximum'>Maximum</item>
                <item id='sum'>Sum</item>
                <item id='count'>Count</item>
            </menu>
        </inputcombo>
        <inputcombo
            type="span"
            id="span"
            label="Span"
            description=""
        />
    </addvariable>
</form>

You can access all of these data as follows:

const settings = ubidots.getWidget().getSettings()["xmlSettings"];

Then, the settings object will be something like:

{
   "title":"my chart",
   "variables":[
      {
         "span":"inherit",
         "color":{
            "a":1,
            "b":62,
            "g":131,
            "r":131
         },
         "label":"variable-cron",
         "variableColor":{
            "a":1,
            "b":62,
            "g":131,
            "r":131
         },
         "aggregationMethod":"last_value"
      }
   ],
   "device_label":"my device",
   "widgetBehavior":"inherit"
}

This object contains on the root level, all the keys corresponding to each of the view_widget.xml element's id.

For example note that above, it was used two input combo whose ids are device_label and tittle correspondingly, also note that those keys are within the settings object. Also note variables key, this is always a list containing the selected variables.

You can also access the widget's endpoint in the following way:

const url = ubidots.getWidget().getSettings()["function_url"]