Navigation

Navigation

Content under construction

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.

Navigation Methods

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');
}

This method can be paired with side navigations or other components like navbars or breadcrumbs to enhance the navigation experience.

Specialized Components for Navigation

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.

Navbar

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

Basic Setup for a Navbar in Servoy

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.

1. Main Form (Containing the Navbar) The main form is the form that contains the navbar as well as a container to display the content of the different forms (such as a form container or tabless panel). This form serves as the "shell" that holds the navigation and dynamically switches between forms when the user interacts with the navbar.

2. Secondary Forms (Linked to the Navbar) These are the individual forms that represent the different sections or pages the user can navigate to. Each form will typically correspond to a specific page or section like Home, Dashboard, Reports, Settings, etc.

3. Form Container The form container (e.g., tabless panel or similar component) is used to dynamically load and display different forms when a navbar item is clicked. This allows the application to switch between forms without reloading the main form.

Step-by-Step Setup

Step 1: Create the Forms

1. Main Form (e.g., main_form):

• This form will hold the navbar and a form container where other forms will be displayed.

1. 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

1. 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. You can add items like Home, Dashboard, Settings, etc.

Step 3: Adding a Form Container to the Main Form

1. 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 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.

Advanced: Modules

Servoy provides specialized modules for advanced navigation patterns that are highly recommended for building scalable applications.

svyNavigation

A comprehensive navigation module that simplifies the setup of navigation logic, history management, and form switching. It offers pre-built components like side navigation and breadcrumbs.

svyNavigationUX

An extension of the svyNavigation module that includes advanced UX features and templates to streamline the navigation experience.

svyNavigationHistory

A module that allows managing navigation history, enabling users to go back and forth between different forms/pages without needing to manually manage the state.

Setting up Basic Navigation

When setting up basic navigation, you can choose between side navigation and top navigation. Here are the key differences:

• Side Navigation (Sidenav): Typically used for applications with a lot of sections, where vertical navigation (left-hand menu) makes it easier to switch between categories. It offers more space for hierarchical structures and is often combined with sub-menus.

• Top Navigation (Navbar): Works well for applications with fewer sections or where the navigation options are horizontal. It's often used for global navigation, with major categories laid out across the top of the page.

Example of Side Navigation:

// Side navigation with form switching
elements.sideNav.onItemClicked = function(item) {
    forms.mainForm.controller.show(item.formName);  // Load the selected form
};

Example of Top Navigation:

// Top navigation using a navbar component
elements.navbar.onItemClicked = function(item) {
    application.show(forms[item.formName]);  // Load the selected form
};

Why Choose Side Navigation vs Top Navigation?

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.

Building Navigation From Scratch

If you prefer not to use pre-built modules (like svyNavigation), you can build your own navigation system from scratch, though it is not recommended due to the complexity and maintenance involved.