Navigation

Overview

In Servoy, navigation refers to how users move between different forms (views) within the application. Servoy provides several built-in methods and components for implementing navigation, ranging from simple to advanced, with the ability to integrate specialized modules to streamline development.

Change Root Form

The simplest way to navigate between forms in Servoy is by using application.showForm(). This method changes the root form, replacing the currently displayed form with the specified one. This type of navigation is commonly used in simpler applications where direct switching between forms is sufficient.

Example:

application.showForm(forms.newForm);  // Navigate to 'newForm'

This method works for basic navigation needs but can become less flexible in more complex applications that require dynamic layout and component-based navigation.

Using Form Containers and Buttons

You can create more complex navigation using form containers and plain buttons, for example. A common use case is buttons that load different forms into a container, which allows you to manage layout and navigation dynamically without changing the root form.

Form containers allow embedding multiple forms in a single container, so users can switch between different views. Buttons trigger form changes inside the container based on the user’s actions.

Example: Using a form container to display different forms based on button clicks:

function switchForm(formName) {
    elements.formContainer.containedForm = forms[formName];
}

// Buttons trigger form switches

function onActionbtnDashboard(event) {
switchForm('dashboardForm');
}

function onActionbtnReports(event) {
switchForm('reportsForm');
}

Servoy provides several specialized UI components designed for navigation. These components are highly useful for implementing structured and intuitive navigation interfaces.

Sidenav

Often used for side navigation with a list of options that load forms into a main container.

Basic Setup for a Sidenav in Servoy

Setting up a sidenav in Servoy involves creating a main form that houses the Sidenav component and multiple secondary forms that are loaded dynamically based on user interaction. The Sidenav acts as both the navigation tool and the form container, eliminating the need for additional form containers. You can assign an existing ServoyMenu or define multiple menu items within the Sidenav, including nested submenu items for hierarchical navigation. Optionally, you can add static header and footer forms for additional content such as logos or utility links.

Main Form (Containing the Sidenav) The main form contains the sidenav component. This form serves as the layout container where the Sidenav resides, and it handles the navigation between other forms. Since the Sidenav includes an internal form container, there’s no need to add a separate form container component.
Secondary Forms (Linked to the Sidenav) These secondary forms represent the different sections or pages of your application. They are loaded into the Sidenav’s internal form container when the user interacts with the menu items.

Step-by-Step Setup

Step 1: Create the Forms

Main Form (e.g., main_form):

This form contains the Sidenav component. It acts as the shell where secondary forms are dynamically loaded based on the user's interactions with the Sidenav.
No separate form container is required because the sidenav already has one built in.

Secondary Forms (e.g., homeForm, dashboardForm, settingsForm):

These forms will be displayed inside the Sidenav’s internal container when users click on the corresponding menu items.

Step 2: Add the Sidenav to the Main Form

In main_form:

Open the Form Editor in Servoy.
Drag the Sidenav component from the Navigation section onto the form.
Set up the menu items for the sidenav either through the properties panel or programmatically: assign an existing ServoyMenu or define multiple menu items within the Sidenav.

Step 3: Define the Menu Items in the Sidenav You can assign an existing ServoyMenu or define menu items using the properties panel, or you can create the menu items programmatically. Each menu item should have an ID and a formName that points to the form to be loaded when that menu item is clicked.

Example: Define Menu Items for the Sidenav

var menuItems = [
    { id: 'home', text: 'Home', formName: 'homeForm' },
    { id: 'dashboard', text: 'Dashboard', formName: 'dashboardForm' },
    { id: 'settings', text: 'Settings', formName: 'settingsForm' }
];

// Set the root menu items for the Sidenav
elements.sidenav.setRootMenuItems(menuItems);

In this example:

id: A unique identifier for each menu item.
text: The text that will be displayed in the Sidenav.
formName: The form to be loaded into the Sidenav’s internal container when the item is clicked.

Step 4: Handle the onMenuItemSelected Event The onMenuItemSelected event is triggered when a user clicks on a menu item. You can use this event to load the appropriate form into the Sidenav’s form container.

Example: onMenuItemSelected Event

/**
 * Called when a menu item is selected.
 *
 * @param {String} menuItemId
 * @param {JSEvent} event
 */
function onMenuItemSelected(menuItemId, event) {
    elements.sidenav.containedForm = forms[menuItemId];  // Load the form associated with the clicked menu item
}

In this example:

menuItemId: This is the ID of the clicked menu item, which corresponds to the form that will be displayed.
elements.sidenav.containedForm: This property automatically loads the specified form into the Sidenav’s built-in form container.

Step 5: Adding Submenu Items (Optional) The Sidenav supports multi-level navigation, allowing you to create submenu items under main items. You can define up to four levels of nested items.

Example: Adding Submenu Items

var menuItems = [
    { id: 'home', text: 'Home', formName: 'homeForm' },
    { id: 'dashboard', text: 'Dashboard', formName: 'dashboardForm', menuItems: [
        { id: 'reports', text: 'Reports', formName: 'reportsForm' },
        { id: 'analytics', text: 'Analytics', formName: 'analyticsForm' }
    ] },
    { id: 'settings', text: 'Settings', formName: 'settingsForm' }
];

// Set the root menu items with submenus
elements.sidenav.setRootMenuItems(menuItems);

In this example:

menuItems: The dashboard item contains two sub-items: Reports and Analytics. These are displayed when the user clicks on Dashboard.

Step 6: Adding Headers and Footers (Optional) The sidenav can also display header and footer forms, which are static forms that stay at the top and bottom of the Sidenav, respectively. You can use these areas for branding, logos, or utility links.

Example: Setting Header and Footer Forms

// Set the header and footer forms
elements.sidenav.headerForm = forms.headerForm;
elements.sidenav.footerForm = forms.footerForm;

In this example:

headerForm and footerForm are optional forms that are displayed at the top and bottom of the Sidenav.

Typically placed at the top of the screen, it includes links to important sections of the application.

To set up a navbar in Servoy, you typically create several forms that correspond to the different sections or pages of your application, and then use the navbar to navigate between them. The setup involves creating the main form that holds the navbar and other content containers, and the secondary forms that represent the different pages or modules that the navbar will link to.

Step 1: Create the Forms

Main Form (e.g., main_form):
- This form will hold the navbar and a form container where other forms will be displayed.
Secondary Forms (e.g., homeForm, dashboardForm, settingsForm):
- These forms represent the content that will be displayed when the user clicks a menu item in the navbar.

Step 2: Adding the Navbar to the Main Form

In main_form:
- Open the form editor and drag the Navbar component from the Navigation section onto the form.
- Set up the menu items in the properties panel for the Navbar: assign an existing ServoyMenu or define multiple menu items within the Navbar. You can add items like Home, Dashboard, Settings, etc.

Step 3: Adding a Form Container to the Main Form

Add a form container to the main_form. This will be used to display the content of the secondary forms dynamically.
- Name it something like fc_content.

Step 4: Defining Menu Items in the Navbar You can either assign an existing ServoyMenu or define the menu items via the properties panel or dynamically through scripting.

Example: Defining Navbar Menu Items via Scripting

var menuItems = [
    { itemId: 'home', text: 'Home' },
    { itemId: 'dashboard', text: 'Dashboard' },
    { itemId: 'settings', text: 'Settings' }
];

// Set the menu items for the navbar
elements.navbar.setMenuItems(menuItems);

In this example:

The navbar is populated with three menu items: Home, Dashboard, and Settings.
Each item has an itemId that corresponds to the form it will display when clicked.

Step 5: Handling Navbar Events You'll need to set up an event to handle the switching of forms when a navbar item is clicked. You can use the onMenuItemClicked event to detect which menu item was clicked and load the corresponding form into the form container. Example Code: onMenuItemClicked Event In the script file for main_form:

/**
 * Called when a menu item is clicked.
 *
 * @param {JSEvent} event
 * @param {CustomType<bootstrapextracomponents-navbar.menuItem>} menuItem
 */
function onMenuItemClicked(event, menuItem) {
    // Switch the form based on the clicked item ID
    switch (menuItem.itemId) {
        case 'home':
            elements.fc_content.containedForm = forms.homeForm;
            break;
        case 'dashboard':
            elements.fc_content.containedForm = forms.dashboardForm;
            break;
        case 'settings':
            elements.fc_content.containedForm = forms.settingsForm;
            break;
        default:
            elements.fc_content.containedForm = forms.homeForm;  // Default to homeForm
    }
}

In this example:

elements.fc_content.containedForm: This is the form container where the forms will be loaded dynamically.
menuItem.itemId: This represents the ID of the navbar item that was clicked. Based on the clicked item, the corresponding form is displayed.

Step 6: Establishing Form Relationships (Optional) In more complex applications, you might want to establish relationships between forms. This is particularly useful if the forms need to share data or if they are related via Servoy's foundset. You can set up these relationships using the relationName property.

Hint

In order to ease things, a common practice is to set the menu item ids identical with the corresponding form name. This also simplifies handling onMenuItemClicked event.

Here is an example:

setting menu items:

var menuItems = [
    { itemId: 'homeForm', text: 'Home' },
    { itemId: 'dashboardForm', text: 'Dashboard' },
    { itemId: 'settingsForm', text: 'Settings' }
];

// Set the menu items for the navbar
elements.navbar.setMenuItems(menuItems);

handling onMenuItemClicked event:

/**
 * Called when a menu item is clicked.
 *
 * @param {JSEvent} event
 * @param {CustomType<bootstrapextracomponents-navbar.menuItem>} menuItem
 */
function onMenuItemClicked(event, menuItem) {
    // Switch the form based on the clicked item ID
    elements.fc_content.containedForm = forms.[menuItem.itemId] //// menuItem.itemId gets the ID value of the clicked menu item, in this case being the same as the name of the corresponding form
}

Breadcrumbs

Provides a trail of links to allow users to trace their navigation history and easily go back to previous sections.

Basic Setup for Breadcrumbs in Servoy

To set up Breadcrumbs in Servoy, you typically create a main form that includes the Breadcrumbs component and a form container to display other forms. You will also create multiple secondary forms that represent each navigation page, and dynamically update the Breadcrumbs trail based on the user’s navigation path.

Step 1: Create the Forms

Main Form (e.g., main_form):
- This form holds the Breadcrumbs component and a form container (e.g., fc_content) where other forms will be displayed.
Secondary Forms (e.g., homeForm, orderForm, detailsForm):
- These represent the sections of your application the user navigates through (e.g., Home → Order → Details).

Step 2: Adding the Breadcrumbs Component

In main_form:
- Open the form editor and drag the Breadcrumbs component from the Navigation section onto the form.
- Configure the onCrumbClicked event in the properties panel or script editor to respond when users click a breadcrumb.

Step 3: Adding a Form Container to the Main Form

Still in main_form:
- Add a form container component (e.g., named fc_content) which will dynamically load the appropriate form based on the breadcrumb trail.

Step 4: Setting the Breadcrumbs Trail via Script You can configure the breadcrumb trail in two ways:

Option 1: Setting the Full Trail at Once Use the setCrumbs() API to define the complete trail when the form is shown:

/**
 * Called when the form is shown.
 */
function onShow(firstShow, event) {
    elements.breadcrumbs_nav.setCrumbs([
        { crumbId: "homeForm", displayName: "Home" },
        { crumbId: "orderForm", displayName: "Order" },
        { crumbId: "detailsForm", displayName: "Details" }
    ]);
    elements.fc_content.containedForm = forms.detailsForm;
}

In this example:

The trail will show Home > Order > Details.
The Details form is loaded into the form container.
The last crumb (Details) is automatically marked as active.

Option 2: Adding Crumbs One-by-One (Dynamic Trail) Use the addCrumb() API to build the trail dynamically as the user progresses:

/**
 * Called when the Home form is shown.
 */
function onHomeSelected() {
    elements.breadcrumbs_nav.addCrumb({ crumbId: "homeForm", displayName: "Home" });
    elements.fc_content.containedForm = forms.homeForm;
}

/**
 * Called when the user selects an order.
 */
function onOrderSelected() {
    elements.breadcrumbs_nav.addCrumb({ crumbId: "orderForm", displayName: "Order" });
    elements.fc_content.containedForm = forms.orderForm;
}

/**
 * Called when viewing order details.
 */
function onDetailsSelected() {
    elements.breadcrumbs_nav.addCrumb({ crumbId: "detailsForm", displayName: "Details" });
    elements.fc_content.containedForm = forms.detailsForm;
}

This approach is ideal for step-by-step flows (e.g., wizards, guided forms), where crumbs are added based on user decisions or path progression.

Step 5: Handling Breadcrumb Events Use the onCrumbClicked event to update the displayed form when a user clicks a breadcrumb:

/**
 * Called when a breadcrumb item is clicked.
 *
 * @param {JSEvent} event
 * @param {CustomType<bootstrapextracomponents-breadcrumbs.crumb>} crumb
 * @param {Number} index
 */
function onCrumbClicked(event, crumb, index) {
    elements.fc_content.containedForm = forms[crumb.crumbId];
}

Step 6: Auto-Remove Crumbs on Click (Optional) Enable the autoRemoveWhenClicked property to automatically remove all crumbs after the clicked one; you can do this in the properties panel of programmatically:

elements.breadcrumbs_nav.autoRemoveWhenClicked = true;

This is useful for workflows where the trail should be trimmed if the user goes back a step.

Hint: Custom Navigation Trail If your breadcrumb path depends on dynamic conditions or user input, use addCrumb() to build the trail incrementally.

Hint: Active Crumb When using setCrumbs(), the last crumb in the array is always marked as active.

Side Navigation: Best suited for applications with many categories, sub-menus, or hierarchical structures. It keeps navigation easy to access without overwhelming the user with too many horizontal options. Top Navigation: Suitable for applications with fewer primary sections. It's more compact and allows the rest of the page to be used for content without occupying vertical space.

PreviousInteracting with Components NextWindows, Dialogs and Popups

Last updated 7 days ago

Was this helpful?

Navigation

Navigation

Overview

Navigation Methods

Change Root Form

Using Form Containers and Buttons

Specialized Components for Navigation

Sidenav

Basic Setup for a Sidenav in Servoy

Step-by-Step Setup

Navbar

Basic Setup for a Navbar in Servoy

Why Choose Side Navigation vs Top Navigation?