ServoyCloudSupportSamplesOpen SourceCommunity

Navbar

Overview

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

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

Setting the menu items (in the properties panel)

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 itmes

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

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 ca 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:

Example with icon and submenus:

Example of an opened submenu:

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:

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":

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:

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:

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

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:

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

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:

/**
 * 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
}

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:

/**
 * 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
}

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:

/**
 * 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;
}
PreviousBreadcrumbsNextsidenav

Last updated