Menus

Overview

The Menu feature in Servoy is a reusable design-time entity designed to simplify and centralize menu management within applications. By defining a menu once, developers can use it consistently across multiple components that rely on structured navigation. This approach streamlines application development, enhances maintainability, and ensures a uniform user experience.

Menus in Servoy are versatile and promote modular design, making it easy to share or restrict their use across different parts of an application. With its flexible design, the Menu feature integrates seamlessly into the application’s user interface, enabling developers to focus on functionality while maintaining consistent navigation across their solutions.

Benefits of Using the Menu Feature

• Consistency: Defining the menu structure once and applying it across multiple components ensures a uniform navigation experience for users.

• Efficiency: Reduces the need for repetitive manual configuration, saving development time and minimizing errors.

• Maintainability: Centralized menu management simplifies updates and modifications, as changes to the menu structure are automatically reflected across all linked components.

Get Started

The Servoy Menu feature simplifies navigation by enabling developers to create structured, reusable menus. This guide provides step-by-step instructions to help you efficiently implement and manage menus for a consistent user experience.

Create a Menu

Using Solution Explorer:

1. In the Solution Explorer, right-click the Menus node and select Create menu. This will open the New Menu Wizard.

2. Enter the name for the Menu, select the desired solution then click on the Finish button. This will open the Menu Editor. After clicking Save All the new Menu will be added to the menus' list.

   
3. Set up the Menu Properties

   
4. Create Menu Items

5. Set up Menu Items Properties

6. Click the Save All button (or ctrl+shift+s) to save all your editors

7. Assign the Menu to a component.

A complete list of Menu API methods can be found here.

Using "servoyMenu" property of a component:

1. In the component Properties Editor, click the servoyMenu property to open the Servoy Menu Selection Wizard

2. Click the name of the desired Servoy Menu

3. Click OK (to dismiss the Servoy Menu Chooser). This will assign the selected Servoy Menu to the component

4. Click the Save All button (or ctrl+shift+s) to save all your editors

Components List

The following components have a servoyMenu property:

• DataGrid

• Navbar

• Sidenav

Menu Item

Overview

The MenuItem is a versatile design-time entity used to define individual items within a menu structure. It supports hierarchical organization, allowing each item to be linked to either a parent menu or another menu item, enabling the creation of nested menus.

With its flexible design, MenuItem ensures seamless integration into menu structures, supporting rich customization and adaptability for various application needs. This makes it an essential component for building intuitive and consistent navigation systems.

Create a Menu Item

Using the Menu Editor:

Menu Editor appears right after creating a new menu or it can be accessed for an existing menu by right-clicking the menu name and selecting Edit menu option. This editor allows the users to add, remove and edit menu items and sub-menu items, including their properties.

Using the Menu Context Menu:

1. In the Solution Explorer, expand the Menus node, select the desired menu, right-click on it and select Create menu item. This will open the New MenuItem Wizard.

2. Enter the name for the Menu item and click on the OK button. This will add the new Menu item inside the specified Menu.

   
3. Set up the Menu Items Properties

   
4. Click the Save All button (or ctrl+shift+s) to save all your editors

A complete list of Menu Item API methods can be found here.

Design-Time Menu Properties

Here is a list of the Menu properties:

Comment

• Description: Allows developers to add notes or descriptive information about the purpose of the menu. These comments can serve as helpful reminders or context for future development and maintenance.

• Use Case: Use this property to document the intended use or special considerations for the menu, ensuring clarity for other developers or when revisiting the project later.

Encapsulation

• Description: Defines the visibility scope of the menu. The available options include:

  • Public: The menu is accessible across all modules, both in scripting and in the designer.

  • Module Scope: The menu is restricted to the same module, both in scripting and in the designer.

• Use Case: Choose the appropriate encapsulation mode based on whether the menu needs to be shared across multiple modules or kept specific to a single module for better modularity and access control.

Name

• Description: Serves as the unique identifier for the menu. This name is used to reference the menu in scripting or other configurations.

• Use Case: Assign a meaningful and intuitive name that reflects the menu's purpose or function to ensure clarity and ease of identification during development.

StyleClass

• Description: Enables the association of CSS classes for styling the menu. This property allows for customization of the menu's appearance to match the application's design.

• Use Case: Apply custom styles by specifying a CSS class that defines the menu's visual properties, such as color, fonts, or layout, ensuring it aligns with the application's overall theme.

Design-Time Menu Item Properties

Menu items in Servoy are highly configurable and can include properties tailored for specific components like Navbar or Sidenav, or for both. These properties allow developers to customize menu items' behavior, appearance, and functionality based on the target component. To ensure seamless integration, the servoyMenu property should be used in the appropriate component (e.g., Navbar or Sidenav), aligning the menu item’s configuration with the component’s requirements.

Here is a list of the Menu Item properties:

Global Properties

Global properties define the core attributes of a menu item, applicable regardless of where the item is used. These properties control fundamental aspects such as appearance, interactivity, and security. Developers can use them to configure essential elements like the menu item's text, styling, tooltip, and access permissions. Since these properties are universal, they apply to menu items used in both Navbar and Sidenav, ensuring a consistent user experience across different navigation components.

These Menu properties apply universally to all menu items, regardless of their placement or context:

Enabled

• Description: Determines whether the menu item is interactive or disabled.

• Use Case: Use this property to control the availability of menu items based on application state or user permissions.

IconStyleClass

• Description: Specifies a CSS class to style the icon associated with the menu item.

• Use Case: Use this to add visual context to menu items by styling their icons to match the application's theme.

Name

• Description: Uniquely identifies the menu item.

• Use Case: Assign a meaningful name to easily reference the menu item in scripting or configurations.

Permissions

• Description: Configures visibility and interactivity of the menu item based on user roles and permissions.

• Use Case: Use this to restrict access to certain menu items for unauthorized users, enhancing security.

StyleClass

• Description: Specifies a CSS class for styling the menu item’s appearance.

• Use Case: Apply this to customize the overall look and feel of the menu item.

Text

• Description: Displays the content of the menu item. Supports HTML and localized text for dynamic customization.

• Use Case: Use this to present descriptive text or HTML-formatted content for better clarity.

ToolTipText

• Description: Displays rich, formatted text when hovering over the menu item.

• Use Case: Add helpful descriptions or instructions for menu items using HTML-formatted tooltips.

DataGrid Properties

DataGrid properties apply to menu items used in the customMainMenu property of the DataGrid component. They allow developers to customize which columns specific menu items should appear for, or insert visual separators in the column menu.

These properties are specific to menu items used in the customMainMenu property of the DataGrid component:

hideForColIds

• Description: Specifies a comma-separated list of DataGrid's column IDs where the menu item should be hidden.

• Use Case: Use this to exclude the menu item from specific columns in the DataGrid's context menu.

isSeparator

• Description: Indicates that this menu item acts as a visual separator in the column menu.

• Use Case: Use this to group related options visually within the DataGrid's context menu.

showForColIds

• Description: Specifies a comma-separated list of DataGrid's column IDs where the menu item should be shown.

• Use Case: Use this to restrict the menu item to only appear for certain columns.

Navbar Properties

Navbar properties allow menu items to be adapted for horizontal navigation within the Navbar component. These properties introduce advanced configurations like input fields, buttons, and position alignment within the Navbar. Menu items in a Navbar can function as standard clickable options, interactive text fields, or buttons, providing flexibility in designing a structured and user-friendly navigation bar. Some properties also enable dynamic content binding via data providers and value lists, making the Navbar highly customizable.

These properties are specific to menu items used in the Navbar component:

Attributes

• Description: Defines additional custom HTML attributes for the menu item.

• Use Case: Use this property to add advanced configurations, such as data-* attributes or accessibility tags.

DataProviderValue

• Description: Links a data provider value to a text field, applicable only for menu items with the display types INPUT or INPUT_GROUP.

• Use Case: Use this to dynamically bind input fields to a data source, enabling real-time updates and interactions.

DisplayType

• Description: Controls the appearance of the menu item. Options include:

  • MENU_ITEM: Default menu item appearance.

  • TEXT: Displays plain text.

  • BUTTON: Renders the item as a button.

  • INPUT: Adds an input field.

  • INPUT_GROUP: Combines an input field with an optional button.

• Use Case: Adjust this property to define how a menu item should look and behave.

• Default Value: MENU_ITEM

InputButtonStyleClass

• Description: Specifies a CSS style class for the button shown with INPUT or INPUT_GROUP types. Typically used with Bootstrap button classes, such as btn-primary, btn-success, etc.

• Use Case: Apply this to style the button according to the application’s theme or functionality.

InputButtonText

• Description: Sets the text for the optional button shown with INPUT or INPUT_GROUP.

• Use Case: Use this to label the button with a relevant action or instruction.

IsActive

• Description: Indicates whether a MENU_ITEM item is shown as active.

• Use Case: Set this to true to highlight the current or selected menu item, improving navigation context for users.

• Default Value: False

Position

• Description: Determines whether the menu item appears on the left or right side of the Navbar.

• Use Case: Use this to organize menu items based on their placement within the navigation bar.

• Default Value: LEFT

TabIndex

• Description: Sets the tab order for the menu item in the navigation sequence.

• Use Case: Use this to improve keyboard navigation and accessibility for users.

UserData

• Description: Stores custom data associated with the menu item for reference purposes.

• Use Case: Use this to pass metadata or additional context for the menu item.

ValueList

• Description: Displays a typeahead list for INPUT or INPUT_GROUP menu items when set.

• Use Case: Use this to enhance user input fields with dynamic suggestions or predefined values.

Sidenav Properties

Sidenav properties are tailored for menu items used in the Sidenav component, which provides a vertical navigation structure. These properties allow additional visual and functional customizations, such as adding badges for notifications, defining dividers for better organization, and linking menu items to forms. Sidenav menu items can also be structured hierarchically, allowing for expandable and collapsible submenus. Developers can leverage these properties to create structured, data-driven, and visually distinct navigation menus.

These properties are specific to menu items used in the Sidenav component:

BadgeStyleClass

• Description: Specifies a CSS class for styling badges displayed alongside the menu item.

• Use Case: Use this to customize the appearance of notification badges.

BadgeText

• Description: Displays text within the badge associated with the menu item.

• Use Case: Use this to show, for example, counts or statuses, such as the number of notifications.

Data

• Description: Stores additional data specific to the menu item.

• Use Case: Use this to hold custom values or context for the menu item.

FormName

• Description: Links the menu item to a specific form.

• Use Case: Use this to define the form that should be opened when the menu item is clicked.

IsDivider

• Description: Indicates whether the menu item acts as a visual divider.

• Use Case: Use this to separate groups of menu items within the Sidenav for better organization.

RelationName

• Description: Defines a relation for dynamically populating the menu item.

• Use Case: Use this to create menu items based on related data.

How to apply security to a Menu Item

To control access to menu items based on user roles and permissions, Servoy provides a permissions property that enables security configurations. Follow the steps below to apply security settings to a menu item:

1. Open the Properties Panel

   • Select the Menu Item you want to secure in Solution Explorer.

   • Open the Properties panel to view the menu item’s attributes.

2. Locate the permissions property

   • In the Properties panel, find the permissions field under the Global Properties section.

   • Click on the field to open the permissions configuration dialog.

3. Configure Security Settings

   • The permissions dialog allows you to define which roles can view or enable the menu item.

   • Add or modify roles by selecting them from the available list.

4. Set Visibility and Access

   • Visible: Determines whether the menu item is displayed for a given user role.

   • Enabled: Controls whether the menu item is interactive or disabled for specific roles.

5. Apply and Save Changes

   • Click OK to confirm the security settings.

   • Save your changes to ensure that the menu item follows the configured access restrictions.

Security Options:

• Visible: If a menu item is not visible, users assigned to the restricted role will not see it in the application.

• Enabled: If a menu item is disabled, users with restricted permissions will see the menu item, but it will be inactive (grayed out or unclickable).

This method ensures that menu items are accessible only to authorized users, improving security and user experience.

Setting a Custom Property of a Menu Item

Menu Items in Servoy support custom properties, allowing developers to extend their functionality with additional configuration or metadata.

How to Set a Custom Property:

1. Open the Menu Editor of the desired menu.

2. Locate the Custom Properties section.

3. Click the Add Custom Property button.

4. Enter the property name and value.

5. Save the changes.

For a full walkthrough on how to define and manage custom properties, see: Adding Custom Properties in the Menu Editor.

Scripting a Menu

The Servoy Menu API enables developers to create, modify, and manage menus dynamically through scripting. Using the JSMenu object, you can define menu structures, add or remove menu items, retrieve existing menus, and control their behavior at runtime.

Here are some examples:

Creating and Managing Menus:

Create a New Menu

Method: menus.createMenu(name) Use Case: When dynamically creating a menu at runtime for different user roles or application states.

Example: Creating a menu named mainMenu:

var myMenu = menus.createMenu('mainMenu');

This menu can now be modified by adding items and configuring properties.

Retrieve an Existing Menu

Method: menus.getMenu(name) Use Case: When needing to modify an existing menu that was created at design time or earlier in runtime.

Example: Retrieving a menu named mainMenu:

var existingMenu = menus.getMenu('mainMenu');
if (existingMenu) {
    application.output('Menu found!');
} else {
    application.output('Menu not found.');
}

If the menu exists, it can be modified; otherwise, a new menu may need to be created.

Retrieve All Menus

• Method: menus.getMenus()

• Use Case: When listing or managing all available menus in an application.

Example: Listing all available menus:

var allMenus = menus.getMenus();
for (var i = 0; i < allMenus.length; i++) {
    application.output(allMenus[i].name);
}

This is useful for dynamically managing different menus based on application state.

Working with Menu Items:

Add a Menu Item

• Method: JSMenu.addMenuItem(id) or JSMenu.addMenuItem(id, index)

• Use Case: When adding new menu items dynamically at the end of the menu or at a specific position.

Example: Adding a new item dashboard at the end of the menu:

var myMenu = menus.getMenu('mainMenu');
var menuItem = myMenu.addMenuItem('dashboard');
menuItem.menuText = "Dashboard";

Adding an item reports at a specific position:

var myMenu = menus.getMenu('mainMenu');
var menuItem = myMenu.addMenuItem('reports', 1);
menuItem.menuText = "Reports";

This allows menu structures to be dynamically modified at runtime.

Retrieve a Menu Item by ID

• Method: JSMenu.getMenuItem(id)

• Use Case: When modifying properties of an existing menu item.

Example: Finding and modifying the dashboard menu item:

var myMenu = menus.getMenu('mainMenu');
var item = myMenu.getMenuItem('dashboard');
if (item) {
    item.menuText = "Dashboard Home";
}

This is useful for dynamically changing menu item labels.

Find a Menu Item (Including Nested Ones)

• Method: JSMenu.findMenuItem(id)

• Use Case: When searching for a menu item that may be deeply nested.

Example: Finding the settings menu item in a multi-level menu:

var myMenu = menus.getMenu('mainMenu');
var nestedItem = myMenu.findMenuItem('settings');
if (nestedItem) {
    application.output('Found settings menu!');
}

This helps when working with hierarchical menus.

Retrieve a Menu Item by Index

• Method: JSMenu.getMenuItemAt(index)

• Use Case: When looping through menu items sequentially.

Example: Getting the first menu item:

var myMenu = menus.getMenu('mainMenu');
var firstItem = myMenu.getMenuItemAt(0);
application.output(firstItem.text);

This can be useful when processing menu items dynamically.

Retrieve All Menu Items

• Method: JSMenu.getMenuItems()

• Use Case: When iterating over all menu items to apply changes or log data.

Example: Listing all menu items:

var myMenu = menus.getMenu('mainMenu');
var menuItems = myMenu.getMenuItems();
for (var i = 0; i < menuItems.length; i++) {
    application.output(menuItems[i].text);
}

This is helpful for bulk operations on menu items.

Removing and Selecting Menu Items:

Remove a Menu Item

• Method: JSMenu.removeMenuItem(menuItem) or JSMenu.removeMenuItem(id)

• Use Case: When dynamically updating menus based on conditions such as user permissions.

Example: Removing a menu item by reference:

var myMenu = menus.getMenu('mainMenu');
var menuItem = myMenu.getMenuItem('dashboard');
if (menuItem) {
    var success = myMenu.removeMenuItem(menuItem);
    application.output(success ? 'Item removed' : 'Failed to remove');
}

Removing a menu item by ID:

var myMenu = menus.getMenu('mainMenu');
var success = myMenu.removeMenuItem('reports');
application.output(success ? 'Reports removed' : 'Reports not found');

This helps keep menus relevant to user roles.

Select a Menu Item

• Method: JSMenu.selectMenuItem(menuItem)

• Use Case: When highlighting a specific menu item based on user navigation.

Example: Selecting the dashboard item:

var myMenu = menus.getMenu('mainMenu');
var menuItem = myMenu.getMenuItem('dashboard');
if (menuItem) {
    myMenu.selectMenuItem(menuItem);
}

This can be useful for guiding users through workflows.

Get the Selected Menu Item

• Method: JSMenu.getSelectedItem()

• Use Case: When tracking user selections to trigger events.

Example: Getting the currently selected menu item:

var myMenu = menus.getMenu('mainMenu');
var selectedItem = myMenu.getSelectedItem();
if (selectedItem) {
    application.output('Current selection: ' + selectedItem.text);
}

This is useful for building dynamic interfaces that respond to user actions.

Security and Menu Items

Retrieve Menu Items with Security Considerations

• Method: JSMenu.getMenuItemsWithSecurity()

• Use Case: When fetching only menu items that the user has permission to view.

Example: Getting all accessible menu items:

var myMenu = menus.getMenu('mainMenu');
var secureItems = myMenu.getMenuItemsWithSecurity();
for (var i = 0; i < secureItems.length; i++) {
    application.output('Accessible: ' + secureItems[i].menuText);
}

This method ensures that restricted items are not exposed to unauthorized users.

Scripting a Menu Item

The JSMenuItem API in Servoy allows developers to dynamically create, configure, and manage individual menu items. With its built-in methods, menu items can be customized with security settings, dynamically modified, or linked to specific application behaviors.