view.xml

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

This file lets developers create a form that is displayed as a GUI when the plugin is created.

Its contents use Ubidots-mapped, XML-like tags that render as React elements. Because of this, it differs from traditional XML tags.

Form

This is the main tag because it wraps the entire form. It maps to a form element. It has the following attribute:

• name: Document-unique text that identifies the form.

Example:

<form name="form-name">
...
</form>

Group

This tag maps to a div in the DOM. It acts as a container and lets you group elements. It has the following attribute:

• name: Document-unique text that identifies the group.

Example:

<group name="group-1">
    <group name="group-2">
        ...
    </group>
</group>

This div uses CSS flexbox so it renders correctly in the front end.

Label

This tag maps to a label element in the DOM. It is usually used as the title for an input element, but it is not limited to that use. Its properties are:

• name: Document-unique text that identifies the label.

• help (optional): Help text displayed as a question mark icon next to the label. Clicking the icon reveals the text, which can also contain external links written in markdown.

Example:

// Label with help text
<label
  name="label-with-help"
  help="Some help text, [Click here](https://google.com)"
>
  Test label
</label>

// Label without help 
<label 
  name="label"
>Test label
</label>

Input

This tag maps to an input element in the DOM. This field can be password, checkbox, or text. Its properties are:

• name: Document-unique text that identifies the input.

• type: Input type. Allowed values are password, checkbox, and text.

• placeholder (optional): Helper text displayed inside the input field.

• value (optional): Default value for the input.

// Text type input
<input
  name="input-text"
  type="text"
  placeholder="Test placeholder"
  value="test value"
/>
 
// Password type input
<input
  name="input-password"
  type="password"
  placeholder="Test placeholder"
/>

// Checkbox type input
<input
  name="input-checkbox"
  type="checkbox"
  value="false"
/>

The text and password inputs are sent to the plugin as plain text. The checkbox is sent as a boolean:

{
  "input-text": "test value",
  "input-password": "",
  "input-checkbox": false
}

Paragraph

This tag maps to a p element in the DOM. It lets you include text blocks within the form. Its properties are:

• name: Document-unique text that identifies the paragraph.

Example:

<paragraph name="paragraph">
  Lorem Ipsum is simply dummy text of the printing and typesetting industry. 
  Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, 
  when an unknown printer took a galley of type and scrambled it to make a 
  type specimen book. It has survived not only five centuries, but also 
  the leap into electronic typesetting, remaining essentially unchanged. 
  It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more 
  recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
  [link](https://www.lipsum.com/)
</paragraph>

As shown above, this tag supports external links written in markdown. The link must include the HTTP or HTTPS protocol.

Map

This tag represents a map in the browser. Like any other form field, it lets users select a location through Google Maps. Its properties are:

• name: Document-unique text that identifies the map within the form.

• lat (optional): If allowed by the user, their position will be retrieved and lat will be the user's position latitude. Else, it will be set to 37.428458 by default.

• lng (optional): If allowed by the user, their position will be retrieved and lng will be the user's position longitude. Else, it will be set to -122.160901 by default.

• zoom (optional): Initial zoom value. The default is 12.

• type (optional): Map type. Accepted values are roadmap, satellite, and hybrid. The default is hybrid.

Example:

// Map with all properties set to their default values
<map
  name="map"
/>

// Map with custom properties
<map
  name="map-2"
  lat="37.420015"
  lng="-122.160901"
  zoom="13"
  type="satellite"
/>

The lat and lng values are sent to the plugin in an object like this:

{"map": { lat: 37.428458, lng: -122.160901 }}

This is how the map looks:

Select

This element is rendered in the browser as a dropdown. It lets users select one or more items from a list. Its properties are:

• name: A unique identifier for the dropdown within the form.

• type: Determines if the dropdown allows single or multiple selections. Accepted values are single and multiple.

• search (optional): Enables a search feature within the dropdown. Accepted values are enabled and disabled.

• placeholder: A default message displayed in the dropdown before any selection.

• value (optional): Default value for the dropdown.

Note: For a multiple dropdown, the default value must be a comma-separated string with no spaces.

<!-- Single selection dropdown -->
<select 
  name="single-name" 
  placeholder="Single placeholder" 
  value="1" 
  type="single"
>
  
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>

</select>

<!-- Multiple selection dropdown with search enabled -->
<select 
  name="multiple-name" 
  placeholder="Multiple placeholder" 
  value="1,3,2" 
  type="multiple" 
  search="enabled">
  
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
  <option value="3">Option 3</option>
  
</select>

For each case, the plugin interprets the values as follows:

// Single selection
{"single-name":  "1"}

// Multiple selection
{
  "multiple-name": [
    { "id": "1", "name": "1"}, 
    { "id": "3", "name": "3"}, 
    { "id": "2", "name": "2"}
  ]
}

Option

This tag represents an individual item within a dropdown. It can only be used inside a dropdown and cannot exist on its own. Its property is:

• value: The associated value of the item.

Example:

<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>

Token

This dropdown lists all user tokens and lets one be selected for plugin configuration. Its properties are:

• name: A unique identifier for the token within the form.

• placeholder: A default message displayed in the dropdown before any selection.

Example:

<token 
    name="ubi-token" 
    placeholder="Ubidots token"
/>

This is sent to the plugin as:

{"ubi-token": "fake-token"}

Frequency

A text field with a label, both arranged on a single line. The text field is positioned inside the label based on a keyword. Its property is:

• label: Descriptive text for the interval input field. The label can contain the {field} keyword, which marks the position of the text field. If it is not included, the field is placed at the end of the label.

Example:

<frequency label="Run every {field} minutes"/>

Connected Account field

This field lists all accounts connected to Ubidots, filtered by the provider attribute. It also lets users connect new accounts from the same provider. Its attributes are:

• label (optional): Descriptive text for the field.

• provider: Refers to the external service that can be connected. Currently, the only accepted value is AWS_IAM. This attribute is case-sensitive.

Example:

<connectedAccount label="Label test" provider="AWS_IAM"/>

Note: Information from this field can only be accessed from the control script through environment variables. Variables that reference this field use the AUTH_CREDENTIALS_ prefix.

Accessing view.xml elements from within the plugin

Any element in the view.xml file can be accessed from the plugin scripts, namely control and function. For example, suppose your plugin uses the following view.xml file:

<form>
  <input
    name="input-text"
    type="text"
    placeholder="Test placeholder"
    value="test value"
  />
 
  <input
    name="input-password"
    type="password"
    placeholder="Test placeholder"
  />

  <input
    name="input-checkbox"
    type="checkbox"
    value="false"
  />
  
  <select 
    name="age-range" 
    placeholder="Select your age range" 
    value="15-20" 
    type="single"
  >
    <option value="1">15-20</option>
    <option value="2">21-35</option>
    <option value="2">More than 36</option>
  </select>

</form>

To access this data in those scripts, read the _parameters key from the incoming JSON payload, which contains the function arguments.

In this case, the JSON would look like this:

{
    ... /Other data,
    .
    .
    .
    _parameters : {
        "input-text" : "some text",
        "input-password" : "some password",
        "input-checkbox" : "false"
    }
}

If you want to get the value of the input-text field, use a snippet like this in your script:

inputTextValue = args["_parameters"]["input-text"]

Likewise, the input-password, input-checkbox, and age-range values can be read like this:

inputPasswordValue = args["_parameters"]["input-password"]
inputCheckboxValue = args["_parameters"]["input-checkbox"]
ageRangeValue = args["_parameters"]["age-range"]