Navbar

Overview

Navbar demo

A Navbar in Servoy is a horizontal navigation bar typically placed at the top of the application interface. It is used to provide users with quick access to major sections or features of the application. The navbar often contains links or buttons that allow users to navigate between different forms or pages in a consistent and intuitive manner.

Navbars are commonly used in applications to enhance user experience by offering easy access to global navigation options like Home, Dashboard, Settings, and more. They can also contain additional elements like dropdowns, search fields, and icons for notifications, user profiles, or other utility actions.

The Navbar component wraps a bootstrap navbar (see here for details) into a component usable directly from within Servoy.

Key Features of a Navbar:

• Horizontal Layout: The navbar provides a horizontal layout for navigation items, usually placed at the top of the application. This layout ensures that major sections of the application are always visible and accessible.

• Navigation Links: The navbar contains buttons or links that allow users to navigate to different forms or sections of the application. These links can represent different views or modules, such as Dashboard, Reports, or Settings.

• Dropdown Menus: The navbar can include dropdown menus for nested or grouped navigation options. This is useful when you want to offer multiple related options under a single menu item, such as user settings or report types.

• Search Field: Navbars often include a search input field to allow users to quickly search through the application or specific data, providing a more comprehensive and functional navigation experience.

• Utility Icons: Navbars may also include icons for additional utilities such as notifications, messages, or profile settings. These icons typically have contextual dropdowns or links associated with them.

• Responsive Design: In responsive layouts, the navbar can adapt to different screen sizes, collapsing into a hamburger menu on smaller screens to save space while still providing easy access to the navigation items.

Use Cases for Navbar

• Global Application Navigation: In applications with global sections (e.g., Dashboard, Reports, Settings), the navbar provides quick access to these areas while maintaining consistency across the interface.

• Modular Systems: For modular systems like admin dashboards or content management systems, the navbar allows users to easily switch between modules or sections.

• User Profile and Utility Actions: The navbar is ideal for placing user-related actions like profile management, notifications, settings, and logout. These can be accessed through icons or dropdowns.

• Responsive Applications: In responsive applications, the navbar can collapse into a hamburger menu for mobile or tablet users, making navigation accessible without taking up too much screen space.

Get Started

Creating a Navbar component

Create a Navbar

Here are the steps for creating a Navbar:

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

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

4. Set the menu items; this can be done via properties panel
5. Edit other Navbar properties and Navbar menu item properties

---

Hint

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

1. Open the Form Editor of the form where you need to place a Navbar 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 Navbar[bootstrapextracomponents] 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 Navbar 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 Navbar menu item properties.

Setting the Menu

The Navbar 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 Navbar. 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 Navbar 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 Navbar 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 Navbar 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 Navbar menuItems 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 Navbar in the form editor, click it and proceed with the following steps:

1. Add a menu item:

   • Select the menuItems 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 menuItems property to see the list of menu items. They are also shown in the Navbar component (in the form editor)
3. In order to edit each menu item, expand it in the Properties Panel and set its properties

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

Working with Navbar

A Navbar is a simple navigation bar that offers:

• an optional branding logo on the left

• an optional branding text on the left

• two bars with any number of items

• plain texts

• single clickable menu entries

• dropdown menus showing a menu (one level)

• buttons

• text fields (optionally as type aheads)

One of the two bars is aligned to the left, the other to the right. Either one or both can be set.

Each item in the bar is a MenuItem javascript object with a position (LEFT or RIGHT) and a displayType (e.g. BUTTON) that controls how the single entry is displayed. Depending on the displayType a MenuItem's properties can have component specific meaning (for example the text property is used as placeholder text for an input field).

You can find a list of Navbar properties here.

Setting the Brand

Navbar has a few properties that allow setting and customizing branding logo and text:

• brandLogo: an optional media shown as branding logo in the upper left corner.
• brandLogoStyleClass: optional style class(es) that can be added to the brandLogo media.
• brandLogoTabindex: sets the tab index for brand logo
• brandText: an optional branding text shown in the upper left corner (after the optional brandLogo)
• brandTextTabindex: sets the tab index for brand text

Set the Navbar's position

Navbar's position can be set in fixed property. This property controls whether the toolbar is fixed to either top or bottom of the screen.

Distinct Active Menu Item

Setting the markClickedItemActive property to true, items of displayType: MENU_ITEM will be shown as "active" when clicked.

Setting menu item's properties

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

Properties to be set:

• item: Identifier of a menu item. This property is required to allow the component to figure out what item a user selected

• text: The text shown. Is used as placeholder text on INPUT or INPUT_GROUP items

• displayType: Controls the appearance of the menu item:

  • MENU_ITEM (default)

  • TEXT

  • BUTTON

  • INPUT

  • INPUT_GROUP

• subMenuItems: An optional array of sub menus for a MENU_ITEM type. When set, the item will be shown as a dropdown

• enabled: enables the menu item

• iconName: An optional icon added to the menu item. Any glyhicon or font awesome icon can be used (e.g. "glyphicon glyphicon-search" or "fa fa-car"). When used with INPUT or INPUT_GROUP used as the button's icon.

• inputButtonStyleClass: Style class to control the optional button shown with INPUT or INPUT_GROUP. Typically one of bootstraps button classes ("btn-default", "btn-primary", "btn-success", "btn-info", "btn-warning", "btn-danger", "btn-link"). Default is "btn-default"

• isActive: When true, a MENU_ITEM item will be shown as active

• position: Controls whether an item is shown on the left or on the right of the navbar. Default is LEFT

• styleClass: Additional style class(es) of the component

• tooltip: An optional tooltip for the item

• valuelist: When set, an INPUT or INPUT_GROUP item will show a typeahead list.

• onAction: Function that will be called if the item is clicked on (MENU_ITEM, BUTTON), a submenu is selected (MENU_ITEM with subMenuItems) or the user hits enter, leaves the field or clicks the optional button (INPUT, INPUT_GROUP). If not set, the component will call the onMenuItemClicked method assigned to the component itself.

Menu Item DisplayType

Menu item displayType property has the following options:

DisplayType: MENU_ITEM (default)

Simple clickable entry in the navbar.

Example with just the text:

MenuItem Text

Example with icon and submenus:

MenuItem Dropdown

Example of an opened submenu:

MenuItem Dropdown opened

For an item of displayType:MENU_ITEM the MenuItem properties are used as:

Property	Usage
dataProvider	not used
iconName	icon to the left of the entry's name
inputButtonStyleClass	not used
inputButtonText	not used
subMenuItems	When set, the item will be shown as a dropdown menu
valuelist	not used
onAction	Fired when the user clicks on the item or selects an item from the dropdown menu

---

DisplayType: TEXT

Plain text shown in the bar:

Text

For an item of displayType:TEXT the MenuItem properties are used as:

Property	Usage
dataProvider	not used
iconName	icon to the left of the entry's name
inputButtonStyleClass	not used
inputButtonText	not used
subMenuItems	not used
valuelist	not used
onAction	not fired

---

DisplayType: BUTTON

A normal button.

Example with text "Button 1", iconName "glyphicon glyphicon-camera" and styleClass "btn-primary":

Button

For an item of displayType:BUTTON the MenuItem properties are used as:

Property	Usage
dataProvider	not used
iconName	icon to the left of the entry's name
inputButtonStyleClass	not used
inputButtonText	not used
subMenuItems	not used
valuelist	not used
onAction	fired when the user clicks on an item
styleClass	Button style class. Typically one of bootstraps button classes ("btn-default", "btn-primary", "btn-success", "btn-info", "btn-warning", "btn-danger", "btn-link"). Default is "btn-default".

---

DisplayType: INPUT

An item of type INPUT adds a text field to the navbar. The text field can have an optional button grouped next to it when the inputButtonText or iconName (or both) property is set.

Example with iconName and inputButtonText:

Input

For an item of displayType:INPUT the MenuItem properties are used as:

Property	Usage
dataProvider	used to assign the dataprovider of the field
iconName	When set a button with that icon is shown next to the input field. Any glyhicon or font awesome icon can be used (e.g. "glyphicon glyphicon-search" or "fa fa-car").
inputButtonStyleClass	Used for the optional button. Typically one of bootstraps button classes ("btn-default", "btn-primary", "btn-success", "btn-info", "btn-warning", "btn-danger", "btn-link"). Default is "btn-default".
inputButtonText	When set a button with the text is shown next to the input field.
subMenuItems	not used
valuelist	When set, the input will show a typeahead list.
onAction	fired when the user hits enter in the field, leaves the field or clicks on the optional button next to the field.

---

DisplayType: INPUT_GROUP

An item of type INPUT_GROUP behaves the same as INPUT except that the field is rendered along with optional button as an inputgroup. There is no spacing between the field and the button.

Example with iconName and inputButtonText:

Inputgroup

Scripting Navbar

Main events

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

Let's consider the following setup:

• main_form: the form where the Navbar component is placed, together with a form container component, fc_nav

  • Navbar component has the following menu items:

    • item:home, displayName:Home

    • item:menu_item1, displayName:Menu Item #1

    • item:menu_item2, displayName:Menu Item #2

    • item:menu_item3, displayName:Menu Item #3

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

onBrandClicked

This event is called when the user clicks on the brand logo or text. Here is an example of how to use the onBrandClicked event of Navbar in the Scripting Editor. The following goes on main_form script file:

/**
 * Called when the user clicks on the brand logo or text.
 *
 * @param {JSEvent} event
 *
 * @private
 *
 * @properties={typeid:24,uuid:"A122138E-AA11-4570-9A94-C1C7454C579D"}
 */
function onBrandClicked(event) {
  elements.fc_nav.containedForm = forms.home; // shows the `Home` form in the form container when clicking on brand logo or text
}

onMenuItemClicked

This event is called when a menu item is clicked. Here is an example of how to use the onMenuItemClicked event of Navbar in the Scripting Editor. The following goes on main_form script file:

/**
 * Called whenever a menu item is clicked or a submenu item is selected with the JSEvent and the menuItem object clicked on.
 *
 * @param {JSEvent} event
 * @param {CustomType<bootstrapextracomponents-navbar.menuItem>} menuItem
 *
 * @private
 *
 * @properties={typeid:24,uuid:"6F2D94B3-C80F-4086-976C-0DAFBF05E256"}
 */
function onMenuItemClicked(event, menuItem) {
	elements.fc_nav.containedForm = forms[menuItem.itemId] // menuItem.itemId gets the ID value of the clicked menu item
}

Setting menu items for a manually configured component's menu

Sets all menu items of the navbar. The branding remains untouched. Here is an example of how to use the setMenuItems event of Navbar in the Scripting Editor:

var menuItems = [];

menuItems.push({itemId: '1', text: 'Accounts', tooltip: 'Accounts'});
menuItems.push({itemId: '2', text: 'Invoices', tooltip: 'Invoices'});
menuItems.push({itemId: '3', text: 'Click me', displayType: 'BUTTON', tooltip: 'Button'});
menuItems.push({text: 'Payables', tooltip: 'Payables'});
menuItems.push({itemId: '5', text: 'Search account...', displayType: 'INPUT', iconName: 'glyphicon glyphicon-search', tooltip: 'Search'});
menuItems.push({itemId: '6', text: 'Menu', position: 'RIGHT', tooltip: 'A submenu', subMenuItems: [{itemId: '6.1', text: 'Action'}, {itemId: '6.2', text: 'More action'}, {isDivider: true}, {itemId: '6.3', text: 'Last action'}]});
menuItems.push({itemId: '7', text: 'Logged in as John Doe', tooltip: 'just text', displayType: 'TEXT', position: 'RIGHT'});

elements.navbar.brandText = 'Accounting';
elements.navbar.setMenuItems(menuItems);

Add a menu item

Adds the given item to the navbar. Here is an example of how to use the addMenuItem event of Navbar in the Scripting Editor:

For a manually configured Menu:

/** @type {bootstrapextracomponents-navbar.menuItem} */
var itemToAdd = {
	itemId: application.getUUID().toString(), 
	text: 'Item added'
}
elements.navbar.addMenuItem(itemToAdd);

---

For an assigned servoyMenu:

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

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

Remove menu Item

Removes the item with the given itemId from the bar. Here is an example of how to use the removeMenuItem event of Navbar in the Scripting Editor:

For a manually configured Menu:

/**
 * Fired when the button is clicked.
 *
 * @param {JSEvent} event
 *
 * @private
 *
 * @properties={typeid:24,uuid:"01F79B4C-917A-44A6-8499-F99D4611FA5F"}
 */
function onAction$remove(event) {
	elements.navbar.removeMenuItem(`menu_item3`); // `menu_item3` is the id of the item we want to remove from the menu
}

---

For an assigned servoyMenu:

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

// remove menu item 
menu.removeMenuItem("menu_item3") // `menu_item3` is the id of the item we want to remove from the menu

Set selected menu item

Sets the item with the given ID as selected (sets the isActive property). Items of type MENU_ITEM will be rendered with a different background color when selected. Here is an example of how to use the setMenuSelected event of Navbar in the Scripting Editor:

For a manually configured Menu:

/**
 * Fired when the button is clicked.
 *
 * @param {JSEvent} event
 *
 * @private
 *
 * @properties={typeid:24,uuid:"01F79B4C-917A-44A6-8499-F99D4611FA5F"}
 */
function onAction$setMenuSelected(event) {
	elements.navbar.setMenuSelected(`menu_item3`); // `menu_item3` is the id of the item we want to set as selected - active
}

---

For an assigned servoyMenu:

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

// remove menu item 
menu.selectMenuItem("menu_item3") // `menu_item3` is the id of the item we want to set as selected - active

Get the selected menu item

Returns the currently selected menu item. Here is an example of how to use the getSelectedMenu event of Navbar in the Scripting Editor:

For a manually configured Menu:

/**
 * Fired when the button is clicked.
 *
 * @param {JSEvent} event
 *
 * @return {CustomType<bootstrapextracomponents-navbar.menuItem>} selected
 * 
 * @private
 *
 * @properties={typeid:24,uuid:"01F79B4C-917A-44A6-8499-F99D4611FA5F"}
 */
function onAction$getSelectedMenu(event) {
	var selected = elements.navbar.getSelectedMenu(); // Returns the currently selected menu item
  return selected;
}

---

For an assigned servoyMenu:

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

// remove menu item 
menu.getSelectedItem() // Returns the currently selected menu item