Client-Side Ribbon Customization

• Jul 01, 2021
• 3 minutes to read

The Rich Text Editor allows you to customize its built-in Ribbon control on the server and client sides. This topic describes client-side modifications.

Call the static createOptions method to create control options.

JS

var options = DevExpress.RichEdit.createOptions();

The ribbon property returns an object of the Ribbon type that contains ribbon settings.

Modify the Tab Collection

Rearrange Tabs

Use the removeTab(id) and insertTab(tab) methods to move a tab within the ribbon.

JS

//move the Home tab to the third position
options.ribbon.insertTab(options.ribbon.removeTab(DevExpress.RichEdit.RibbonTabType.Home),2);

Add a Custom Tab

Use the insertTab(tab) method to add a custom tab to the ribbon.

JS

var ribbonItemUndo = options.ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home)
  .getItem(DevExpress.RichEdit.HomeTabItemId.Undo);
var ribbonItemRedo = options.ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home)
  .getItem(DevExpress.RichEdit.HomeTabItemId.Redo);

var historyTab = new DevExpress.RichEdit.RibbonTab;
historyTab.id = "myHistoryTab";
historyTab.title = "History";
historyTab.items =[ribbonItemUndo, ribbonItemRedo];

options.ribbon.insertTab(historyTab, 0);

Remove a Tab

Use the following methods to remove a tab from the ribbon.

Method	Description
clearTabs	Removes all tabs from the ribbon tab collection.
removeTab(id)	Removes the tab with the specified ID from the ribbon tab collection.
removeTab(tab)	Removes the specified tab from the ribbon tab collection.

JS

//remove the References tab
options.ribbon.removeTab(DevExpress.RichEdit.RibbonTabType.References);

Modify the Item Collection

Rearrange Items

Use the removeItem(id) and insertItem(item) methods to move an item within the ribbon.

JS

//move the Undo and Redo commands
var homeTab = options.ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home);
var ribbonItemUndo = homeTab.getItem(DevExpress.RichEdit.HomeTabItemId.Undo);
var ribbonItemRedo = homeTab.getItem(DevExpress.RichEdit.HomeTabItemId.Redo);
ribbonItemUndo.beginGroup = true;
homeTab.removeItem(ribbonItemUndo);
homeTab.removeItem(ribbonItemRedo);
homeTab.insertItem(ribbonItemUndo, 3);
homeTab.insertItem(ribbonItemRedo, 4);

JS

richEdit.updateRibbon(function (ribbon) {
    var pageLayoutTab = ribbon.getTab(DevExpress.RichEdit.RibbonTabType.PageLayout);
    var subMenuItem = pageLayoutTab.getItem(DevExpress.RichEdit.PageLayoutTabItemId.InsertPageBreak);
    if (subMenuItem) {
        pageLayoutTab.removeItem(DevExpress.RichEdit.PageLayoutTabItemId.InsertPageBreak);
        var insertTab = ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Insert);
        insertTab.insertItem(subMenuItem.convertToButton(), 0);
    }
});

Add a Custom Item

Use the insertItem(item) method to add a custom item to a tab.

To process a custom item click, handle the CustomCommandExecuted event. The commandName event argument returns the item’s id property value.

Note

Rich Text Editor determines commands and ribbon items by numeric identifiers. Use strings or numbers greater than 10000 for custom command identifiers.

JS

var ribbonButton = new DevExpress.RichEdit.RibbonButtonItem("sendEmail", "Send Email",
  { icon: "email", showText: true, beginGroup: true });
options.ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home).insertItem(ribbonButton,2);

options.events.customCommandExecuted = ("function(s, e) {
  switch (e.commandName) {
    case 'sendEmail':
      var text = s.document.getText();
      var mailto_link = 'mailto:[e-mail]?subject=Test&body=' + encodeURIComponent(text);
      window = window.open(mailto_link, 'emailWindow');
      if (window && window.open && !window.closed)
        window.close();
      break;
  }
}");

Remove an Item

Use the following methods to remove an item from a tab.

Method	Description
removeItem(id)	Removes the item with the specified ID from the tab.
removeItem(item)	Removes the specified item from the tab.

JS

//remove the Increase Font Size and Decrease Font Size commands from the Home tab
var homeTab = options.ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home);
homeTab.removeItem(DevExpress.RichEdit.HomeTabItemId.IncreaseFontSize);
homeTab.removeItem(DevExpress.RichEdit.HomeTabItemId.DecreaseFontSize);

Hide the Ribbon

Set the visible property to false to hide the ribbon.

JS

options.ribbon.visible = false;

Update the Ribbon at Runtime

Modify a Ribbon object and send it to the updateRibbon(callback) method to update the ribbon at runtime.

JS

richEdit.updateRibbon(function (ribbon) {
  ribbon.visible = false;
});