Help CenterAPI ReferenceData APICommunity

XML v2.0

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

As seen in the previous section, Custom sidebar, XML v2.0 introduces a more modular and dynamic structure to the sidebar. The root <tree> now divides content into an optional set of asidepanel elements and a body, each with their own sections. The enhanced asidepanel supports dynamic content loaded via HTTP requests and JSONPath parsing, enabling a more flexible and user-aware sidebar.

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

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 XML V2.0//EN' "-">.

  2. The <tree> element is mandatory. It must have at least 1 <body> element. <asidepanel> is optional and there can be as many as needed.

  3. <asidepanel> can be static or dynamic, in which case the contents are loaded through HTTP and parse based on the element attributes.

  4. The <body> must have at least 1 <section>.

  5. <section> must have at least 1 <menu> or <link>.

  6. <menu> must have at least 1 <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.

–

asidepanel

Allows creating static or dynamic asidepanels. This is an optional element within <tree>

  • id: Used to associate the asidepanel with a <link> or <item>

  • source: Path or URL from which dynamic content will be retrieved using HTTP.

  • query: JSONPath expression to parse the response from source.

  • path: This is the dynamic path template for each option in the asidepanel. It supports JSONPath.

  • label: This is how the dynamic option will be shown in the asidepanel. It supports JSONPath.

  • text: Title of the asipanel when open. It supports JSONPath.

  • permissions: List of end-user permissions under which the asidepanel content will be visible.

  • tags: List of end-user tags under which the asidepanel content will be visible.

body

Wraps all the content of the sidebar.

–

home

This element controls the path or URL when clicking the application logo.

  • path: This the path or URL when clicking the logo.

  • permissions: List of end-user permissions under which the home path will be applied.

  • tags: List of end-user tags under which the home path will be applied.

section

Wraps all 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.

menu

This is the dropdown menu.

  • defaultShow: [true | false] Determines whether the dropdown is open or closed when loading the app.

  • icon: Name of icon from Fontawesone.

  • iconFaType: [duotone | classic] Fontawesome type.

  • iconFaStyle: [solid | regular | light | thin] Fontawesome style.

  • label: Title of the menu

item

Actual options displayed under a dropdown menu.

  • panelTarget: ID of the asidepanel. If present, path is ignored.

  • path: Where the item redirects to upon clicking.

  • label: Title of the item.

  • open: Open link in same "tab" or "redirect".

  • exact: highlights the menulink when in the exact path defined by path.

  • permissions: List of end-user permissions under which the item will be visible.

  • tags: List of end-user tags under which the item will be visible.

link

Creates direct access to links.

  • panelTarget: ID of the asidepanel. If present, path is ignored.

  • path: Where the link redirects to upon clicking.

  • label: Title of the link.

  • icon: Name of icon from Fontawesone.

  • iconFaType: [duotone | classic] Fontawesome type.

  • iconFaStyle: [solid | regular | light | thin] Fontawesome style.

  • open: Open links in same tab or redirect.

  • exact: Highlights the menulink when in the exact path defined by path.

  • permissions: List of end-user permissions under which the link will be visible.

  • tags: List of end-user tags under which the link will be visible.

text

Creates text of different sizes. It helps in creating defined sections in the sidebar.

  • type: Determines the size. It can be "h1", "h2", "h3", "h4", "normal" or "bold".

divider

Creates horizontal lines that serve as section separation.

–

tree

Parent element wrapping the body and the optionals asidepanel:

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

asidepanel

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

  • Note that asidepanel can only be opened from a link or item element within a body section.

  • A dynamic asidepanel panel has precedence over a static one, that is, if the "source" and "path" attributes are set, all elements inside the asidepanel will be ignored.

  • Some attributes used in asidepanel support JSONPath expressions. This is 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

id

Used to associate the asidepanel with the respective link or item elements from which the asidepanel will be invoked.

source

Ubidots API endpoint path or external URL from which the content of the asidepanel will be retrieved dynamically through and HTTP request.

text

This is the title of the asidepanel. It supports JSONPath expressions so it can change dynamically based on the HTTP request response to "source".

query

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

label

JSONPath expression used to select displaying label of the options in the asidepanel. This expression is evaluated over each list element from the "query" output.

path

JSONPath expression used to build the path that each option will redirect to upon clicking. This expression is evaluated over each list element from the "query" output.

permissions

Comma separated list of permissions associated with the path. An end user will only see the content of the asidepanel if its permissions match.

tags

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

In the below 2 tabs are examples of how a static and a dynamic asidepanel look like, both in terms of XML code and UI. For simplicity, permissions and tags aren't used in these examples, so refer to the respective sections to learn more about these 2 attributes.

This XML creates a fixed content asidepanel. In this mode, the asidepanel acts similarly to a body element, receiving section, link, menu and 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 will create a static asidepanel as follows. The options "Aside static" in the sidebar are, from top to bottom, the link and a item found in the body section.

body

Element wrapping the content of the sidebar.

  • The body must have at least 1 section element.

  • The body element may have 0 or more home elements.

<!DOCTYPE tree PUBLIC '-//UBIDOTS//DTD Menu XML V2.0//EN' "-">
<tree>
  <!--Your optionals asidepanel elements go here-->
  <body>
    <!--Your sections and optionals 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 seen dashboard, nonetheless, by configuring this element, you can control the path or URL when clicking the application logo by user, using permissions and tags.

  • As an end-user, if the result of the permissions and tags filtering renders multiple home elements for that user, then clicking the logo takes 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 will only see the effect of the home element if its permissions match.

tags

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

The example below shows 2 home elements, each takes to a different dashboard. Note that by using tags, one is shown to User1, the other to User2 because the respective tags. 

<!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/Title of the section. It can be left empty, that is text=""

permissions

Comma separated list of permissions associated with the path. An end user will only see the section if its permissions match.

tags

Comma separated list of tags. This adds a visibility layer to the sidebar. An end user will only see the section if its 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>

menu and item

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

  • A menu must have at least 1 item.

  • As an end-user, if the result of the permissions and tags filtering renders an empty menu, then the menu won't be visible.

Attributes by element

Here's 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 menu.

panelTarget

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

path

Redirection path (see available paths here) or URL.

icon

Name of icon from Fontawesone.

iconFaType

Fontawesome type. [duotone | classic]

iconFaStyle

Fontawesome style. [solid | regular | light | thin]

exact

Highlights the item when in the exact path defined by path. It doesn't include the query parameters. [true | false]

open

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

permissions

Comma separated list of permissions associated with the path. An end user will only see this link if its permissions match.

tags

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

Here's 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:

Attributes
Description

type

Type of text [h1 | h2 | h3 | h4 | normal | bold]

Here's 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

Simply creates a horizontal line that introduces intentional separation. This element 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

The elements that support the permissions attribute will only appear to those end users whose assigned permissions match those of 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

The elements that receive the "tag" attribute add 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 respective element (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 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>

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:

PreviousCustom sidebarNextXML v1.0 (deprecated)

Last updated

Was this helpful?