JSMenuItem

Overview

The JSMenuItem scripting wrapper provides functionality for managing menu items in a Servoy application. It supports configuration and interaction through constants, properties, and methods, enabling dynamic customization of menu behavior and appearance. ## Functionality

Constants such as ENABLED and VIEWABLE control security flags, determining whether menu items are accessible or visible. Properties like callbackArguments, enabled, iconStyleClass, itemID, menuText, styleClass, and tooltipText allow precise customization of menu item attributes, including visual styling, text, and state.

The functionality includes methods to manage menu items dynamically. Developers can add new items using methods like addSubMenuItem, which supports specifying positions, or retrieve existing items through methods such as getSubMenuItem and getSubMenuItemAt. Items can also be removed using the removeSubMenuItem method.

Security and visibility features allow control over menu item behavior. The setSecurityFlags method, combined with constants like ENABLED and VIEWABLE, provides flexibility to set whether a menu item is visible and interactive. Additional methods, such as getEnabledWithSecurity and getSubMenuItemsWithSecurity, refine the interaction by considering security constraints.

Properties and additional functionality extend to retrieving extra information, such as through the getExtraProperty method, and updating the menu item’s appearance and behavior dynamically. These capabilities make JSMenuItem a versatile tool for creating adaptive and secure menu systems in Servoy applications.

MenuItem section of this documentation

Constants Summarized

Type	Name	Summary
Number	ENABLED	Constant representing the enabled flag for menu item security.
Number	VIEWABLE	Constant representing the viewable flag for menu item seurity.

Properties Summarized

Type	Name	Summary
Array	callbackArguments	Set/Get the menu item callback arguments (for components that support this)
Boolean	enabled	Set/Get the menu item enabled state
String	iconStyleClass	Set/Get the menu item space separated icon style classes
String	menuText	Set/Get the menu item text
String	name	The menu name (identifier)
String	styleClass	Set/Get the menu space separated styleclases
String	tooltipText	Set/Get the menu item tooltip text

Methods Summarized

Type	Name	Summary
JSMenuItem	addMenuItem(id)	Adds a new menu item, as last item in the list.
JSMenuItem	addMenuItem(id, index)	Adds a new menu item, at a specific position.
JSMenuItem	findMenuItem(id)	Gets a menu item by identifier.
Object	getCustomProperty({String})	Returns custom property value.
Boolean	getEnabledWithSecurity()
Object	getExtraProperty({String})	Returns an extra property value.
JSMenuItem	getMenuItem(id)	Gets a menu item by identifier.
JSMenuItem	getMenuItemAt(index)	Gets a menu item by index (0 based).
Array	getMenuItems()	Returns all the menus items, either created at design time or at runtime, in the order they will show up in user interface.
Array	getMenuItemsWithSecurity()
JSMenuItem	getSelectedItem()
Boolean	removeMenuItem(menuItem)	Removes a menu item from children's list, returns true if element was found an removed
Boolean	removeMenuItem(id)	Removes a menu item with given id, returns true if element was found an removed
void	selectMenuItem(menuItem)	Selects a menu item in user interface
void	setCustomProperty({String}, {Object})	Sets a custom property value.
void	setExtraProperty({String}, {Object})	Sets an extra property value (property must be present in the component spec).
void	setSecurityFlags(flags)	Override the permission data and design data (for enabled flag) and set if a menu item is viewable(visible) and enabled.

Constants Detailed

ENABLED

Constant representing the enabled flag for menu item security.

Type Number

Sample

menuItem.setSecurityFlags(JSMenuItem.VIEWABLE|JSMenuItem.ENABLED);

VIEWABLE

Constant representing the viewable flag for menu item seurity.

Type Number

Sample

menuItem.setSecurityFlags(JSMenuItem.VIEWABLE|JSMenuItem.ENABLED);

Properties Detailed

callbackArguments

Set/Get the menu item callback arguments (for components that support this)

Type Array The callback arguments of the menu item for supported components.

Sample

menuItem.callbackArguments = [1];

enabled

Set/Get the menu item enabled state

Type Boolean The enabled state of the menu item.

Sample

menuItem.enabled = false;

iconStyleClass

Set/Get the menu item space separated icon style classes

Type String The space-separated icon style classes of the menu item.

Sample

menu.iconStyleClass = 'fas fa-square';

menuText

Set/Get the menu item text

Type String The text of the menu item.

Sample

menuItem.menuText = 'Item 1';

name

The menu name (identifier)

Type String the name (identifier) of the menu

styleClass

Set/Get the menu space separated styleclases

Type String The space-separated style classes applied to the menu.

Sample

menu.styleClass = 'myclass';

tooltipText

Set/Get the menu item tooltip text

Type String The tooltip text of the menu item.

Sample

menuItem.tooltipText = 'my tooltip';

Methods Detailed

addMenuItem(id)

Adds a new menu item, as last item in the list.

Parameters

• String id the menu item identifier

Returns: JSMenuItem The newly added menu item.

Sample

var item = menu.addMenuItem('item1');

addMenuItem(id, index)

Adds a new menu item, at a specific position.

Parameters

• String id the menu item identifier

• Number index the index position in list (0 based)

Returns: JSMenuItem The newly added menu item at the specified index.

Sample

var mnu = menu.addMenuItem('item1',0);

findMenuItem(id)

Gets a menu item by identifier. Also searches for nested elements. Returns null if not found.

Parameters

• String id the menu item identifier

Returns: JSMenuItem The menu item with the specified identifier, including nested items, or null if not found.

Sample

var mnu = menu.findMenuItem('item1');

getCustomProperty({String})

Returns custom property value. Custom properties can be defined on each Menu.

Parameters

• Object {String} propertyName - The name of the property to retrieve the value for.

Returns: Object The value of the specified custom property, or null if not found.

Sample

menuItem.getCustomProperty('myproperty');

getEnabledWithSecurity()

Returns: Boolean Returns whether the menu item is enabled with security constraints applied.

getExtraProperty({String})

Returns an extra property value.

Parameters

• Object {String} propertyName - The name of the property to retrieve the value for.

Returns: Object The value of the specified extra property, or null if not found.

Sample

menuItem.getExtraProperty('Sidenav','formName');

getMenuItem(id)

Gets a menu item by identifier. Returns null if not found.

Parameters

• String id the menu item identifier

Returns: JSMenuItem The menu item with the specified identifier, or null if not found.

Sample

var mnu = menu.getMenuItem('item1');

getMenuItemAt(index)

Gets a menu item by index (0 based). Returns null if not found.

Parameters

• Number index the menu item index among its sibblings

Returns: JSMenuItem The menu item at the specified index, or null if the index is out of bounds.

Sample

var mnu = menu.getMenuItemAt(0);

getMenuItems()

Returns all the menus items, either created at design time or at runtime, in the order they will show up in user interface.

Returns: Array An array of all menu items in this menu, in the order they appear in the user interface.

Sample

var items = menu.getMenuItems();

getMenuItemsWithSecurity()

Returns: Array An array of menu items that have the security flag set to "viewable."

getSelectedItem()

Returns: JSMenuItem the selectedItem

removeMenuItem(menuItem)

Removes a menu item from children's list, returns true if element was found an removed

Parameters

• JSMenuItem menuItem the menu item to be removed

Returns: Boolean True if the specified menu item was removed; false otherwise.

Sample

var success = menu.removeMenuItem(item);

removeMenuItem(id)

Removes a menu item with given id, returns true if element was found an removed

Parameters

• String id the menu item identifier

Returns: Boolean True if a menu item with the specified identifier was removed; false otherwise.

Sample

var success = menu.removeMenuItem('item1');

selectMenuItem(menuItem)

Selects a menu item in user interface

Parameters

• JSMenuItem menuItem the menu item to be selected

Returns: void

Sample

menu.selectMenuItem(item);

setCustomProperty({String}, {Object})

Sets a custom property value. Custom properties can be defined on each Menu.

Parameters

• Object {String} propertyName - The name of the property to set.

• Object {Object} value - The value to assign to the specified property.

Returns: void

Sample

menuItem.setCustomProperty('formName','myform');

setExtraProperty({String}, {Object})

Sets an extra property value (property must be present in the component spec).

Parameters

• Object {String} propertyName - The name of the property to set.

• Object {Object} value - The value to assign to the specified property.

Returns: void

Sample

menuItem.setExtraProperty('Sidenav','formName','myform');

setSecurityFlags(flags)

Override the permission data and design data (for enabled flag) and set if a menu item is viewable(visible) and enabled.

Parameters

• Number flags either 0 or a combination of JSMenuItem.VIEWABLE and JSMenuItem.ENABLED

Returns: void

Sample

menuItem.setSecurityFlags(JSMenuItem.VIEWABLE|JSMenuItem.ENABLED);

---