# view\_widget.xml

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](https://dev.ubidots.com/dashboards-and-widgets/custom-ui) documentation in order to know the available elements and how to use them:

{% content-ref url="../../dashboards-and-widgets/custom-ui" %}
[custom-ui](https://dev.ubidots.com/dashboards-and-widgets/custom-ui)
{% endcontent-ref %}

## Basic structure

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

* Settings.
* Appearance.

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FJREtHMlBqFMjOduoXWkh%2Fimage.png?alt=media&#x26;token=beecba4f-d6c5-4dd6-a628-f20685d84cf4" alt=""><figcaption></figcaption></figure>

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

```xml
<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                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FaMowLhdAriMNZ4Kt9349%2Fimage.png?alt=media&#x26;token=6b6535e0-ebdf-4b34-ba08-6167d7025866" alt="" data-size="original"> | <img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2F9MVZ8Qu2UjKYGcUqxvGM%2Fimage.png?alt=media&#x26;token=259b4744-0d8d-4d83-a8e7-7bb2bbf87782" alt="" data-size="original"> | <img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FYcIM9c2gmps82VUaHIeb%2Fimage.png?alt=media&#x26;token=7c1d3001-4359-42f2-b00b-a878d9e00828" alt="" data-size="original"> |

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

{% hint style="info" %}
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
```

{% endhint %}

## 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.&#x20;
* **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](https://dev.ubidots.com/dashboards-and-widgets/custom-ui).&#x20;

### **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:**

```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()`):**

```json
{
   "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:**

```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()`):**

```json
{
   "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):

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2FBf2hPcTVrwfI3kAKVXBV%2Fimage.png?alt=media&#x26;token=6e25c929-6c25-46ae-a7b3-2794f74c80f7" alt=""><figcaption></figcaption></figure>

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

```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](https://dev.ubidots.com/dashboards-and-widgets/custom-ui) documentation.

### addvariable tag

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

<table><thead><tr><th width="173">Attribute</th><th width="122">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Yes</td><td>Unique identifier used internally. Don't modify its default value.</td></tr><tr><td><code>maxvariables</code></td><td>Yes</td><td>Max number of variables that can be added.</td></tr><tr><td><code>dividername</code></td><td>Yes</td><td>Unique identifier used internally. Don't modify its default value.</td></tr></tbody></table>

### variablelabel tag

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

<table><thead><tr><th width="166">Attribute</th><th width="134">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>label</td><td>Yes</td><td>Message displayed when selecting a variable.</td></tr><tr><td>description</td><td>No</td><td>Message displayed below the label message</td></tr></tbody></table>

<figure><img src="https://884329393-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MhzNRg0B4ECiNXc093G%2Fuploads%2F4GinbmKUVREXW3nu69dA%2Fimage.png?alt=media&#x26;token=6d30b494-7b4c-466a-8dea-bb70437d4087" alt=""><figcaption></figcaption></figure>

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.&#x20;

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

```xml
<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:

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

Then, the `settings` object will be something like:

```json
{
   "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:

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