Skip to main content

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 CategoryPlaced onTop-level rows are
Browse every record of a type with its related records underneath itDashboardA Dashboard templateAll records of the widget's Type Name
Show the hierarchy below the record the user is currently viewingRelationA tab on a View layoutThe 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:

SettingDescriptionRequired
OData QueryThe 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 DesignerThe 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 onRequest sent
Dashboardodata/{TypeName}?{your query}&$top=50[&$skip=N]
View layout tabodata/{TypeOfViewedRecord}({RecordId})?{your query}&$top=50
  • On a Dashboard, the top-level rows are the records returned by the query. Each $expand adds 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​

OptionWherePurpose
$expand=Rel(...)Top level, and nested inside another $expandAdds 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=NInside each $expand onlyHow many children to load per parent. Defaults to 20; the server caps it at 100.
$select=...Top level, and inside each $expandThe attributes to fetch for that level. Include every attribute that has a column.
$count=trueTop level (required on Dashboards), and inside each $expandReturns the record count that the widget uses for paging.
  • Separate top-level options with &. Separate options inside $expand(...) with ;.
  • Don't add $top or $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 $select it, 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 $top inside 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​

  1. Navigate to Design Studio → Type Widgets and click Create.
  2. 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.
  3. Set Show As to Tree View.
  4. Enter the OData Query. See Examples.
  5. 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.
  6. 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:

  1. Expand and collapse rows to drill down through the hierarchy.
  2. Scroll down to load more top-level records (Dashboard only).
  3. 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.

SettingValue
Widget CategoryDashboard
Type NameDepartment
Show AsTree View
ColumnsName, 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,State at the top level fetches both columns for each department.
  • $expand=DepartmentToEmployee(...) adds the employees as the second level, with the same two columns.
  • $count=true at 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.

SettingValue
Widget CategoryDashboard
Type NameFactory
Show AsTree View
ColumnsName

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

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.

SettingValue
Widget CategoryRelation
Type NameEquipmentAsset
Show AsTree View
ColumnsName, 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 $expand must 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 $select of every level where it should show a value.
  • Columns are matched by attribute name, ignoring case, so name and Name both work.
  • Always include $count=true at the top level on Dashboards. Without it, the widget can't tell how many records remain, and scrolling won't load more.
  • Keep $select lean. 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​

SymptomLikely 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 childrenNo $top inside that level's $expand. Add $top=100 (the maximum).
No arrow on rows that should have childrenThe $expand is missing for that level, or those records have no related records.
View layout tab shows no rowsThe 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​