Breadcrumbs

Overview

Breadcrumbs demo

Breadcrumbs in Servoy is a UI component used for navigation that provides a trail of links representing the user's current location within the application, usually in a hierarchical manner. This allows users to easily navigate back to previous forms or pages by clicking on the links in the breadcrumb trail.

The Breadcrumbs component wraps the standard Bootstrap breadcrumbs used to display navigational hierarchy.

Breadcrumbs are particularly useful in applications with a multi-level navigation structure or complex workflows, where users need to track where they are and how they reached the current page. They give users a quick way to backtrack to higher-level forms or sections of the application without using traditional back/forward buttons or re-navigating through the menus.

Key Features of Breadcrumbs:

• Hierarchical Navigation: Breadcrumbs display the user's navigation path in a hierarchical order. Each segment in the breadcrumb trail represents a form or a section, and users can click on any segment to go back to that point in the navigation history.

• Improves User Experience: Breadcrumbs make navigation more intuitive by providing users with a clear sense of their location within the application's hierarchy. This is especially helpful in applications with deep navigation layers or complex workflows.

• Contextual Backtracking: Unlike using a back button (which follows strict history order), breadcrumbs allow the user to jump back to any previous section in the hierarchy, making it easier to navigate to higher-level forms or modules. Dynamic Generation: Breadcrumbs are often generated dynamically based on the user's navigation history. Each time the user navigates to a new form, the breadcrumb trail updates to reflect the new location. Customization: Breadcrumb components in Servoy can be customized to fit the design and functionality of the application. You can choose the labels for each segment of the breadcrumb and control how they respond when clicked.

Use Cases for Breadcrumbs

• Hierarchical Applications: In applications with a hierarchical structure, breadcrumbs help users understand their current location and navigate between different levels of the hierarchy. For example, in an e-commerce application, a breadcrumb might track the user's path from Home to Categories to a specific Product.

• Multi-Step Processes: Breadcrumbs can be used to guide users through a multi-step process, such as a wizard or checkout flow. The breadcrumbs visually represent each step, and users can click on previous steps to review or change information.

• Drill-Down Navigation: Breadcrumbs are useful when users are drilling down into data or categories. They allow users to easily retrace their steps back to higher-level categories or forms without having to use the back button or main navigation.

Get Started

Creating a Breadcrumbs component

Create a Breadcrumbs component

Here are the steps for creating a Breadcrumbs component:

1. Open the Form Editor of the form where you need to place a Breadcrumbs component

2. Find Breadcrumbs in Navigation section in the components' pallet

3. Drag and drop the Breadcrumbs component in the desired place of the form

4. Set the crumbs; this can be done via properties panel

5. Edit other Breadcrumbs properties and Breadcrumbs crumb properties

Setting the crumbs (in the properties panel)

Adding and editing crumbs

After dragging the component on the form, find the Breadcrumbs in the form editor, click it and proceed with the following steps:

1. Add a crumb. There are 2 ways of adding a crumb:

   1. Select the breadcrumbs property and click the + button in order to add a crumb. Next crumbs can be added the same way or by clicking the + button (insert a new array item below) of another crumb. You can change the crumbs' order by dragging them into the desired placed inside the Breadcrumbs (in the form editor).

   2. Drag and drop crumb component (of an Breadcrumbs in Navigation section in the components' pallet) into the Breadcrumbs component (in the form editor)

2. Expand the breadcrumbs property to see the list of crumbs. They are also shown in the Breadcrumbs component (in the form editor)

3. In order to edit each crumb, expand it or click the crumb name in the Breadcrumbs component (in the form editor) and set its properties:

   1. Set an unique crumb id

   2. Set a display name corresponding to each id

Breadcrumbs crumb It is necessary to set an unique id in the Breadcrumbs crumb crumbID property. Example: home_page.

If you do it in code:

   /** @type {CustomType<bootstrapextracomponents-breadcrumbs.crumb>} */
   var newCrumb = {crumbId:'home_page', displayName:'Home'};

Building a Custom Trail If your breadcrumb trail depends on user choices or dynamic navigation, you should add crumbs one by one using the addCrumb() method. This ensures the trail accurately reflects the actual path taken through your application rather than a fixed, predefined structure.

elements.breadcrumbs_steps.addCrumb({ crumbId: 'step1', displayName: 'Step 1' });
elements.breadcrumbs_steps.addCrumb({ crumbId: 'step2', displayName: 'Step 2' });

This approach is ideal for multi-step forms, wizard-style flows, or deep drill-down paths.

Predefined Crumbs Behavior If you set the entire breadcrumb trail in one go in the properties panel or by using setCrumbs(), Servoy will automatically highlight the last crumb as active. This assumes the final item in the array represents the current page or view.

elements.breadcrumbs_steps.setCrumbs([
  { crumbId: 'home', displayName: 'Home' },
  { crumbId: 'orders', displayName: 'Orders' },
  { crumbId: 'details', displayName: 'Details' } // this one will be shown as active
]);

To change this behavior dynamically, consider building the trail incrementally using addCrumb() instead.

Breadcrumbs Properties

You can find a list of Breadcrumbs events here.

autoRemoveWhenClicked

When autoRemoveWhenClicked property is selected, then any crumbs that come after it will be automatically removed from the breadcrumb trail. This behavior is useful in scenarios where the breadcrumb trail represents a linear progression, such as a step-by-step workflow or a history path that should reset when the user navigates back to a previous point. When set to true, it mimics the behavior of "going back and discarding forward history," ensuring the trail stays relevant and doesn't display steps that are no longer active.

Scripting Breadcrumbs

Main events

You can find a list of Breadcrumbs events here. You can find a list of Breadcrumbs API methods here.

onCrumbClicked

This event is called when a breadcrumb item is clicked. Here is an example of how to use the onCrumbClicked event of Breadcrumbs in the Scripting Editor:

Let's consider the following setup:

• main_form: the form where the Breadcrumbs component is placed, together with a form container component, fc_crumb_form

  • Breadcrumbs component will get the following crumbs:

    • crumb:customers, displayName:Customers page

    • crumb:orders, displayName:Orders page

    • crumb:order_details, displayName:Order details page

• separate forms showed in main_form as a contained form in the form container component: customers, orders, order_details.

The following goes on main_form script file:

/**
 * Called whenever a breadcrumb item is clicked with the JSEvent and the item clicked on.
 *
 * @param {JSEvent} event
 * @param {CustomType<bootstrapextracomponents-breadcrumbs.crumb>} crumb
 * @param {Number} index
 *
 * @private
 *
 * @properties={typeid:24,uuid:"5289032B-AF76-4E73-BB04-65061E0CAA6D"}
 */
function onCrumbClicked(event, crumb, index) {
elements.fc_crumb_form.containedForm = forms[crumb.crumbId]; // crumb is an object; crumb.crumbId gets the value of the clicked crumb ID
}

Add a crumb

Here is an example of how to programmatically add a crumb in the Scripting Editor of the main form, using the the addCrumb API:

/**
 * Callback method for when form is shown.
 *
 * @param {Boolean} firstShow form is shown first time after load
 * @param {JSEvent} event the event that triggered the action
 *
 * @private
 *
 * @properties={typeid:24,uuid:"62F000BF-9C8E-4E42-88D4-D4CFBAEB7AC5"}
 */
function onShow(firstShow, event) {
	elements.breadcrumbs_steps.addCrumb({crumbId:"products", displayName:"Products page"}); // adds a crumb at the end, having id = `products` and displayed text "Products page"
}

Remove a crumb after a certain index

Here is an example of how to programmatically remove a crumb after a certain index in the Scripting Editor of the main form, using the the removeCrumbsAfter API:

/**
 * Callback method for when form is shown.
 *
 * @param {Boolean} firstShow form is shown first time after load
 * @param {JSEvent} event the event that triggered the action
 *
 * @private
 *
 * @properties={typeid:24,uuid:"62F000BF-9C8E-4E42-88D4-D4CFBAEB7AC5"}
 */
function onShow(firstShow, event) {
	elements.breadcrumbs_steps.removeCrumbsAfter(1); // index starts at 0, so in this case only the first 2 crumbs will be displayed
}

Remove the last crumb

Here is an example of how to programmatically remove the last crumb in the Scripting Editor of the main form, using the the removeLastCrumb API:

/**
 * Callback method for when form is shown.
 *
 * @param {Boolean} firstShow form is shown first time after load
 * @param {JSEvent} event the event that triggered the action
 *
 * @private
 *
 * @properties={typeid:24,uuid:"62F000BF-9C8E-4E42-88D4-D4CFBAEB7AC5"}
 */
function onShow(firstShow, event) {
	elements.breadcrumbs_steps.removeLastCrumb(); // removes the last crumb
}

Setting the crumbs

Here is an example of how to programmatically set the crumbs in the Scripting Editor of the main form, using the the setCrumbs API:

/**
 * Callback method for when form is shown.
 *
 * @param {Boolean} firstShow form is shown first time after load
 * @param {JSEvent} event the event that triggered the action
 *
 * @private
 *
 * @properties={typeid:24,uuid:"62F000BF-9C8E-4E42-88D4-D4CFBAEB7AC5"}
 */
function onShow(firstShow, event) {
	elements.breadcrumbs_steps.setCrumbs([{crumbId:"customers", displayName:"Customers page"}, {crumbId:"orders", displayName:"Orders page}, {crumbId:"order_details", displayName:"Order details page"}, {crumbId:"products", displayName:"Products page"}]); 
}