XML v1.0 (deprecated)

Create a custom sidebar navigation panel.

This XML version has been deprecated in favor of XML v2.0.

XML v1.0 lets you customize the sidebar elements described below.

XML syntax

The custom sidebar uses XML to map UI elements to code. This lets you create 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

These XML elements follow rules enforced by the editor. The editor also warns you about syntax errors:

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 include at least one <menu> or <link> element.

3. The <menu> element must include at least one <toggle> and one <collapsable> element.

4. The <collapsable> element must include at least one <menulink> element.

5. The <link> element must include at least one <icon> and one <label> element.

Here's a quick summary of the available elements. Use the links for more detail:

Sidebar element	Description	Properties
tree	Root element. All other elements must be inside it.	–
menu	Creates dropdown menus.	defaultShow: Determines whether the dropdown is open or closed when the app loads.
toggle	Defines the dropdown trigger.	–
icon	Represents the dropdown icon.	name: Name of an icon from Font Awesome.
label	Text shown in the dropdown menu.	–
chevron	Arrow icon shown in the dropdown menu.	–
collapsable	Parent element for the options in the dropdown.	–
menulink	Option shown under a dropdown menu.	path: Where the menulink redirects when clicked. permissions: List of end-user permissions under which the menulink is visible. tags: List of end-user tags under which the menulink is visible. open: Opens the link in the same tab or redirects. exact: Highlights the menulink when the current path exactly matches path.
link	Creates direct-access links.	path: Where the link redirects when clicked. permissions: List of end-user permissions under which the link is visible. tags: List of end-user tags under which the link is visible. open: Opens links in the same tab or redirects. exact: Highlights the link when the current path exactly matches path.
paragraph	Creates titles of different sizes. It helps define sections in the sidebar.	type: Determines the size. It can be "h1", "h2", "h3", "h4", "normal", or "bold".
divider	Creates horizontal lines that separate sections.	–

tree

Parent element where all <menu> and <link> elements 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 creates a dropdown menu with its options:

These are the properties of the <menulink> element:

Property	Description
path	Path in Ubidots to a direct resource, such as "/app/dashboards/663d484aaa8d92005751b2e2", a module such as "/app/dashboards/", or a full URL in Ubidots or on an external website.
permissions	Comma-separated list of permissions associated with the path. An end user only sees this menulink if the permissions match.
tags	Comma-separated list of tags. This adds a visibility layer to the sidebar. An end user only sees this menulink if the tags match. See also here.
open	Available options are: - "tab": Opens the link in a new tab. - "redirect": Opens the link in the same tab.
exact	"true" or "false". Highlights the menulink when the current path exactly matches path.

link

Element used to create shortcuts, or 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 creates a direct link:

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

paragraph and divider

Title or label element and horizontal separator.

<!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 only appear to end users whose assigned permissions match the element configuration.

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

Module	Path	Permissions
Devices	"/app/devices/"	"ubi_datasource.view_device"
Device groups	"/app/device-groups/"	"ubi_datasource.view_devicegroup"
Dashboards	"/app/dashboards/"	"ubi_dashboards.view_dashboardpg"
Events	"/app/events/"	"ubi_events.view_eventpg"
Reports	"/app/data-analysis/"	"ubi_data_analysis.view_report"
Organizations	"/app/organizations/"	"customuser.view_organization"
Users	"/app/organizations/users"	"customuser.view_user"

Filter elements by tags

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

Tag filtering lets you customize the sidebar based on the user accessing the platform. For example, if you want to create a direct link that takes users to their own home dashboard, create XML like this:

<!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 creates 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>

Assume two end users with tags tag1 and tag2, respectively. Note that there are two Home links in the XML. Since they use different tags, each Home link appears only to the matching user.

This previews the following sidebar. We have marked what each user would see: