sidenav

Overview

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. The sidenav allows users to quickly navigate between different sections or forms within the application. This type of navigation is common in modern web and mobile applications and provides a consistent, easy-to-use navigation structure for users, especially when there are multiple sections or forms to manage.

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

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 Navigation section in the components' pallet

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

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

5. Edit other Sidenav properties and Sidenav menu item properties

Setting the menu items (in the properties panel)

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. Next menu item can be added 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

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

Working with Sidenav

Setting the contained form

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

Setting header and footer

Sidenav component can have 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 menu item's properties

A complete list of menu item's properties ca 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 divier 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_menu.containedForm = forms[menuItemId]; // menuItemId gets the ID value of the clicked menu item
	return false;
}

Setting menu items

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.

Menu Item properties can be found here.

This is a menu item with 2 sub menu items:

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

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:

 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

Setting sub-menu items

Set the menuItems as sub menu items of the menu item with id menuItemId, return 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:

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

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

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"

Remove all menu items

If depth is specified removes all the menu items at depth. If depth is equal to 1 all roots will be removed. 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);