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

Here are the steps for creating a Sidenav:
Open the Form Editor of the form where you need to place a Sidenav component
Find Sidenav in the Navigation section in the components' palette
Drag and drop the Sidenav component in the desired place of the form
Edit other Sidenav properties and Sidenav menu item properties, if the case
Setting the Menu
The Sidenav component supports two ways to configure its menu:
Using
servoyMenu
property: Assign a predefined servoyMenu for centralized menu management.Using
menu
property: Manually define menu items directly inside the component.
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
:
In the Properties Panel of the Sidenav component, locate the
servoyMenu
property and click on its value. This will open the Servoy Menu Selection WizardSelect an existing
servoyMenu
from the list.When a
servoyMenu
is assigned, its menu items are automatically applied to the Sidenav component.
Setting the menu items in the properties panel

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:
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.
Expand the
menu
property to see the list of menu items. They are also shown in the Sidenav component (in the form editor)In order to edit each menu item, expand it in the Properties Panel and set its properties
Submenu items can be added by clicking the
+
button of the parent menu item and following the same steps.
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:
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 itemtext
: displayed text for the menu itemenabled
: enables the menu itemisDivider
: if this property is set totrue
, then the menu item will be displayed as a visually divider linemenuItems
: 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 itemrelationName
: here the user can set an existing relation in case the contained form needs to be loaded through a specific relationformName
: 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);
Last updated
Was this helpful?