view.xml

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

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 plugin. The contents of this file are Ubidots-mapped XML-like tags to React elements, so it actually differs from the traditional XML supported tags.

Form

This tag is the most important since it wraps the whole form. It is mapped to an XML form element. It has the following attributes:

name: Document-unique text that identifies the form.

Example:

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

Group

This tag is mapped in the DOM as a div. It serves as a container, thus allowing grouping elements. Its attributes are:

name: Document-unique text that identifies the group.

Example:

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

This div element represented by utilizes certain CSS flexbox technique so it is properly rendering on the front-end.

Label

This tag is mapped in the DOM as a label tag. Generally used as the title associated to an input element, yet not constrained to it solely. Its properties are:

name: Document-unique text that identifies the label.
help (optional): A help text displayed as a question mark icon next to the label. Clicking the icon reveals the text, which can also contain external links using 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 is mapped onto the DOM as a text input element. This field can be of password, switch or text type. Its properties are:

name: Document-unique text that identifies the input.
type: This is the input type of the element. Its allowed values are password, checkbox and text
placeholder (optional): Help-like text that will be displayed within 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. On the other hand, the checkbox is sent as a boolean as:

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

Paragraph

This tag is mapped into the DOM as a p element. It allows including 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 allows including external link using markdown syntaxis, however it should include the HTTP protocol (either HTTP or HTTPS)

Map

This tag represents a map in the web browser. It works as any other entry in he form, that allows selecting a location through a google map. 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): Zoom initial value. Its defaulted to 12.
type (optional): Map type. The accepted values are roadmap, satellite and hybrid, the later being the default value.

Example:

// Mapa with all of its properties set to default
<map
  name="map"
/>

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

They lat and lng values are sent to the plugin in an object as follows:

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

This is how the map looks like:

Select

This element is rendered in the browser as a dropdown, allowing users to select one or multiple 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 multiple type dropdown, the default value should be a comma-separated string without 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>

Correspondingly, for each case, the following is interpreted by the plugin:

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

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

Option

Represents individual items within a dropdown. They can only be used as sub-elements of a dropdown and cannot exist independently. Its properties are:

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

A dropdown that lists all user tokens and allows one to 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 accompanied by a label, both arranged on a single line. The text field is positioned within the label based on a specified keyword. Its properties are:

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

Example:

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

Connected Account Field

A list of all accounts connected to Ubidots, filtered based on the provider attribute. This field also allows connecting new accounts from the same provider. Its attributes are:

label (optional): Descriptive text for the field.
provider: Refers to various external services 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 related to this field can only be accessed from the control script using environment variables. Variables referencing this field have the AUTH_CREDENTIALS_ prefix.

Accessing view.xml elements from within the plugin

Any of the elements in view.xml file can be accessed from the plugin's scripts, namely control and function. For example, suppose that your plugin is implementing 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>

So in order to access these data on the aforementioned scripts, you should read the _parameters key from the incoming JSON (the function's arguments).

For this particular case, this is how said JSON would look like:

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

Said so, if you want to get the value of input-text field, you need to do something like the following snippet on your script:

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

Conversely, the input-password, input-checkbox and age-range data can be read as:

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

PreviousDevice Nextview_widget.xml

Last updated 7 months ago