`. 5. `

` must have at least 1 `` or ``. 6. `` must have at least 1 ``. 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`: ```xml ``` ### asidepanel This element creates a static or dynamic, user-aware content asidepanel. {% hint style="info" %} * 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](https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html) expressions. This is used to parse the response when the asidepanel loads dynamic content from an HTTP request. {% endhint %} 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](#permissions) and [tags](#filter-elements-by-tags) aren't used in these examples, so refer to the respective sections to learn more about these 2 attributes. {% tabs %} {% tab title="Static asidepanel" %} 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: ```xml

Static panel with links and menus to resources

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

{% endtab %} {% tab title="Dynamic asidepanel" %} This XML creates a dynamic-content asidepanel. In this mode, the asidepanel loads its user-aware content from an HTTP request, in this case to Ubidots dashboards API endpoint; Nonetheless, this could also be the URL from an [UbiFunction](https://dev.ubidots.com/ubifunctions) where custom logic is applied based on the user that's loading the asidepanel. It then uses its JSONPath enabled attributes to parse the response and render the asidepanel. ```xml

``` This will create a dynamic asidepanel as follows. The `menuitem` option "Custom dashboards" in the sidebar invokes the HTTP to "/api/v2.0/dashboards/" and renders the dynamic content parsing the response with the respective attributes.

{% endtab %} {% endtabs %} ### body Element wrapping the content of the sidebar. {% hint style="info" %} * The `body` must have at least 1 `section` element. * The `body` element may have 0 or more `home` elements. {% endhint %} ```xml ``` ### 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. {% hint style="info" %} * 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. {% endhint %} 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. ```xml

``` ### 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. {% hint style="info" %} * The `section` must contain at least one `menu`, `link`, `divider` or `text` element. * The "text" attribute is mandatory. . {% endhint %} 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. {% columns %} {% column width="58.333333333333336%" %} ```xml

``` {% endcolumn %} {% column width="41.666666666666664%" %}

{% endcolumn %} {% endcolumns %} ### menu and item These 2 elements help create menus within the sidebar or static asidepanel. {% hint style="info" %} * 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. {% endhint %} #### Attributes by element {% tabs %} {% tab title="menu" %}

Attribute	Description
label	Label of the menu.
defaultShow	Determines whether the dropdown is open or closed when loading the app. [true \| false]
icon	Name of icon from Fontawesone.
iconFaType	Fontawesome type. [duotone \| classic]
iconFaStyle	Fontawesome style. [solid \| regular \| light \| thin]

{% endtab %} {% tab title="item" %}

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 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 item 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 item if its tags match. See also here.

{% endtab %} {% endtabs %} Here's an example of a `menu` and its `items`. {% columns %} {% column width="50%" %} ```xml

``` {% endcolumn %} {% column width="50%" %}

{% endcolumn %} {% endcolumns %} ### 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 {% columns %} {% column %} ```xml

``` {% endcolumn %} {% column %}

{% endcolumn %} {% endcolumns %} ### 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 {% columns %} {% column width="58.333333333333336%" %} ```xml

This is a Heading 1 This is a Heading 2 This is a Heading 3 This is a Heading 4 This is normal body text This is bold text

``` {% endcolumn %} {% column width="41.666666666666664%" %}

{% endcolumn %} {% endcolumns %} ### divider Simply creates a horizontal line that introduces intentional separation. This element does not have any attributes {% columns %} {% column %} ```xml

``` {% endcolumn %} {% column %}

{% endcolumn %} {% endcolumns %} ## 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](https://help.ubidots.com/en/articles/8063141-ubidots-basics-tags)). 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: ```xml

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