Tree View Widget
Tree View is a Type Widget display option that shows records and their related records as an expandable hierarchy. Each row has an arrow to show its children. Columns line up across every level. Use it when the relationships matter more than a flat list, for example Factory → Project → Building or Department → Employee.
Overview
A Tree View widget is an ordinary Type Widget with Show As set to Tree View. Unlike a grid, it doesn't use a Query Definition. You write an OData query instead, and its $expand clauses define the levels of the tree.
| I want to... | Widget Category | Placed on | Top-level rows are |
|---|---|---|---|
| Browse every record of a type with its related records underneath it | Dashboard | A Dashboard template | All records of the widget's Type Name |
| Show the hierarchy below the record the user is currently viewing | Relation | A tab on a View layout | The records related to the current record |
Typical uses:
- A Factory dashboard that lists every factory, its projects and the buildings in each project.
- A Department dashboard showing the employees in each department, with their lifecycle State.
- An Equipment Asset View page with a tab that lists the asset's maintenance requests.
The widget is read-only. It is for browsing a hierarchy, not editing it.
How it Works
Tree View Settings
When you set Show As to Tree View, these settings appear in the widget's details:
| Setting | Description | Required |
|---|---|---|
| OData Query | The query that fetches the records and their children. Click the ⓘ icon next to the label to open the built-in OData Query Guide. | Yes |
| Column Designer | The attributes shown as columns. The same columns are used at every level of the tree. | Yes |
On a Dashboard Tree View, the Query Definition field is hidden because the OData query replaces it. Sorting, toolbar, bulk actions, export, filter and shrink-to-fit settings are also hidden, because the tree doesn't use them.
How the Query is Sent
The widget sends your query to the Protrak OData endpoint and adds paging for you:
| Placed on | Request sent |
|---|---|
| Dashboard | odata/{TypeName}?{your query}&$top=50[&$skip=N] |
| View layout tab | odata/{TypeOfViewedRecord}({RecordId})?{your query}&$top=50 |
- On a Dashboard, the top-level rows are the records returned by the query. Each
$expandadds a level below them. - On a View layout tab, the query starts from the record being viewed. That record isn't shown. Its expanded children become the top-level rows.
- The widget encodes
=and;inside$expand(...)automatically, so write the query in plain text.
OData Query Rules
| Option | Where | Purpose |
|---|---|---|
$expand=Rel(...) | Top level, and nested inside another $expand | Adds a child level. Rel is the relation name that links the parent type to the child type. To go from the child side up to the parent, use Rel_Reverse. |
$top=N | Inside each $expand only | How many children to load per parent. Defaults to 20; the server caps it at 100. |
$select=... | Top level, and inside each $expand | The attributes to fetch for that level. Include every attribute that has a column. |
$count=true | Top level (required on Dashboards), and inside each $expand | Returns the record count that the widget uses for paging. |
- Separate top-level options with
&. Separate options inside$expand(...)with;. - Don't add
$topor$skip. The widget adds them and they will be overwritten. - In each
$select, use only attributes that exist on that level's type. Basic attributes (Name,State,Creator,Modifier,Created,Modified,Description) exist on every type, so they are safe at any level.
What the Tree Displays
In the toolbar
- A record count, "Showing X of Y records", where X is the number of top-level records loaded so far.
- A Reload button, which collapses every row and fetches the tree again from the start.
In the grid
- A header row with one column per visible attribute from the Column Designer, using each attribute's label.
- The first column is twice as wide as the others. It holds the expand arrow (▶ collapsed, ▼ expanded) and is indented by 24 px for each level. Put Name first.
- Every row starts collapsed. Click the arrow or anywhere on the row to expand or collapse it. Rows with no children have no arrow.
- Values use the attribute's normal renderer, so dates, picklists, users and so on look the same as in a grid. If a level's type doesn't have a column's attribute, or the query didn't
$selectit, the cell shows "-". - Each column is at least 150 px wide. If the columns don't fit, the tree scrolls horizontally.
Loading more records
- On a Dashboard, the first 50 top-level records are loaded. Scrolling near the bottom loads the next 50, and so on until all records are loaded. If 50 rows don't fill the widget, it keeps loading until they do.
- Children are not paged by the widget. They come back with their parent in the same response, limited to 20 per parent unless you set
$topinside the$expand(up to 100). Extra children are silently left out. - On a View layout tab, the children of the current record are loaded in a single request, with the same per-parent limit.
- The server returns at most 10,000 records across all levels in one response, and allows up to 5 levels of nested
$expand.
If the request fails, for example because of a misspelled relation name or attribute, the widget shows "Error loading tree data."
Steps to Use
Before you begin, the types and the relations between them must already exist, for example Factory, Project and Building, linked by the relations FactoryToProject and PToBuilding. You need the exact relation names for $expand.
1. Configure the Widget
- Navigate to Design Studio → Type Widgets and click Create.
- Fill in the basic details: Widget Name, Display Name, Type Name and Widget Category.
- Dashboard: set Type Name to the type of the top-level rows, e.g.
Factory. - Relation: set Type Name to the type whose View layout will show the tab, and fill in the other Relation details as usual.
- Dashboard: set Type Name to the type of the top-level rows, e.g.
- Set Show As to Tree View.
- Enter the OData Query. See Examples.
- In the Column Designer, add the attributes to show. Put Name first and mark the columns Visible. Columns that aren't visible are not rendered.
- Save the widget.
2. Place it on a Template
- Dashboard widget: open your Dashboard template in the Page Template Editor and add the widget. Give it a tall container, because the tree fills the container and scrolls inside it.
- Relation widget: add it as a tab on the type's View layout.
See Page Template Editor for placement and sizing.
3. Use the Tree
Once published, users can:
- Expand and collapse rows to drill down through the hierarchy.
- Scroll down to load more top-level records (Dashboard only).
- Click Reload to fetch the latest data.
Examples
The examples below use sample types. Replace the type, relation and attribute names with the ones in your tenant.
Example 1: Single-Level Dashboard Tree (Department → Employee)
Every department, with its employees underneath.
| Setting | Value |
|---|---|
| Widget Category | Dashboard |
| Type Name | Department |
| Show As | Tree View |
| Columns | Name, State |
OData Query
$expand=DepartmentToEmployee($select=Name,State;$count=true)&$count=true&$select=Name,State
Result
Name State
▼ Engineering Active
Asha Patil Active
Rahul Mehta On Leave
▶ Finance Active
▶ Human Resources Active
Breakdown of the query:
$select=Name,Stateat the top level fetches both columns for each department.$expand=DepartmentToEmployee(...)adds the employees as the second level, with the same two columns.$count=trueat the top level is required for paging through departments.
Example 2: Two-Level Dashboard Tree (Factory → Project → Building)
A three-tier hierarchy using a nested $expand.
| Setting | Value |
|---|---|
| Widget Category | Dashboard |
| Type Name | Factory |
| Show As | Tree View |
| Columns | Name |
OData Query
$expand=FactoryToProject($select=Name;$count=true;$expand=PToBuilding($select=Name;$count=true))&$count=true&$select=Name
Written out by level, this reads more easily:
$select=Name ← Level 1: Factory
&$count=true
&$expand=FactoryToProject( ← Level 2: Project
$select=Name;
$count=true;
$expand=PToBuilding( ← Level 3: Building
$select=Name;
$count=true
)
)
The OData Query field must contain the single-line form. The indented version is only there to show the structure.
Result
Name
▼ Pune Factory
▼ Phase 1 Expansion
Building A
Building B
▶ Warehouse Upgrade
▶ Nashik Factory
To add a fourth level, nest one more $expand=...(...) inside PToBuilding(...), separated with ;.
Example 3: Relation Tab on a View Layout (Equipment Asset → Maintenance Requests)
A tab on an Equipment Asset View page that lists the asset's maintenance requests with their type and priority.
| Setting | Value |
|---|---|
| Widget Category | Relation |
| Type Name | EquipmentAsset |
| Show As | Tree View |
| Columns | Name, RequestType, Priority, State |
OData Query
$expand=EquipmentAssetToMaintenanceRequest($select=Name,RequestType,Priority,State;$count=true)&$select=Name
The widget requests odata/EquipmentAsset({id of the open asset})?.... The asset itself is not shown. Its maintenance requests become the top-level rows:
Name Request Type Priority State
MR-21-Sep-2026-94 Inspection Medium Open
MR-02-Oct-2026-17 Repair High In Progress
RequestType and Priority are custom attributes of Maintenance Request. Selecting them inside that relation's $expand is valid because they exist on that level's type. The top-level $select=Name only applies to the asset, which isn't displayed.
Example 4: Multi-Level Relation Tab (Athlete → Academy → Coach)
Expanding on a View page works the same way as on a Dashboard. Nest $expand to go deeper below the current record.
$expand=AthleteToAcademy($select=Name,State;$count=true;$expand=AcademyToCoach($select=Name,State;$count=true))&$select=Name
On an Athlete's View page, the tab lists the athlete's academies. Each academy expands to show its coaches.
Notes
- The relation name in
$expandmust match exactly. A wrong relation name fails the whole request, and the widget shows "Error loading tree data." - A column must be in both places. Add it in the Column Designer and in the
$selectof every level where it should show a value. - Columns are matched by attribute name, ignoring case, so
nameandNameboth work. - Always include
$count=trueat the top level on Dashboards. Without it, the widget can't tell how many records remain, and scrolling won't load more. - Keep
$selectlean. Each extra attribute, and especially each extra level, makes the response larger. Children are fetched together with their parents. - There is no search, sort, filter or Quick Filter on this widget. To narrow or reorder the data, change the OData query.
- Rows are not links. To open a record, use a grid widget or navigate to it directly.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| "Error loading tree data." | Misspelled relation or attribute name, an attribute selected on a level whose type doesn't have it, or & used inside $expand(...) instead of ;. |
| Rows appear but every cell shows "-" | The column's attribute isn't in that level's $select. |
| Only the first 50 rows ever load | $count=true is missing from the top level of the query. |
| A parent shows only 20 children | No $top inside that level's $expand. Add $top=100 (the maximum). |
| No arrow on rows that should have children | The $expand is missing for that level, or those records have no related records. |
| View layout tab shows no rows | The viewed record has no related records through the relation in the first $expand. |
To check a query outside the widget, call the OData endpoint directly with the same URL the widget sends (see How the Query is Sent) and inspect the JSON. Each expanded relation appears as a nested object with a value array.
Next Steps
- Creating and configuring widgets: Type Widgets
- Placing the widget on a template: Page Template Editor