XML v2.0

Create a sidebar navigation that's more elaborate and dynamic.

As covered in Custom sidebar menu, XML v2.0 introduces a more modular and dynamic sidebar structure. The root <tree> now splits content into an optional set of asidepanel elements and a body, each with its own sections. The enhanced asidepanel also supports dynamic content loaded through HTTP requests and JSONPath parsing, which enables a more flexible and user-aware sidebar.

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 XML elements and their hierarchy are:

├── tree
│   ├── asidepanel
│   │   ├── (Option A: static)
│   │   │   └── section
│   │   │       ├── menu
│   │   │       │   └── item
│   │   │       ├── link
│   │   │       ├── text
│   │   │       └── divider
│   │   ├── (Option B: dynamic using attributes)
│   │   │   └── [HTTP source + query + path → resolved into link]
│   └── body
│       └── home
│       └── section
│           ├── menu
│           │   └── item
│           ├── link
│           ├── text
│           └── divider

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

The XML needs to start with: <!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu XML V2.0//EN' "-">.
The <tree> element is mandatory. It must include at least one <body> element. <asidepanel> is optional, and you can add as many as needed.
<asidepanel> can be static or dynamic. In dynamic mode, its content is loaded through HTTP and parsed based on the element attributes.
The <body> must have at least one <section>.
<section> must have at least one <menu> or <link>.
<menu> must have at least one <item>.

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

Summary of elements and their attributes

Sidebar element

Description

Attributes

tree

Root element. All other elements must be inside it.

–

asidepanel

Creates static or dynamic aside panels. This is an optional element inside <tree>.

id: Used to associate the asidepanel with a <link> or <item>.
source: Path or URL from which dynamic content is retrieved through HTTP.
query: JSONPath expression used to parse the response from source.
path: Dynamic path template for each option in the asidepanel. It supports JSONPath.
label: Label shown for each dynamic option in the asidepanel. It supports JSONPath.
text: Title of the asidepanel when open. It supports JSONPath.
permissions: List of end-user permissions under which the asidepanel content is visible.
tags: List of end-user tags under which the asidepanel content is visible.

body

Wraps all sidebar content.

–

home

Controls the path or URL used when clicking the application logo.

path: Path or URL used when clicking the logo.
permissions: List of end-user permissions under which the home path applies.
tags: List of end-user tags under which the home path applies.

section

Wraps link, menu, text, and divider elements. It creates a separation between sections, with an optional title.

text: Title of the section.
permissions: List of end-user permissions under which the section is visible.
tags: List of end-user tags under which the section is visible.

Dropdown menu.

defaultShow: [true | false] Determines whether the dropdown is open or closed when the app loads.
icon: Name of an icon from Font Awesome.
iconFaType: [duotone | classic] Font Awesome type.
iconFaStyle: [solid | regular | light | thin] Font Awesome style.
label: Title of the menu.

item

Option displayed inside a dropdown menu.

panelTarget: ID of the asidepanel. If present, path is ignored.
path: Where the item redirects when clicked.
label: Title of the item.
open: Open the link in the same tab or redirect.
exact: Highlights the item when the current path exactly matches path.
permissions: List of end-user permissions under which the item is visible.
tags: List of end-user tags under which the item is visible.

link

Creates direct-access links.

panelTarget: ID of the asidepanel. If present, path is ignored.
path: Where the link redirects when clicked.
label: Title of the link.
icon: Name of an icon from Font Awesome.
iconFaType: [duotone | classic] Font Awesome type.
iconFaStyle: [solid | regular | light | thin] Font Awesome style.
open: Open links in the same tab or redirect.
exact: Highlights the link when the current path exactly matches path.
permissions: List of end-user permissions under which the link is visible.
tags: List of end-user tags under which the link is visible.

text

Creates text with 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 that wraps the body and optional asidepanel elements:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu XML V2.0//EN' "-">
<tree>
    <!--Your body and optional asidepanel elements go here-->
</tree>

asidepanel

This element creates a static or dynamic, user-aware asidepanel.

asidepanel can only be opened from a link or item element inside a body section.
A dynamic asidepanel takes precedence over a static one. If the source and path attributes are set, all elements inside the asidepanel are ignored.
Some asidepanel attributes support JSONPath expressions. These are used to parse the response when the asidepanel loads dynamic content from an HTTP request.

These are the attributes of the asidepanel element:

Attribute

Description

Used to associate the asidepanel with the respective link or item elements that invoke it.

source

Ubidots API endpoint path or external URL from which the asidepanel content is retrieved dynamically through an HTTP request.

text

Title of the asidepanel. It supports JSONPath expressions, so it can change dynamically based on the HTTP response from source.

query

JSONPath expression used to parse the HTTP response from source. The result should render a list of strings or objects used as the asidepanel option content.

label

JSONPath expression used to select the label shown for options in the asidepanel. This expression is evaluated over each list element returned by query.

path

JSONPath expression used to build the path each option redirects to when clicked. This expression is evaluated over each list element returned by query.

permissions

Comma-separated list of permissions associated with the path. An end user only sees the asidepanel content if the permissions match.

tags

Comma-separated list of tags. This adds a visibility layer to the sidebar. An end user only sees the asidepanel content if the tags match. See also here.

The next two tabs show examples of static and dynamic asidepanels, both in XML and in the UI. For simplicity, these examples do not use permissions or tags. Refer to those sections to learn more about these two attributes.

This XML creates a fixed-content asidepanel. In this mode, the asidepanel works similarly to a body element and supports section, link, menu, item, text, and divider elements:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu XML V2.0//EN' "-">
<tree>
  <asidepanel id="static-asidepanel">
    <section text="Static Internal Navigation">
      <text type="bold">Static panel with links and menus to resources</text>
      <link path="/app/dashboards/689619a3c9a12800114b6fbd" icon="home" label="Home"/>
      <menu icon="microchip" label="Device Management">
        <item path="/app/devices" label="All Devices" />
        <item path="/app/device-groups" label="Device Groups" />
        <item path="/app/device_types" label="Device Types" />
      </menu>
      <divider />
      <link path="/app/settings/" icon="cog" label="Settings" />
      <link path="/accounts/me/" icon="user" label="Profile" />
    </section>
  </asidepanel>
  <body>
    <section text="Main sidebar">
      <link panelTarget="static-asidepanel" icon="sidebar" label="Aside static"/>
      <menu defaultShow="true" icon="microchip" label="Devices">
        <item panelTarget="static-asidepanel" label="Aside static"/>
        <item path="/app/device-groups/" label="Group" />
        <item path="/app/device_types/" label="Types" />
      </menu>
    </section>
  </body>
</tree>

This creates the static asidepanel shown below. The two "Aside static" options in the sidebar come from the link and the item inside the body section.

This XML creates a dynamic-content asidepanel. In this mode, the asidepanel loads user-aware content through an HTTP request. In this example, it requests the Ubidots dashboards API endpoint. However, it could also request the URL of an UbiFunction where custom logic is applied based on the user loading the asidepanel. It then uses its JSONPath-enabled attributes to parse the response and render the asidepanel.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <asidepanel 
    id="dynamic-asidepanel"
    source="/api/v2.0/dashboards/"
    query="$.results[*]"
    label="$.name"
    path="/app/dashboards/{$.id}"
    text="Dynamic asidepanel"
  />
  <body>
    <section text="">
      <link path="/app/dashboards/" icon="home" label="Home"/>
      <link path="/app/dashboards/68c056ffe40f2600103af3ec/" icon="industry-windows" label="Production"/>
      <link path="/app/dashboards/" icon="chart-line-down" label="Losses"/>
      <menu defaultShow="true" icon="gear" label="Settings">
        <item path="/app/devices" label="Datasources"/>
        <item panelTarget="dynamic-asidepanel" label="Custom dashboards"/>
      </menu>
    </section>
  </body>
</tree>

This creates the dynamic asidepanel shown below. The "Custom dashboards" option in the sidebar sends an HTTP request to /api/v2.0/dashboards/ and renders dynamic content by parsing the response with the configured attributes.

body

Element that wraps the sidebar content.

The body must have at least one section element.
The body element may have 0 or more home elements.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu XML V2.0//EN' "-">
<tree>
  <!--Your optional asidepanel elements go here-->
  <body>
    <!--Your sections and optional home elements go here-->
  </body>
</tree>

home

By default, clicking the application logo takes end users to the dashboards module at /app/dashboards/, usually to the last dashboard they viewed. By configuring this element, you can control the path or URL opened when each user clicks the application logo, based on permissions and tags.

If permissions and tag filtering render multiple home elements for the same end user, clicking the logo goes to the dashboards module by default.

These are the attributes of the home element:

Attribute

Description

path

Redirection path (see available paths here) or URL.

permissions

Comma-separated list of permissions associated with the path. An end user only sees the effect of the home element if the permissions match.

tags

Comma-separated list of tags. This adds a visibility layer to the sidebar. An end user only sees the effect of the home element if the tags match. See also here.

The example below shows two home elements, each pointing to a different dashboard. By using tags, one is shown to User1 and the other to User2.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">

<tree>
  <body>
    <!-- Home for User1 with tag1 -->
    <home 
      path="/app/dashboards/663d484aaa8d92005751b2e2" 
      permissions="ubi_dashboards.view_dashboardpg" 
      tags="tag1"/>

    <!-- Home for User1 with tag2 -->
    <home 
      path="/app/dashboards/663d484aaa8d92007364jnhd" 
      permissions="ubi_dashboards.view_dashboardpg" 
      tags="tag2"/>

    <section text="Main Navigation">
      <link 
        label="Dashboard" 
        path="/dashboard" 
        icon="home.svg" 
        iconFaType="classic" 
        iconFaStyle="solid"/>
    </section>
  </body>
</tree>

section

This element creates groups of menu, link, text and divider elements within the sidebar or static asidepanel. The groups are separated by an optional text label.

The section must contain at least one menu, link, divider, or text element.
The text attribute is mandatory.

These are the attributes of the section element:

Attribute

Description

text

Label or title of the section. It can be left empty, as in text="".

permissions

Comma-separated list of permissions associated with the path. An end user only sees the section if the permissions match.

tags

Comma-separated list of tags. This adds a visibility layer to the sidebar. An end user only sees the section if the tags match. See also here.

Here's an XML example with 2 sections.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <body>
    <!-- First section -->
    <section text="Main Section">
      <link label="Dashboard" path="/dashboard" icon="home"/>
      <menu label="Reports" defaultShow="true" icon="newspaper">
        <menuitem label="Sales Report" path="/reports/sales"/>
        <menuitem label="Inventory Report" path="/reports/inventory"/>
      </menu>
    </section>
    
    <!-- Second section -->
    <section text="Settings Section">
      <link label="Profile" path="/settings/profile" icon="user"/>
      <menu label="Admin Tools" defaultShow="false" icon="gear">
        <menuitem label="User Management" path="/admin/users"/>
        <menuitem label="System Logs" path="/admin/logs"/>
      </menu>
    </section>
  </body>
</tree>

These two elements help create menus within the sidebar or a static asidepanel.

A menu must have at least one item.
If permissions and tag filtering render an empty menu, the menu is not visible to the end user.

Attributes by element

Attribute

Description

label

Label of the item.

panelTarget

ID of the asidepanel. If present, path is ignored.

path

Redirection path (see available paths here) or URL.

exact

Highlights the item when the current path exactly matches path. Query parameters are not included. [true | false]

open

Open the link in the same tab or redirect. [tab | redirect]

permissions

Comma-separated list of permissions associated with the path. An end user only sees this item if the permissions match.

tags

Comma-separated list of tags. This adds a visibility layer to the sidebar. An end user only sees this item if the tags match. See also here.

Here is an example of a menu and its items.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <body>
    <section text="">
      <menu 
        label="Reports" 
        defaultShow="true" 
        icon="chart-bar" 
        iconFaType="duotone" 
        iconFaStyle="solid">
        <menuitem 
          label="Sales Report" 
          path="/app/data-analysis/reports/" 
          exact="true" 
          open="redirect"/>
        <menuitem 
          label="Inventory Report"
          path="/app/data-analysis/reports/" 
          exact="false" 
          open="tab"/>
        <menuitem 
          label="Customers Report" 
          path="/app/data-analysis/reports/" 
          exact="false" 
          open="tab"/>
      </menu>
    </section>
  </body>
</tree>

link

This element creates direct links within the sidebar or static asidepanel.

These are the attributes of the link element:

Attribute

Description

label

Label of the link.

panelTarget

ID of the asidepanel. If present, path is ignored.

path

Redirection path (see available paths here) or URL.

icon

Name of an icon from Font Awesome.

iconFaType

Font Awesome type. [duotone | classic]

iconFaStyle

Font Awesome style. [solid | regular | light | thin]

exact

Highlights the link when the current path exactly matches path. Query parameters are not included. [true | false]

open

Open the link in the same tab or redirect. [tab | redirect]

permissions

Comma-separated list of permissions associated with the path. An end user only sees this link if the permissions match.

tags

Comma-separated list of tags. This adds a visibility layer to the sidebar. An end user only sees this link if the tags match. See also here.

Here is an example of consecutive link elements.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <body>
    <section text="Main Navigation">
      <link 
        label="Dashboards" 
        path="/app/dashboards/" 
        icon="objects-column" 
        iconFaType="classic" 
        iconFaStyle="solid" 
        exact="true" 
        open="redirect"/>
      <link 
        label="Reports" 
        path="/app/data-analysis/" 
        icon="newspaper" 
        iconFaType="duotone" 
        iconFaStyle="regular" 
        exact="false" 
        open="tab"/>
      <link 
        label="Settings" 
        path="/accounts/me/" 
        icon="gear" 
        iconFaType="classic" 
        iconFaStyle="light" 
        exact="true" 
        open="tab"/>
    </section>
  </body>
</tree>

text

Creates texts within the sidebar or static asidepanel.

These are the attributes of the text element:

Attribute

Description

type

Text type. [h1 | h2 | h3 | h4 | normal | bold]

Here is an example of consecutive text elements with different types.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <body>
    <section text="Text Samples">
      <text type="h1">This is a Heading 1</text>
      <text type="h2">This is a Heading 2</text>
      <text type="h3">This is a Heading 3</text>
      <text type="h4">This is a Heading 4</text>
      <text type="normal">This is normal body text</text>
      <text type="bold">This is bold text</text>
    </section>
  </body>
</tree>

divider

This element simply creates a horizontal line for visual separation. It does not have any attributes.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <body>
    <section text="Quick Menu">
      <link label="Home" path="/app/dashboards/" icon="home" iconFaType="classic" iconFaStyle="solid"/>
      <divider/>
      <link label="Profile" path="/accounts/me/" icon="user" iconFaType="duotone" iconFaStyle="regular"/>
    </section>
  </body>
</tree>

Permissions

Elements that support the permissions attribute only appear to end users whose assigned permissions match the element configuration.

The available permissions for each possible path that's exposed to the 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

Elements that receive the tags attribute add 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 element (learn more about tag filtering). If at least one tag matches, the element is visible to the user.

This tag-based 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, you can use XML like this:

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu App XML V2.0//EN' "-">
<tree>
  <body>
    <section text="User Homes">
      <!--This link creates Home for User 1-->
      <link 
        label="Home"
        path="/app/dashboards/663d484aaa8d92005751b2e2" 
        icon="home" 
        iconFaType="classic" 
        iconFaStyle="solid"
        open="tab" 
        exact="true" 
        permissions="ubi_dashboards.view_dashboardpg"
        tags="tag1"/>

      <!--This link creates Home for User 2-->
      <link 
        label="Home"
        path="/app/dashboards/663d484aaa8d92007364jnhd" 
        icon="home" 
        iconFaType="classic" 
        iconFaStyle="solid"
        open="tab" 
        exact="true" 
        permissions="ubi_dashboards.view_dashboardpg"
        tags="tag2"/>
    </section>
  </body>
</tree>

Assume two end users, with tags tag1 and tag2, respectively. The XML includes two Home links. 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:

PreviousCustom sidebar menu

NextXML v1.0 (deprecated)

Last updated 4 months ago

Was this helpful?

XML Syntax

tree

asidepanel

body

home

section

menu and item

Attributes by element

link

text

divider

Permissions

Filter elements by tags