There are various ways to show hierarchical information in Visual Builder, as shown in my previous blogs about trees, hierarchical lists, and nested tables. With the Redwood set of components a new Hierarchy Viewer component provides a more visual way to show and interact with this type of information – the Hierarchy Viewer look like this:
In this blog we'll show how to add and configure a hierarchy viewer in your app. As you can see in the image above – the component can be used to show different objects in different levels of the hierarchy. We'll focus on a simplified scenario where all the items are of the same type – they are all employees. We'll show employees their managers and their directs, and allow you to navigate the organizational tree.
Here is a demo of the complete development process followed by information on the specific steps:
Basic Setup
The Hierarchy Viewer Pattern component will be in the component palette if your application is set to use the Redwood templates and patterns. The easiest way to get this is by using the Redwood starter template. If you already have an app using a different template you can manually added the Redwood components to an existing app.
When you add the hierarchy viewer pattern to your page, it adds a hierarchy viewer and a hierarchy card components to your UI, and also a set of variables, events, and action chains to handle the display and navigation. Now you need to configure the properties of these to show your data.
Start by configuring the card templates – in our example we have one template for all levels of the tree. You provide a name for the template item, and then setup the properties of the various attribute of the card pointing to expressions of the format [[$current.data.attributename]]. Note that you can add multiple templates with unique names and unique card layouts.
Next, we'll configure the variables.
The key variable is the currentItemId – which contains the id of the object that you are showing (and whose parents and children you'll want to show in the hierarchy). The variable is set as an input parameter to the page that you can pass on the URL. In our example we set a default value.
You'll see variables created for the currentItem and the parentItem data sources – you need to configure the SDPs that fetch the info into those two layers choosing the right REST endpoints and the attributes you want to display. Make sure to include the right filtering for the REST calls to get the actual data you are interested in.
Since in our case we want to show the manager of the current employee, we add a variable to store the managerid, and use this in the filter of the parent data source. We also add logic to our page to fetch the info about the manager of the current employee, and assign it to the managerid variable (we add this in the vbEnter event of the page).
For both the current and parent items there are variables that should contain the name of the card template used to show them – in our case that's the emp template.
With these in place you should be able to run the page and see the current employee and their manager shown in the hierarchy viewer (HV for short).
Configure Child Objects
The HV can show various children related to the current item – you add them as an array to the HV, and for each one you'll specify label, template, and a variable that contains the data.
In the demo we create an SDP to fetch employees and configure the filterCriterion to only return the employees that report to the current employee.
We can also specify a variable that contains the number of children. To get the number of directs, we set the totalResults attribute of the SDP to true. Then we can use the SDP.totalSize as the value for the count field.
If you'll run the page now you should see 3 levels of hierarchy – parent->current->directs
Configure A Focus Event
The hierarchy viewer allows you to navigate the hierarchy by clicking on cards to select them as the new current item. The pattern includes a built-in change focus event on the HV, that you'll need to update to handle selection of a card. The action chain simply navigates to the same page passing on the URL the values for the new currentItem and the child view to use.
In the current version of the pattern this event still uses a json action chain, and you'll need to switch to the code view of the action to update the value passed to the currentItemId to point to the attribute that was passed in the payload to the action chain. In our case that attribute is called id so the setting will look like this: "currentItemId": "{{ $variables.focusContext.id }}",
Also update a value for the childView you want to show when the new current item is selected – for us it will be still the directs.
Since in our example fetching the parent is done in the VBEnter event, and this event doesn't fire again when you navigate from the page to itself, we need to update the manager id. To do this we add a value listener to the value of the currentItemId and in it fetch the new managerId to use.
Summary
This sample focuses just on the basics of using the hierarchy viewer, there are various other capabilities that you can implement such as showing multiple types of objects, listing various children of the current object, and various navigation and actions at the card level – check the hierarchy viewer's documentation in the component exchange for information about these capabilities.