Ribbon Javascript API

Class

Ribbon

Ribbon is a navigation control that allows you to organize your application's commands in a tabbed interface.

Selector

smart-ribbon

Properties

Events

Methods

Properties

collapsibleany

Specifies whether the ribbon interface can be collapsed or expanded by the user, allowing for a more compact or fully visible display as needed.

dataSourcearray

Specifies the individual tab items to be displayed within the ribbon interface. Each tab item typically represents a distinct category or section, allowing users to easily navigate and access grouped commands or features within the ribbon.

disabledboolean

Specifies or retrieves whether the element is disabled, preventing user interaction and making it unresponsive to mouse and keyboard events. When set to true, the element cannot be activated or receive input focus.

 <smart-ribbon disabled></smart-ribbon>

 const ribbon = document.querySelector('smart-ribbon');

 ribbon.disabled = true;

 const ribbon = document.querySelector('smart-ribbon');

 let disabled = ribbon.disabled;

fileMenuobject

Specifies the available file menu options displayed within the ribbon interface, defining which actions (such as New, Open, Save, Print, etc.) users can access from the file menu.

 <smart-ribbon enabled></smart-ribbon>

 const ribbon = document.querySelector('smart-ribbon');

 let fileMenu = ribbon.fileMenu.fileMenu;

unlockKeystring

Sets or retrieves the value of the unlockKey property, which is used to authenticate and authorize access to unlock the product. The unlockKey typically functions as a secure code or token required to enable full product functionality.

 const ribbon = document.querySelector('smart-ribbon');

 ribbon.fileMenu.unlockKey = '1111-2222-3333-4444-5555';

 const ribbon = document.querySelector('smart-ribbon');

 let unlockKey = ribbon.fileMenu.unlockKey;

localestring

Specifies the localization settings for the ribbon, determining the language and regional formatting (such as date, time, and number formats) used for displaying text and other interface elements.

 const ribbon = document.querySelector('smart-ribbon');

 let locale = ribbon.fileMenu.locale;

messagesobject

Specifies the text and content displayed in the ribbon's message area, allowing customization of informational or notification messages shown to users within the ribbon interface.

 const ribbon = document.querySelector('smart-ribbon');

 let messages = ribbon.fileMenu.messages;

rightToLeftboolean

Specifies or retrieves a value that determines whether the element’s alignment is optimized for right-to-left (RTL) languages, such as Arabic or Hebrew. This affects the element’s text direction, layout flow, and alignment to accommodate locales that use right-to-left scripts.

 const ribbon = document.querySelector('smart-ribbon');

 ribbon.fileMenu.rightToLeft = true;

 const ribbon = document.querySelector('smart-ribbon');

 let rightToLeft = ribbon.fileMenu.rightToLeft;

selectedTabany

Specifies which tab is currently selected and active in the tab navigation component, typically by its index or identifier. This property controls which tab's content is visible to the user.

 const ribbon = document.querySelector('smart-ribbon');

 let selectedTab = ribbon.fileMenu.selectedTab;

Events

collapseCustomEvent

This event is triggered whenever the ribbon component transitions from its expanded state to a collapsed state. It allows developers to execute custom logic or UI updates in response to the ribbon becoming minimized or hidden from view.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onCollapse

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('collapse', function (event) {
	// event handling code goes here.
})

collapsingCustomEvent

This event is fired when the ribbon begins the process of collapsing, allowing you to execute custom logic before the collapse completes. If you wish to prevent the ribbon from collapsing, you can call event.preventDefault() within your event handler. This will cancel the default collapsing action, keeping the ribbon expanded.

• Bubbles Yes
• Cancelable Yes
• Interface CustomEvent
• Event handler property onCollapsing

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('collapsing', function (event) {
	// event handling code goes here.
})

dialogLauncherClickCustomEvent

This event is triggered when a user clicks the dialog launcher button, typically represented by a small icon (such as an arrow or ellipsis) in a component's toolbar or header. The event indicates the user's intention to open an extended options dialog or advanced settings panel related to the component.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onDialogLauncherClick

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('dialogLauncherClick', function (event) {
    const detail = event.detail,
        groupLabel = detail.groupLabel,
        groupId = detail.groupId;

	// event handling code goes here.
})

expandCustomEvent

This event is triggered whenever the ribbon interface transitions from its collapsed state to an expanded state, indicating that additional options or tools have become visible to the user. Use this event to execute custom logic or UI updates whenever the ribbon expands.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onExpand

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('expand', function (event) {
	// event handling code goes here.
})

expandingCustomEvent

This event is fired when the ribbon component begins to expand. You can intercept and cancel the expansion by calling event.preventDefault() within your event handler function. This allows you to programmatically control whether or not the ribbon expands based on custom logic.

• Bubbles Yes
• Cancelable Yes
• Interface CustomEvent
• Event handler property onExpanding

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('expanding', function (event) {
	// event handling code goes here.
})

fileButtonClickCustomEvent

This event is triggered whenever the file menu button is clicked by the user. It is typically used to open, display, or perform actions related to the file menu, such as showing file options or initializing file-related functions. The event provides an opportunity for developers to execute custom logic in response to user interaction with the file menu button.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onFileButtonClick

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('fileButtonClick', function (event) {
	// event handling code goes here.
})

fileMenuOpenCustomEvent

This event is triggered whenever the user opens the file menu, such as by clicking on the "File" option in the application's main menu bar. It allows developers to execute custom logic immediately when the file menu becomes visible to the user.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onFileMenuOpen

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('fileMenuOpen', function (event) {
	// event handling code goes here.
})

fileMenuCloseCustomEvent

This event is triggered whenever the file menu is closed, either by user interaction or programmatically. It occurs after all menu actions have completed, signaling that the file menu is no longer visible or active. Developers can use this event to execute cleanup operations, update the user interface, or manage application state in response to the menu being closed.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onFileMenuClose

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('fileMenuClose', function (event) {
	// event handling code goes here.
})

fileMenuItemClickCustomEvent

This event is triggered whenever a user clicks on an item within the file menu. It allows you to execute custom actions in response to specific file menu selections, such as opening, saving, or closing a file. The event provides details about the selected menu item, enabling context-aware handling within your application.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onFileMenuItemClick

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('fileMenuItemClick', function (event) {
    const detail = event.detail,
        item = detail.item;

	// event handling code goes here.
})

selectCustomEvent

This event is triggered whenever the user selects a different tab, indicating that the active tab within the interface has changed. It allows you to respond to changes in tab selection, such as updating displayed content, fetching new data, or tracking user navigation within tabbed components.

• Bubbles Yes
• Cancelable No
• Interface CustomEvent
• Event handler property onSelect

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('select', function (event) {
    const detail = event.detail,
        oldIndex = detail.oldIndex,
        index = detail.index;

	// event handling code goes here.
})

selectingCustomEvent

This event is fired immediately before the active tab changes, allowing you to intercept and potentially prevent the tab switch. To cancel the tab selection change, call event.preventDefault() within your event handler. This provides an opportunity to perform validations or prompt the user before the change is finalized.

• Bubbles Yes
• Cancelable Yes
• Interface CustomEvent
• Event handler property onSelecting

Arguments

const ribbon = document.querySelector('smart-ribbon');
ribbon.addEventListener('selecting', function (event) {
    const detail = event.detail,
        oldIndex = detail.oldIndex,
        index = detail.index;

	// event handling code goes here.
})

Methods

addTab( tab: any): void

Adds a new tab to the application's ribbon interface. The tab can be specified in one of three ways: as a configuration object defining the tab's properties, as an existing HTMLElement to be used as the tab, or as a string representing the id of an existing HTMLElement to be added as the tab. This provides flexibility in how ribbon tabs are created and integrated.

Arguments

tabany

The ribbon tab to be added.

const ribbon = document.querySelector('smart-ribbon');
ribbon.addTab("Tab");

addGroup( tab: any, group: any): void

Enhances a ribbon tab by adding a new group. The group can be specified in one of the following ways: as an object defining its properties, as a direct reference to an HTMLElement, or as a string representing the id of an existing HTMLElement. This flexibility allows you to create the group dynamically, use an already created DOM element, or reference an element by its id.

Arguments

tabany

The id, index or HTMLElement of the parent ribbon tab.

groupany

The ribbon group to be added.

const ribbon = document.querySelector('smart-ribbon');
ribbon.addGroup("Tab");

addItem( tab: string | number | HTMLElement, group: string | HTMLElement, item: any): void

Adds a new item to a specified ribbon group in the ribbon interface. The new item can be provided in one of the following forms: as a configuration object, as an actual HTMLElement, or by specifying the id of an existing HTMLElement. This offers flexibility in how ribbon items are defined and incorporated into the ribbon group.

Arguments

tabstring | number | HTMLElement

The id, index or HTMLElement of the parent ribbon tab.

groupstring | HTMLElement

The id or HTMLElement of the parent ribbon group.

itemany

The ribbon item to be added.

const ribbon = document.querySelector('smart-ribbon');
ribbon.addItem();

collapse(): void

Minimizes the ribbon interface, hiding its commands and options, to provide more workspace on the screen.

const ribbon = document.querySelector('smart-ribbon');
ribbon.collapse();

expand(): void

Expands the ribbon interface to reveal additional tools, features, and options that are otherwise hidden from view. This action increases the available workspace by displaying the full set of ribbon commands and controls.

const ribbon = document.querySelector('smart-ribbon');
ribbon.expand();

removeTab( ribbonTab: string | number): void

Removes a specified tab from the ribbon interface, effectively hiding it and its associated commands from the user’s view. This action ensures that the tab and its contents are no longer accessible within the ribbon navigation.

Arguments

ribbonTabstring | number

The id or index of the ribbon tab to be removed.

const ribbon = document.querySelector('smart-ribbon');
ribbon.removeTab(0);

removeGroup( ribbonTabIndex?: string | number, ribbonGroup?: string | number): void

Removes a specified ribbon group from the selected ribbon tab, effectively deleting that group's controls and functionalities from the tab's interface.

Arguments

ribbonTabIndex?string | number

The id or index of the parent ribbon tab.

ribbonGroup?string | number

The id or index of the ribbon group to be removed.

const ribbon = document.querySelector('smart-ribbon');
ribbon.removeGroup(0);

removeItem( ribbonTabIndex?: string | number, ribbonGroup?: string | number, ribbonItem?: string | number): void

Removes a specified ribbon item from its parent ribbon group, effectively deleting the item from the group and updating the user interface accordingly. This operation ensures that the ribbon group no longer displays or interacts with the removed item.

Arguments

ribbonTabIndex?string | number

The id or index of the parent ribbon tab.

ribbonGroup?string | number

The id or index of the parent ribbon group.

ribbonItem?string | number

The id or index of the ribbon item to be removed.

const ribbon = document.querySelector('smart-ribbon');
ribbon.removeItem(0);

selectTab( ribbonTabIndex: string | number): void

Activates the specified ribbon tab, bringing its contents into focus and making its associated controls and options accessible to the user.

Arguments

ribbonTabIndexstring | number

The index of the ribbon tab to be selected.

const ribbon = document.querySelector('smart-ribbon');
ribbon.selectTab(0);