Using breadcrumbs to keep your users on track

In the legendary fairy tale of Hansel and Gretel, little Hansel comes up with the novel approach of laying a trail of breadcrumbs to help them find their way back home from unfamiliar territory. You can now do the digital equivalent to this in Nitro App Builder apps — minus the risk of the breadcrumbs being eaten by birds — as a way to help users know where they are in a particular process in the browser.

Introduced to NAB in build 6.2.20230927, a common use case for breadcrumbs would be for stepping users through setting up a new part number, in which multiple forms must be filled out one after the other.  Or you could use breadcrumbs as a visual reference to where a user is as he or she goes through the various pages of a drill-down inquiry. 

To illustrate the concept, let’s show how we could set up breadcrumbs for a basic order inquiry app, with drill-down logic consisting of three distinct grid widgets: (1) A list of customers, (2) a list of orders for a selected customer, and (3) a list of lines for a selected order.

(1) Create the desired widgets for the drill-down or step-through

The first step is to create three simple NAB data sources and accompanying grid widgets for each of the lists. For our demonstration here we’ll use example grids that are included with Valence 6.2. Specifically, the grid widgets respectively named Customer List, Order List and Order Lines (to see these widgets, be sure to click on the cogwheel above the object list in NAB Designer and tick on the “Show Examples” checkbox).

(2) Insert the widgets into a NAB App and turn on Breadcrumbs

With your widgets ready to go, we’ll start a new NAB app and add two additional sections beyond the default “Main” section — one called “Orders” and one the other called “Lines”. Sections aren’t absolutely necessary for using breadcrumbs, but they tend to make it easier to hide and show widgets. So add the appropriate grid widget to each of the three sections, then click on the “App-level breadcrumbs” checkbox to activate the breadcrumb navigation, resulting in something that looks like this:


(3) Add Behavior logic to handle drilling down from one widget to the next 

For our drill-down inquiry we want a click on the Customers grid in the Main section to show customer orders for the selected customer, and a subsequent click on an order to bring up the line item detail for the selected order. To achieve this we’ll go into Behaviors and add two click events: The first click event should be added to the Customers grid to filter the Orders grid based on customer number clicked, then show the Orders section; The second click event will go on the Orders grid to filter the Lines grid based on the order number clicked, then show the Details section. The resulting Behaviors list should look like this:


(4) Assign the desired breadcrumb text to each click event

Now we can start configuring the breadcrumbs, which entails adding some more actions under the two click events. We’ll begin by setting up an app variable to hold the text we want to show in each breadcrumb (unless you just want to hard code something generic like “Step 1”, which wouldn’t be terribly helpful).  So on the click event in the Customers grid, add a “Set App Variable” action to assign the customer name to an app variable we’ll reference in a moment. You can call it whatever you want, but we’ll use “crumbText” for our example here. A logical text value for the first breadcrumb would be the name of the customer that was clicked, which we’ll do like this:

We’ll do the same for the click event in the Orders grid, only in this case we’ll set the app variable to “Order: ” plus the selected order number, like this:


(5) Link text to breadcrumbs and fire events to handle click actions

Now we’re ready to wire up the breadcrumbs themselves. When this app is initially launched we don’t want to show any breadcrumbs, as they’re already “home” so to speak.  But as soon as the user clicks on a customer in the first grid, we want to add two breadcrumbs — one to reflect “home” (the list of customers) and one to reflect the customer that they drilled down on.

This is where we put the new “Breadcrumbs” behavior action to use, an action that is only available because we activated App-level breadcrumbs in step 2 above.

The first breadcrumb we want to show should simply say “Customers” and, when clicked by the user, should fire an event we’ll call “backtomain” to return the user to the Main grid (we’ll expand on that in a moment).  So that first breadcrumb entry should look like this:

The second breadcrumb that should appear is the name of the customer that was selected, so we’ll add another breadcrumb and put the “crumbText” app variable we set in step 4 above in the link Text field. We’ll also fire another event we’ll call “backtoorders” here, such that clicking on the breadcrumb will return the user to the order list. So our second breadcrumb entry should look like this:

The last breadcrumb we’ll want to see is the order number that was clicked in the Orders grid when displaying the list of lines. So in the click event for the Order List grid we will again link the “crumbText” app variable that was set in step 4. Since this will be the last breadcrumb in the list there’s no need to fire any event, as it won’t be clickable. So this breadcrumb entry should look just like the prior breadcrumb except with no fired event.

The resulting Behavior tree should look like this:


(6) Add logic to respond to fired events

The last step is to respond to click events registered on each breadcrumb, which is handled in the Event Listeners section located at the top of the Behaviors list. The first event we want to listen for is the local one we called backtomain, which should switch the user back to the first grid and remove the breadcrumbs. So add an event, click on Local and select “backtomain” as illustrated here:

Then add a “Clear All Breadcrumbs” action and a “Show Section” to return the user to the Main grid. Likewise, add another event listener for backtoorders and have that return the user to the Orders grid. The resulting events list should look like this:

At this point you can save the app and launch it to see the feature in action. Drill through the various grid widget records and you’ll see a list of breadcrumbs that would make Hansel proud!

Note that there is also a “Navigate to Breadcrumb” behavior action you could also use on, say, a button somewhere else in your app to simulate the user clicking on a specific breadcrumb. Specify “1” to indicate the first breadcrumb, “2” for the second, etc.