sidenav

Overview

Sidenav demo

A Sidenav (short for side navigation) in Servoy is a UI component that provides a vertical navigation menu typically placed on the left (or sometimes right) side of an application interface. Sidenav allows users to navigate quickly between different sections or forms within the application. This type of navigation is common in modern web and mobile applications, providing a consistent and intuitive structure, particularly when managing multiple sections or forms.

Key Features of Sidenav:

• Multi-Level Navigation (Up to 4 Levels): The sidenav can manage nested items up to 4 levels deep. Each level can have selectable and collapsible items, where one item can be selected and expanded at a time.

• Collapsible and Expandable Menu Items: Menu items within the sidenav can be collapsed or expanded, giving users control over how much information is visible at any given time. When an item is selected, its child items (if any) are automatically expanded.

• Programmatic Control: The sidenav component can be controlled programmatically, allowing developers to modify its runtime properties and trigger actions through the component’s API.

• Form Container Integration: The sidenav can serve as a form container that displays a form alongside the menu. This form animates together with the menu when it slides in or out, creating a seamless user experience.

Use Cases for Sidenav

• Multi-Section Applications: In applications with multiple sections or areas (such as an admin panel, content management system, or e-commerce platform), a sidenav provides a clear, structured way to navigate between forms or modules.

• Hierarchical Navigation: For applications that require deep, hierarchical navigation (e.g., categories and subcategories in a product catalog), sidenav is ideal for letting users drill down into different levels of the hierarchy.

• Responsive Design: In mobile and responsive applications, the sidenav can be made collapsible or hidden on smaller screens, giving users access to navigation when needed while conserving screen space.

Get Started

Creating a Sidenav component

Create a Sidenav

Here are the steps for creating a Sidenav:

1. Open the Form Editor of the form where you need to place a Sidenav component
2. Find Sidenav in the Navigation section in the components' palette

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

4. Set the menu
5. Edit other Sidenav properties and Sidenav menu item properties, if the case

---

Hint

In case there is an existing Servoy Menu that will be used as a Sidenav menu, then here are the steps to be followed:

1. Open the Form Editor of the form where you need to place a Sidenav component
2. Find the desired Servoy Menu name in the Servoy Menu section in the components' palette

3. Drag and drop the desired Servoy Menu name in the form. This will open the JSMenu compatible component selector
4. Select sidenav[servoyextra] option, then click OK. This will add to the main form a Sidenav component having the desired Servoy Menu name set for servoyMenu property of the component
5. Configure Sidenav properties in the component's properties panel. If needed, you can change or remove the assigned servoyMenu. In this case, you must manually configure the Sidenav menu item properties.

Setting the Menu

The Sidenav component supports two ways to configure its menu:

1. Using servoyMenu property: Assign a predefined servoyMenu for centralized menu management.
2. Using menu property: Manually define menu items directly inside the component.

Using either a manually configured menu or servoyMenu will not change the appearance of the Sidenav. Both methods result in the same UI layout, styling, and interactions, including menu item rendering, nested structures, icons, and animations. The only difference is in how the menu items are configured and managed.

IMPORTANT! If both methods are used, the manually configured menu will take precedence, and the servoyMenu will be ignored.

Assigning an existing servoyMenu

Instead of configuring the menu manually, you can assign a predefined servoyMenu in Sidenav servoyMenu property, which allows you to:

• Centrally manage menus across multiple components.

• Easily update menus without modifying individual Sidenav components.

• Use the same menu structure in different parts of the application.

To assign a servoyMenu:

1. In the Properties Panel of the Sidenav component, locate the servoyMenu property and click on its value. This will open the Servoy Menu Selection Wizard
2. Select an existing servoyMenu from the list.

3. When a servoyMenu is assigned, its menu items are automatically applied to the Sidenav component.

Setting the menu items in the properties panel

Adding and editing menu items and sub menu items

You can configure menu items directly in the Sidenav menu property. This allows fine-grained control over the menu structure, including:

• Adding menu items manually.

• Defining sub-menus (up to 4 levels deep).

• Setting icons, styles, and form associations.

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

1. Add a menu item:

   • Select the menu property and click the + button in order to add a menu item. You can add the next menu item in the same way or by clicking the + button (insert a new array item below) of another menu item.
2. Expand the menu property to see the list of menu items. They are also shown in the Sidenav component (in the form editor)
3. In order to edit each menu item, expand it in the Properties Panel and set its properties
4. Submenu items can be added by clicking the + button of the parent menu item and following the same steps.

Sidenav menu items It is necessary to set a unique id in the Sidenav menu item id property. Example: home_page.

Working with Sidenav

You can find a list of Sidenav properties here.

Setting the contained form

The initial form to be displayed can be set by selecting a form name in the component's Properties Panel containedForm property.

Setting header and footer

Sidenav component can include forms acting like headers and footers. This is done by selecting a form name in the component's Properties Panel for the following properties:

• headerForm
• footerForm

Setting component's menu item's properties

A complete list of component's menu item's properties can be found here.

Important properties to be set:

• id: it represents the menu item ID, it is mandatory and must be unique for each menu item

• text: displayed text for the menu item

• enabled: enables the menu item

• isDivider: if this property is set to true, then the menu item will be displayed as a visually divider line

• menuItems: this property is set exactly as a menu item; here the user can set sub-items for a menu item; each sub-item has the same kind of properties as a main item

• relationName: here the user can set an existing relation in case the contained form needs to be loaded through a specific relation

• formName: the user can set here the contained form corresponding to each menu item

Scripting Sidenav

Main events

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

onMenuItemSelected

This event is called when a menu item is clicked. Here is an example of how to use the onMenuItemSelected event of Sidenav in the Scripting Editor: Let's consider the following setup:

• main_form: the form where the Sidenav component is placed:

  • Sidenav component has the following menu items:

    • id:menu_item1, text:Menu Item #1

    • id:menu_item2, text:Menu Item #2

    • id:menu_item3, text:Menu Item #3

• separate forms showed in main_form as a contained form in the Sidenav component: menu_item1, menu_item2, menu_item3.

The following goes on main_form script file:

/**
 * @param menuItemId
 * @param {JSEvent} event
 *
 * @return {Boolean}
 *
 * @private
 *
 * @properties={typeid:24,uuid:"D1C19804-0E6A-44C2-B5D4-8934E5B5F5F5"}
 */
function onMenuItemSelected(menuItemId, event) {
	elements.sidenav.containedForm = forms[menuItemId]; // menuItemId gets the ID value of the clicked menu item
	return false;
}

Setting menu items for a manually configured component's menu

Use the api setRootMenuItems to populate the sidenav with Menu Items. You can nest Menu Items up to 4 levels depth.

var menu = [{
    id: 1,
    text: "Sample Item #1",
    styleClass : "sn-large",
    iconStyleClass:  "glyphicon glyphicon-search",
    data: { description: "This is sample information that can be added to a menuItem" },
    menuItems: [{
  	  id: 5,
  	  text: "Sub Item #1"
  	}, {
  	  id: 6,
  	  text: "Sub Item #2"}]
  }, {
    id: 2,
    text: "Sample Item #2"
  },{
    isDivider: true
  },{
    id: 3,
    text: "Sample Item #3",
    enabled: false
}];

  elements.sideNavigation.setRootMenuItems(menu);

The method setRootMenuItems requires an Array of Menu Item object.

Menu Item

The menu item is a JSON object representing an item in the sidenav. A menu item may nest other menu items. A menu item may be also used as divider, which is nothing else then a line separating the menu item above and below, in this case all other properties of the menu item are ignored.

Component's Menu Item properties can be found here. ServoyMenu's Menu Item properties for Sidenav component can be found here.

This is a menu item with 2 sub menu items:

For a manually configured Menu:

var menuItem = {
    id: 1,
    text: "Sample Item #1",
    styleClass : "sn-large",
    iconStyleClass:  "glyphicon glyphicon-search",
    data: { description: "This is sample information that can be added to a menuItem" },
    menuItems: [{
  	  id: 5,
  	  text: "Sub Item #1"
  	}, {
  	  id: 6,
  	  text: "Sub Item #2"}]
  };

This menu item is instead rendered as a divider:

 var menuDivider = {
    isDivider: true
  };

---

For an assigned servoyMenu:

// Get reference to servoyMenu
var menu = elements.sidenav.servoyMenu;

// Create a new menu item
var newItem = menu.addMenuItem("item1");
newItem.menuText = "Sample Item #1";
newItem.iconStyleClass = "glyphicon glyphicon-search";

// Add sub-menu items
var subItem1 = newItem.addMenuItem("sub_item1");
subItem1.menuText = "Sub Item #1";

var subItem2 = newItem.addMenuItem("sub_item2");
subItem2.menuText = "Sub Item #2";

Add a Menu Item

Add a menu item. The menu is added as sub Menu Item if a menuItemId is provided, otherwise is added in root. If index is provided the menu is added at the specified index position, otherwise is added as last element. Return false if menuItemId cannot be found. Here is an example of how to programmatically add a menu item in the Scripting Editor of the main form, using the the addMenuItem:

For a manually configured Menu:

 var menuItem = {
  id: 100,
  text: "Sample Item #1",
  styleClass : "nav-large nav-primary",
  iconStyleClass:  "glyphicon glyphicon-search",
  data: { description: "This is sample information that can be added to a menuItem" },
  menuItems: [{
  	id: 101,
  	text: "Sub Item #1"
  	}, {
  	id: 102,
  	text: "Sub Item #2"}]
  };
  elements.sideNavigation.addMenuItem(menuItem, 1, 0); // parameters are : menuItem, menuItemId, index

---

For an assigned servoyMenu:

// Get reference to servoyMenu
var menu = elements.sidenav.servoyMenu;

// Create a new menu item
var newItem = menu.addMenuItem("item1");
newItem.menuText = "Sample Item #1";
newItem.iconStyleClass = "glyphicon glyphicon-search";

Setting sub-menu items

Set the menuItems as sub-menu items of the menu item with id menuItemId. This function returns false if menuItemId cannot be found. Here is an example of how to programmatically set sub-menu items in the Scripting Editor of the main form, using the the setSubMenuItems:

For a manually configured Menu:

var menuItems = [{
  id: 10,
  text: "Sample Item #1",
  styleClass : "sn-large",
  iconStyleClass:  "glyphicon glyphicon-search",
  data: { description: "This is sample information that can be added to a menuItem" },
  menuItems: [{
  	id: 12,
  	text: "Sub Item #1"
  	}
  }]
  }, {
  id: 11,
  text: "Sample Item #2"
  },{
  isDivider: true
  }];
  elements.sideNavigation.setSubMenuItems(menuItems);

---

For an assigned servoyMenu:

// get reference to the desired menu item
var menuItem = elements.sidenav.servoyMenu.getMenuItem("item1");

// Add sub-menu items
var subItem1 = menuItem.addMenuItem("sub_item1");
subItem1.menuText = "Sub Item #1";

var subItem2 = menuItem.addMenuItem("sub_item2");
subItem2.menuText = "Sub Item #2";

Update a Menu Item

To update a menu item you should get the menu item object using the component's API getMenuItem, any change to the returned object will be reflected on the sidenav component.

Example For a manually configured Menu:

var menuItem = elements.sidenav.getMenuItem(1);
menuItem.text = "Update the text of the menuItem";
menuItem.styleClass = "nav-large nav-bold";
menuItem.data = { "lastUpdate" : new Date(); }

Updating an old reference of the menuItem which has not been retrieved via API it won't be possible.

Don't do this:

var menuItem = { id:1, text: "init text"};
elements.sidenav.addMenuItem(menuItem);
menuItem.text = "Update text of menu item 1 like this is not reflected on UI"

Instead do:

var menuItem = { id:1, text: "init text"};
elements.sidenav.addMenuItem(menuItem);
// get the menuItem via API
menuItem = elements.sidenav.getMenuItem(1); 
menuItem.text = "Update text of menu item 1 like this is correct"

---

For an assigned servoyMenu:

// get the menuItem via API
var menuItem = elements.sidenav.servoyMenu.getMenuItem("item1");

//update the menu item as needed
menuItem.menuText = "Update the text of the menuItem";
menuItem.styleClass = "nav-large nav-bold";

Remove all menu items

If a depth value is specified, all menu items at that depth will be removed. If the depth is set to 1, all root menu items will be removed. The default depth is 1. Here is an example of how to programmatically remove all menu items in the Scripting Editor of the main form, using the the clearMenuItems:

 // clear the whole menu removing all nodes. 
 elements.sidenav.clearMenuItems();
  
 // clear menu at depth 2 removes the sub menu items of each root menu.
 elements.sidenav.clearMenuItems(2);