XML v1.0 (deprecated)

The XML v1.0 syntax allows to customize the sidebar elements described below.

XML syntax

The custom sidebar uses XML to map UI elements to code, which is the engine that allows the creation of a sidebar tailored to a specific application.

The available UI elements, and their hierarchy, are:

├── tree
│   ├── menu
│   │   ├── toggle
│   │   │   ├── icon
│   │   │   ├── label
│   │   │   ├── chevron
│   │   ├── collapsable
│   │   │   ├── menulink
│   ├── link
│   │   ├── icon
│   │   ├── label
│   ├── paragraph
│   ├── divider

Using these XML elements comes with rules that are enforced by the editor and warns you of errors in the syntax:

1. The XML needs to start with: <!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V1.0//EN' "-">

2. The <tree> element is mandatory. It must have at least 1 or more <menu> or <link> elements.

3. The <menu> element must have at least 1 <toggle> and 1 <collapsable> elements.

4. The <collapsable> element must have at least 1 <menulink> element.

5. The <link> element must have at least 1 <icon> and <label> elements.

Here's a quick summary of the available elements, but you can click the links and read more details:

tree

Parent element where all <menulink> and <link> reside:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V1.0//EN' "-">
<tree>
    <!--Your menulink and link components go here-->
</tree>

menu, toggle, icon, label, chevron, collapsable and menulink

Elements used to create dropdown menus:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V1.0//EN' "-">
<tree>
    <menu defaultShow="true">
      <toggle>
        <icon name="gear"/>
        <label>Settings</label>
        <chevron/>
      </toggle>
    <collapsable>
      <menulink 
          open="tab"
          exact="false"
          path="/app/devices"
          tags="tag1"
          permissions="ubi_datasource.view_device"
        >Datasources
      </menulink>
      <menulink path="/app/dashboards/" tags="tag1" permissions="ubi_dashboards.view_dashboardpg">Custom dashboards</menulink>
    </collapsable>
  </menu>
</tree>

This will create a dropdown menu, with its options, as follows:

These are the properties of the <menulink> element:

link

Element to create shortcuts, in other words, direct access to modules or resources:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V1.0//EN' "-">
<tree>
  <link
    open="tab"
    exact="true" 
    path="/app/dashboards/663d484aaa8d92005751b2e2" 
    tags="tag1" 
    permissions="ubi_dashboards.view_dashboardpg">
      <icon name="home"/>
      <label>Home</label>
  </link>
</tree>

This will create a direct link, as follows:

The properties of the <link> element are the same as the <menulink>

paragraph and divider

Title/label element and horizontal separation line.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V1.0//EN' "-">
<tree>
    <paragraph type="bold">SECTION 1</paragraph>
    <divider/>
    <paragraph type="bold">SECTION 2</paragraph>
</tree>

This will create the following:

Permissions

With permissions, the <menulink> and <link> elements will only appear to those end users whose assigned permissions match that of the element configuration.

The available permissions for each possible path that's exposed to the end users in the application are:

Filter elements by tags

The <menulink> and <link> elements receive a "tag" property that adds a visibility layer on top of the permissions assigned to an end user. The way it works is by matching the tags of an end user with those specified in the <menulink> or <link> (learn more about tag filtering). Simply put, if there's at least one match between the user tags and the element's, it means the element will be visible to the user.

This filtering by tags allows customizing the sidebar based on the user accessing the platform. For example, say you want to create a direct link that takes users to their own home dashboard, you would create an XML as follows:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V1.0//EN' "-">
<tree>
  <!--This link creates Home for User 1-->
  <link
    open="tab"
    exact="true" 
    path="/app/dashboards/663d484aaa8d92005751b2e2" 
    tags="tag1" 
    permissions="ubi_dashboards.view_dashboardpg">
      <icon name="home"/>
      <label>Home</label>
  </link>

  <!--This link create Home for User 2-->
  <link
    open="tab"
    exact="true" 
    path="/app/dashboards/663d484aaa8d92007364jnhd" 
    tags="tag2" 
    permissions="ubi_dashboards.view_dashboardpg">
      <icon name="home"/>
      <label>Home</label>
  </link>
</tree>

Let's assume 2 end users, with tags "tag1" and "tag2", respectively. Note that there are 2 home links in the XML, however, since they have different tags ("tag1" and "tag2"), each home link will appear to the respective user.

Likewise, this will preview the following sidebar. We have marked what each user would see: