Lesson 2. Dashboard States & Navigation

Dashboard states enable multi-level navigation within a single dashboard. Each state is a separate view scoped to an entity selected in the previous level. This lesson adds building and office states with drill-down navigation from buildings to offices to devices.

1. Open the Buildings dashboard and enter edit mode.
2. Click the States icon in the upper-left corner.
3. Click + (Add dashboard state) and add a state: name ${entityName}, state ID building.
4. Click + again and add: name ${entityName}, state ID office.
5. Click Save.

The special ${entityName} variable makes state names dynamic — at runtime it’s replaced with the entity name that triggered navigation.

Click "Edit mode" to start editing the dashboard Open the "States" section Click "+" to add a new dashboard state Configure the "building" state using ${entityName} Repeat the process to create another state Configure the "office" state using ${entityName} Verify that all states are created. Click "Save" to persist the changes Save" the dashboard

Connect the default state to the building state via a Tooltip tag action on the map widget and an On row click action on the Buildings list.

1. Enter edit mode and click the pencil icon on the Map widget.

2. In the Overlays section, click the marker configuration button.

3. In the Tooltip section, click the fullscreen button to open the tooltip function editor.

4. And add the link-act tag to the tooltip function to display the Details > action button:

   + '<div style="text-align:center;background:var(--tb-primary-50, #87ceeb);border-radius:6px">' +
       '<link-act name="building_details">Details ></link-act>' +
   '</div>'

   Reference (full tooltip function after modification):

   const address = data.address ? data.address : 'N/A';
   const email = data.email ? data.email : 'N/A';
   const phone = data.phone ? data.phone : 'N/A';
   const buildingImage = data.buildingImage ? data.buildingImage : '';
   return '<div style="display:flex;flex-direction:column;font-family:\'Roboto\';font-weight:500;font-size:14px;line-height:24px;letter-spacing:0.25px;color:#29313C;margin-bottom:5px">' +
              (buildingImage ? `<img style="width: 300px; height: auto" src=${buildingImage}>` : '') +
              '<div style="margin-top:5px;">${entityName}</div>' +
              '<div style="display:flex;flex-direction:row;align-items:center;justify-content:space-between;gap:10px">' +
                  '<div style="font-size:11px;line-height:16px;font-weight:500;color:rgba(0,0,0,0.38);">Address</div>' +
                  '<div style="font-size:12px;line-height:20px;font-weight:500;color:#29313C;text-align:right;">' + address + '</div>' +
              '</div>' +
              '<div style="display:flex;flex-direction:row;align-items:center;justify-content:space-between;gap:10px">' +
                  '<div style="font-size:11px;line-height:16px;font-weight:500;color:rgba(0,0,0,0.38);">Email</div>' +
                  '<div style="font-size:12px;line-height:20px;font-weight:500;color:#29313C;text-align:right;">' + email + '</div>' +
              '</div>' +
              '<div style="display:flex;flex-direction:row;align-items:baseline;justify-content:space-between;gap:10px">' +
                  '<div style="font-size:11px;line-height:16px;font-weight:500;color:rgba(0,0,0,0.38);">Phone</div>' +
                  '<div style="font-size:12px;line-height:20px;font-weight:500;color:#29313C;text-align:right;">' + phone + '</div>' +
              '</div>' +
          '</div>' +
          '<div style="text-align:center;background:var(--tb-primary-50, #87ceeb);border-radius:6px">' +
              '<link-act name="building_details">Details ></link-act>' +
          '</div>';

   In edit mode, click the edit button on the map widget. In the Advanced tab, in the Overlays section, click the marker configuration button. In the Tooltip section, keep the Function tab selected and click the fullscreen button to open the tooltip function editor. Add the link-act tag to the tooltip function to display the Details > action button.

5. In the Tag actions section, click the Add tag action button. Configure the action:

   • Name it building_details.
   • Set Action to Navigate to new dashboard state
   • Specify Target dashboard state to building.
   • Click Add.

6. Save the marker configuration and apply the changes to the widget and dashboard.

In the Tag actions section, click the Add tag action button. Configure the action: set the name to building_details, select Navigate to new dashboard state, and specify the target state building. Click Add. Verify that the building_details action has been added in the Tag actions section. Click Save Click Apply to save the widget changes. Save the dashboard to apply all changes.

Click a marker to open the tooltip and use the Details > link. You are redirected to the Building A dashboard state.

Click a marker to open the tooltip and use the Details > link. You are redirected to the Building A dashboard state.

1. With the default Buildings state active, click the pencil icon on the Buildings list widget.
2. Scroll to Actions and click Add action.
3. Click +.
4. Set source to On row click, enter an action name (e.g., go_to_building).
5. Set type to Navigate to new dashboard state and select building.
6. Click Add, review, then click Save.
7. Click Apply, then save the dashboard.

Click Buildings in the breadcrumb to return to the default state. Click Edit mode to modify the dashboard. Click the pencil icon to edit the Buildings list widget. Scroll down to the Actions section, and click Add action Click the + (Add action) button to add a new action. Configure the action: On row click ⇾ Navigate to new dashboard state (building). Click Add. Click Save. Apply changes. Save the dashboard.

Click a building row to test navigation.

Click a building row to test navigation The row click action navigates to the selected building state Click another row (e.g., Building B) to verify behavior Navigation works consistently for all entities in the list

Add a background image, building info card, focused map widget, and offices list to the building state.

1. Navigate to the state of Building A.
2. Enter edit mode and click the Manage layouts.
3. Click the gear icon to open layout settings.
4. Scroll to Background image and click Browse from gallery.
5. Download the sample building background.
6. Click Upload image, drop or browse the image, then click Upload.
7. Select the uploaded image and click Apply.
8. Click Save, then save the dashboard.

Navigate to the state of Building A. Enter edit mode and click the Layouts. In the Manage layouts dialog, click the gear icon. In the Layout settings dialog, click Browse from gallery. In the Image gallery, click Upload image. Upload an image and click Upload. Click Save. Save changes. The background image is applied to the layout. Save dashboard.

The Markdown/HTML Card widget displays entity attributes using custom HTML. Configure it with the Selected entity alias (from dashboard state) and render building address, contact person, phone, and email.

Datasource:

1. In the building state (edit mode), click Add widget.
2. Select Cards ⇾ Markdown/HTML Card.
3. Create the new entity alias:
   • Type Selected entity in the alias field and click Create a new one!
   • Set filter type to Entity from dashboard state and click Add.
4. Add data keys: address, contactPerson, email, phone.
   Enter edit mode and click the “Add widget” button or the “Add new widget” placeholder In the widget selection dialog, open the “Cards” bundle and select the “Markdown/HTML Card” widget In the “Data” tab, enter an alias name (e.g., “Selected entity”) and click “Create a new one” In the “Add alias” dialog, set the filter type to “Entity from dashboard state” and click “Add” Add required data keys (e.g., address, contactPerson, email, phone) to the selected entity datasource

5. Appearance tab. Enable Use markdown/HTML value function and paste:

   if (data.length) {
       const attributes = ['address', 'contactPerson', 'phone', 'email'];
       let info = {
           entityName: data[0].entityName || 'Not found',
           fields: {}
       };
   
       attributes.forEach(key => {
           info.fields[key] = data[0][key] || 'Not found';
       });
   
       const allMissing = Object.values(info.fields).every(v => v === 'Not found');
   
       if (allMissing) {
           return `<div class="no-data-card"><h1 class="card-title">Information on ${info.entityName}</h1>
                   <div class="no-data-block"><div class="no-data-content">
                   <p class="no-data-title">No building information available</p></div></div></div>`;
       }
   
       const icons = { address: 'place', contactPerson: 'person', phone: 'call', email: 'mail_outline' };
       const labels = { address: 'Address', contactPerson: 'Contact person', phone: 'Phone', email: 'Email' };
   
       let html = `<div class="card"><h1 class="card-title">Information on ${info.entityName}</h1><div class="attributes">`;
   
       attributes.forEach(key => {
           html += `<div class="attribute_container">
                    <div class="icon_wrapper"><tb-icon class="icon" color="primary" matButtonIcon>${icons[key]}</tb-icon></div>
                    <div class="attribute_content"><p class="attribute">${info.fields[key]}</p>
                    <span class="attribute_label">${labels[key]}</span></div></div>`;
       });
   
       return html + '</div></div>';
   }

   In the Markdown/HTML CSS section, paste:

   .card, .no-data-card {
       padding: 0px;
       height: 100%;
   }
   .card-title {
       position: sticky;
       top: 0;
       z-index: 2;
       font-size: 16px;
       letter-spacing: 0.25px;
       padding: 16px;
   }
   .attribute_container {
       display: flex;
       align-items: center;
       gap: 20px;
       padding: 16px;
       border-bottom: 1px solid #0000000d;
   }
   .icon_wrapper {
       display: flex;
       position: relative;
       align-items: center;
       padding: 8px;
       border: 1px solid var(--tb-primary-100, #305680);
       border-radius: 4px;
   }
   .icon_wrapper:before {
       content: '';
       z-index: 0;
       position: absolute;
       opacity: 0.1;
       background-color: var(--tb-primary-200, #305680);
       width: 100%;
       height: 100%;
       left: 0;
       top: 0;
   }
   .icon {
       z-index: 1;
   }
   .attribute, .attribute_label {
       font-size: 14px;
       line-height: 20px;
   }
   .attribute_label {
       color: #00000061;
   }
   .no-data-card {
       display: flex;
       flex-direction: column;
   }
   .no-data-block {
       display: flex;
       flex-direction: column;
       justify-content: center;
       height: 100%;
       max-width: 345px;
       padding: 0 15px;
       margin: 0 auto;
       text-align: center;
   }
   .no-data-content {
       transform: translateY(-30%);
   }
   .no-data-title {
       color: rgba(0, 0, 0, 0.54);
       font-weight: 500;
   }

   

7. Widget card tab. Disable Enable fullscreen and Enable data export, then click Add. Resize and position on the left side:
8. Resize and position on the left side and save dashboard.

In the "Widget card" tab, disable the "Enable fullscreen" and "Enable data export" options, then click "Add" Resize the widget as needed and click "Save" to apply the changes

Copy the Map widget from the default state and re-point it to the Selected entity alias to show only the currently selected building.

1. Navigate to the default Buildings state, enter edit mode, right-click the Map widget, and select Copy.
2. Navigate to the building state, right-click an empty area, and select Paste.
3. Click the pencil icon on the pasted widget.
4. In Datasource, change the alias from Buildings to Selected entity.
5. Go to Appearance, find Tooltip, and remove the <link-act> lines (no deeper navigation needed here).
6. Click Apply, position in the upper-right area, and save the dashboard.

Enter edit mode for the “Default” state. Right-click on the Map widget to open the widget context menu and click “Copy” Switch to the “building” state, open the context menu, and click “Paste” Click the edit (pencil) icon on the pasted widget In the "Overlays" section, click the marker configuration button In the datasource, change the entity alias to "Selected entity" In the "Tooltip" section, click the fullscreen button to open the tooltip function editor. In the tooltip configuration, remove the “link-act” section from the function code Final function code Save marker configuration Apply changes Place the widget in the upper-right corner of the dashboard and adjust its size. Save the dashboard

Select a building from the list to verify navigation The building state displays the information card and a map centered on the selected entity

Use an Entities table widget with Asset search query alias type to list all offices related to the currently selected building.

1. In the building state (edit mode), click + Add widget.
2. Select Tables ⇾ Entities table.
3. Create the new entity alias:
   • Type Building offices in the alias field and click Create a new one!
   • Set filter type to Asset search query.
   • Enable Use dashboard state entity as root.
   • Set Max relation level to 1, relation type to Contains, asset type to office.
   • Click Add.
4. Add data keys: floor, phone.
5. Set card title to Offices list and uncheck all card buttons except Search.
6. Click Add, resize below the info card, and save the dashboard.

Click the “Add widget” button In the widget selection dialog, open the “Tables” bundle and select the “Entities table” widget In the “Data” tab, enter an alias name (e.g., “Building offices”) and click “Create a new one” Configure the alias: select “Asset search query”, enable “Use dashboard state entity as root”, set relation type to “Contains”, and specify asset type “office” Add required columns, such as “floor” and “phone” In the “Appearance” tab, set the card title (e.g., “Offices list”) and configure the required card buttons Position the widget as needed and click “Save” The widget displays a list of offices with their attributes (e.g., floor and phone)

Add a background image, office info card, Image Map widget, and sensors list to the office state.

Add an On row click action to the Offices list widget to navigate to the office state.

1. On the building state and enter edit mode.
2. Click the pencil icon on the Offices list widget.
3. Scroll to Actions and click Add action.
4. Click +.
5. Set source to On row click, enter an action name (e.g., go_to_office).
6. Set type to Navigate to new dashboard state and select office.
7. Click Add, then Save.
8. Click Apply, then save the dashboard.

On the "building" state and enter edit mode. Open the Offices list widget settings In the “Actions” section, click “Add action” Click the add (+) button to create a new action Configure the action: set “On row click” and select “Navigate to new dashboard state” with target state “office” Click “Save” to add the action Click “Apply” to save widget changes Save the dashboard

Open the Office A state by clicking it in the Office list widget.

Click Office A in the Offices list Office A state opened — breadcrumb confirms navigation

1. Download the sample office floor plan.
2. Select the office state from the toolbar state selector.
3. Enter edit mode, click Manage layouts ⇾ gear icon.
4. Click Browse from gallery, upload your floor plan, select it, and click Apply.
5. Click Save, then save the dashboard.

The office info card displays office attributes (floor, officeManager, phone, email) from the selected entity and the parent building’s address via a Relation type alias.

Datasources:

1. In the office state (edit mode), click Add widget and select Markdown/HTML Card from Cards bundle.
2. Add first datasource:
   • Set Selected entity alias.
   • Specify data keys: floor, officeManager, phone, email.
3. Add second datasource:
   • Type Entity with relation to dashboard state (asset) in the alias field and click Create a new one!
   • Set filter type to Relation type, enable Use dashboard state entity as root.
   • Set direction to To, max relation level to 1.
   • Add relation filter: type Contains, entity type Asset.
   • Click Add.
   • Add key address to this second datasource.

4. Appearance tab. Enable Use markdown/HTML value function and paste:

   // data[0] = Selected entity (office), data[1] = parent building (via Relation type alias)
   if (data.length > 1) {
       const officeAttrs = ['floor', 'officeManager', 'phone', 'email'];
       const icons = { floor: 'mdi:floor-plan', officeManager: 'person', phone: 'call', email: 'mail_outline' };
       const labels = { floor: 'Floor', officeManager: 'Office manager', phone: 'Phone', email: 'Email' };
   
       let info = {
           entityName: data[0].entityName || 'Not found',
           address: data[1].address || 'Not found',
           fields: {}
       };
   
       officeAttrs.forEach(key => {
           info.fields[key] = data[0][key] || 'Not found';
       });
   
       const allMissing = Object.values(info.fields).every(v => v === 'Not found') && info.address === 'Not found';
   
       if (allMissing) {
           return `<div class="no-data-card"><h1 class="card-title">Information on ${info.entityName}</h1>
                   <div class="no-data-block"><div class="no-data-content">
                   <p class="no-data-title">No office or building address information available</p></div></div></div>`;
       }
   
       let html = `<div class="card"><h1 class="card-title">Information on ${info.entityName}</h1><div class="attributes">
                   <div class="attribute_container">
                   <div class="icon_wrapper"><tb-icon class="icon" color="primary" matButtonIcon>place</tb-icon></div>
                   <div class="attribute_content"><p class="attribute">${info.address}</p>
                   <span class="attribute_label">Address</span></div></div>`;
   
       officeAttrs.forEach(key => {
           html += `<div class="attribute_container">
                    <div class="icon_wrapper"><tb-icon class="icon" color="primary" matButtonIcon>${icons[key]}</tb-icon></div>
                    <div class="attribute_content"><p class="attribute">${info.fields[key]}</p>
                    <span class="attribute_label">${labels[key]}</span></div></div>`;
       });
   
       return html + '</div></div>';
   }

5. Use the same CSS from the building info card in the Markdown/HTML CSS section.

   .card, .no-data-card {
     padding: 0px;
     height: 100%;
   }
   
   .card-title {
     position: sticky;
     top: 0;
     z-index: 2;
     font-size: 16px;
     letter-spacing: 0.25px;
     padding: 16px;
   }
   .attribute_container {
     display: flex;
     align-items: center;
     gap: 20px;
     padding: 16px;
     border-bottom: 1px solid #0000000d;
   }
   
   .icon {
     z-index: 1;
   }
   
   .icon_wrapper {
     display: flex;
     position: relative;
     align-items: center;
     padding: 8px;
     border: 1px solid var(--tb-primary-100, #305680);
     border-radius: 4px;
   }
   
   .icon_wrapper:before {
     content: '';
     z-index: 0;
     position: absolute;
     opacity: 0.1;
     background-color: var(--tb-primary-200, #305680);
     width: 100%;
     height: 100%;
     left: 0;
     top: 0;
   }
   
   .attribute, .attribute_label {
     font-size: 14px;
     line-height: 20px;
   }
   
   .attribute_label {
     color: #00000061;
   }
   
   .no-data-card {
     display: flex;
     flex-direction: column;
   }
   
   .no-data-block {
     display: flex;
     flex-direction: column;
     justify-content: center;
     height: 100%;
     max-width: 345px;
     padding: 0 15px;
     margin: 0 auto;
     text-align: center;
   }
   
   .no-data-content {
     transform: translateY(-30%);
   }
   
   .no-data-block p {
     font-weight: 500;
   }
   
   .no-data-title {
     color: rgba(0, 0, 0, 0.54);
   }
   
   .no-data-subtitle {
     font-size: 13px;
     color: rgba(0, 0, 0, 0.38);
   }

6. Widget card tab. Enable fullscreen and data export, then click Add.
7. Resize and save the dashboard.

Enter edit mode and click “Add widget” Select the “Markdown/HTML Card” widget from the Cards bundle Configure the first datasource using the “Selected entity” with required data keys Create a second datasource using an entity alias based on dashboard state relations Type "Entity with relation to dashboard state (asset)" in the alias field and click "Create a new one!" Configure the relation query: use dashboard state as root Direction “To”, max level 1. Add a relation filter: type “Contains”, entity type “Asset”. Click "Add" Add the “address” data key to the second datasource Appearance tab. Enable the value function and add JavaScript and CSS Disable fullscreen and data export, then click “Add” Resize the widget and save the dashboard Result: the office information card displays all attributes

The Image Map widget places device markers on a custom floor plan using percentage-based X/Y coordinates (0–1) stored as entity attributes.

The coordinates used to determine device positions on the floor plan were defined during devices creation as the xPos and yPos attributes.

1. Download the sample office floor plan.
2. Go to Resources ⇾ Image gallery and click Upload image.
3. Upload the office floor plan.
4. Copy the Embed image link — you’ll need it for the widget background.

In Resources → Image gallery, click "Upload image", select the office plan file, and click Upload In the Image gallery table, locate the uploaded image and click the "Embed image" action In the Embed image dialog, copy the image URL for further use in widgets or HTML content

5. Go to Entities ⇾ Assets, and select Office A.
6. Navigate to the Attributes.
7. Click +.
8. Name it office-plan, choose String as the value type, and paste the previously copied link into the value field.
9. Click Add.

In the "Office A" asset details, open the Attributes tab, click "+" Add the "office-plan" attribute with the image URL as the value Verify that the "office-plan" attribute has been successfully added to the asset

Similarly, upload the Office B plan image to the Image gallery, and add a link to it for “Office B” asset as a server attribute. Use the provided Office B plan image or upload your own image.

1. In the office state (edit mode), click + Add widget.
2. Select the Maps ⇾ Image Map.
3. Set the office plan image as widget background:
   • Go to Appearance ⇾ Image source.
   • Switch to the Entity key.
   • Set source entity alias to Selected entity alias.
   • Set image URL key to office-plan attribute.
4. Create the new entity alias:
   • Click Add marker
   • Type Office devices and click Create a new one!
   • Set filter type to Device search query.
   • Enable Use dashboard state entity as root.
   • Set Max relation level to 1, relation type to Contains.
   • List the following device types: air-sensor, energy-sensor, and water-sensor.
   • Click Add.
5. Open marker configuration and verify that the marker uses the Office devices alias and:
   • xPos/yPos is set as the coordinate key
   • type is set as the additional data key

In the office state (edit mode), click “Add widget” in the dashboard toolbar elect the "Maps" ⇾ "Image Map" "Image source" section. Set the office plan image as widget background "Overlays" ⇾ "Markers". Click "Add marker". Enter a marker source alias and click “Create a new one” Configure the alias using device search query and root entity settings Set relation filter and select required device profiles. Click "Add" Open "Marker configuration" Add additional data key (e.g., “type”)

Appearance tab:

6. Use the function to display a marker image with the corresponding index, depending on the device type:
   • Upload marker images for each device type (Download image markers: air, energy, water)
   • Add Marker image function
   • Click Apply

Configure marker appearance and adjust marker offset if needed Switch to “Function” mode and define marker image logic based on data keys Add marker images and map them to device types, then click “Apply”

7. Configure labels:
   • Paste the label HTML:

<div style='position: relative; white-space: nowrap; text-align: center; font-size: 14px; top: 2px;'><span style='margin-left: -500%;'></span><div style='border: 2px solid #00695c; border-radius: 10px; color: #000; background-color: #fff; padding-left: 12px; padding-right: 12px; padding-top: 4px; padding-bottom: 4px;'>${entityLabel}</div></div>

8. Configure tooltip:
   • Keep only ${entityName}.

Widget card tab:

9. Set card title to Office plan.

10. Go to Advanced widget style → Widget CSS and paste:

    .leaflet-tooltip-pane .leaflet-tooltip-top {
      opacity: 1 !important;
    }

11. Uncheck Enable data export in Card buttons.
12. Click Add.

Set the widget title to "Office plan" in the Widget card tab Scroll down to Advanced widget style and review or edit Widget CSS. Click "Add" to save the widget View it on the dashboard. Adjust the size of the Image Map widget on the dashboard

13. Resize the widget to the right corner.
14. Go to Layout settings and enable Auto fill layout height.
15. Save the dashboard.

Open "Manage layouts" from the dashboard toolbar Click the settings icon to open layout settings Enable "Auto fill layout height". Click "Save" to apply the layout changes Click "Save" to apply layout changes. Save the dashboard

A widget has been added that displays the plan of the selected office and the placement of devices on it.

Verify that markers are displayed correctly for Office A Switch to Office B and verify that markers update correctly

Add an Entities table widget to list all devices in the currently selected office.

1. In the office state (edit mode), click + Add widget.
2. Select Entities table from the Tables bundle.
3. Reuse the Office devices alias.
4. Set card title to Office sensors list.
5. Click Add, resize alongside the Image Map, and save the dashboard.

Click "+ Add widget" in the dashboard toolbar Select "Entities table" in the "Tables" widget bundle Select the "Entity alias" datasource and choose "Office devices" Set the widget title to "Office sensors list" Add the widget to the dashboard and save changes

The configured “office” state should look like this:

Default state — displays all buildings and map overview Building state — shows building details and list of offices Office state — displays office details, sensors, and floor plan Office state (Office B) — displays office details and IAQ sensor location

Hierarchy & Context: Use dashboard states to create drill-down hierarchies (Buildings → Offices ⇾ Devices). Each state should narrow the entity context, reducing data and improving readability.

Entity from Dashboard State: This alias type automatically binds widgets to the currently selected entity in the state. Use it for re-focused views (e.g., map showing only the selected building).

Asset Search Query: Combine with Use dashboard state entity as root and relation filters to fetch related entities. Set Max relation level carefully—level 1 gets direct children; higher levels traverse further.

Relation Type: Use to fetch parent or cross-referenced entities (e.g., building address from an office state). Set direction To to traverse backward through relations.

Smart Aliases & Navigation: Name aliases clearly (Selected entity, Building offices, Office devices). Avoid hardcoding entity IDs—use aliases to make widgets reusable across states.

Widget Reuse: Copy widgets between states, then re-point aliases. Extract common layout patterns (card + map + list) to reduce repetition.