Ribbon Customization

• Aug 08, 2024
• 6 minutes to read

The Rich Text Editor allows you to customize its built-in ribbon on the server and client sides.

Run Demo: Ribbon Customization

Server-Side Ribbon Customization

Call the Ribbon method to access and customize ribbon settings:

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        //...
    )
)

Modify the Tab Collection

Add Default Tabs

The Rich Text Editor includes multiple methods that allow you to populate the ribbon with default tabs. For instance, the AddHomeTab() method adds the Home tab to the ribbon.

Note that the Rich Text Editor automatically populates the ribbon with default tabs. To clear the tab collection, call the Clear() method:

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Tabs(tabs => {
            tabs.Clear();
            tabs.AddHomeTab();
            //...
        })
    )
)

Add Custom Tabs

The following methods allow you to add a custom tab to the ribbon:

Add()

Adds a new tab to the end of the ribbon tab collection.

Add(String)

Adds a new tab with the specified title to the end of the ribbon tab collection.

Insert(Int32)

Inserts a new tab to the ribbon tab collection at the specified position.

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Tabs(tabs => {
            tabs.Clear();
            tabs.Add("History")
                .Items(items => {
                    items.AddUndoItem();
                    items.AddRedoItem();
                    //...
                });
        })
    )
)

Remove Tabs

Call one of the following methods to remove tabs from the ribbon:

Clear()

Removes all tabs from the ribbon tab collection.

RemoveAt(Int32)

Removes a tab at the specified position from the ribbon tab collection.

RemoveByTitle(String)

Removes a tab with the specified title from the ribbon tab collection.

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Tabs(tabs => {
            tabs.RemoveByTitle("References");
            //...
        })
    )
)

Modify Context Tab Categories

Call the ContextTabCategories method to access the collection of context tab categories. You can clear, add, and customize the default categories.

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .ContextTabCategories(categories => {
            categories.Clear();
            categories.AddHeaderAndFooterContextTabCategory();
            //...
        })
    )
)

Modify the Item Collection

Add Default Items

A tab item collection includes multiple methods that allow you to add default items to a tab. For instance, call AddUndoItem() and AddRedoItem() methods to add Undo and Redo items:

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Tabs(tabs => {
            tabs.Clear();
            tabs.Add("History")
                .Items(items => {
                    items.AddUndoItem();
                    items.AddRedoItem();
                    //...
                });
        })
    )
)

Add Custom Items

The table below lists methods that allow you to add custom items to a tab.

Item Type	Add Methods	Insert Method
Button	AddButton	InsertButton(Int32)
Color Box	AddColorBox	InsertColorBox(Int32)
Menu	AddMenu()	InsertMenu(Int32)
Number Box	AddNumberBox	InsertNumberBox(Int32)
Select Box	AddSelectBox()	InsertSelectBox(Int32)
Toggle Button	AddToggleButton	InsertToggleButton(Int32, Boolean)

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Tabs(tabs => {
            tabs.Clear();
            tabs.Add()
                .Title("Email")
                .Items(items => {
                    items.AddButton()
                        .Text("Send Email")
                        .CommandName("sendEmail")
                        .ShowText(true)
                        .Icon("email");
                });
        })
    )
    .OnCustomCommandExecuted("onCustomCommandExecuted")
    //...
)

Handle the CustomCommandExecuted event to process a custom item click. The commandName event argument returns the item’s commandName and allows you to identify the item.

JS

function onCustomCommandExecuted(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 Items

The following methods allow to remove items from a tab:

Clear()

Removes all items from the collection.

RemoveAt(Int32)

Removes an item at the specified position from the ribbon item collection.

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Tabs(tabs => {
            tabs.GetByTitle("Home")
                .Items(items => {
                    items.RemoveAt(0);
                    //...
                });
        })
    )
)

Hide the Ribbon

Pass false to the ribbon’s Visible method to hide the ribbon.

Razor C#

@(Html.DevExpress().RichEdit("richEdit")
    .Ribbon(ribbon => ribbon
        .Visible(false)
        //...
    )
)

Client-Side Ribbon Customization

Call the static createOptions method to create control options. The ribbon option returns an object of the Ribbon type that contains ribbon settings.

JS

var options = DevExpress.RichEdit.createOptions();

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.

clearTabs

Removes all ribbon tabs.

removeTab(id)

Removes the tab with the specified ID from the ribbon.

removeTab(tab)

Removes the specified tab from the ribbon.

JS

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

Modify the Item Collection

Rearrange Items

To move an item within the ribbon, call the removeItem(id) method to remove the item, and then call the insertItem(item) method to insert the item into a new position.

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.

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;
});

Change the Command Availability

Call the setCommandEnabled(command, enabled) method to change the command’s availability.

JS

var ribbonButton = new DevExpress.RichEdit.RibbonButtonItem("sendEmail", "Send Email",
  { icon: "email", showText: true, beginGroup: true });
ribbon.getTab(DevExpress.RichEdit.RibbonTabType.Home).insertItem(ribbonButton);
...
richEdit.setCommandEnabled("sendEmail", false);
richEdit.setCommandEnabled(DevExpress.RichEdit.InsertTabCommandId.ShowInsertTableDialog, false);
richEdit.setCommandEnabled(DevExpress.RichEdit.InsertTabItemId.ShowBookmarkDialog, false);

You can call the getCommandState(commandId) method to get the current state of the command.