aspnetcore-401809-rich-edit-ribbon-customization.md
The Rich Text Editor allows you to customize its built-in ribbon on the server and client sides.
Run Demo: Ribbon Customization
Call the Ribbon method to access and customize ribbon settings:
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
//...
)
)
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:
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.Tabs(tabs => {
tabs.Clear();
tabs.AddHomeTab();
//...
})
)
)
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.
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.Tabs(tabs => {
tabs.Clear();
tabs.Add("History")
.Items(items => {
items.AddUndoItem();
items.AddRedoItem();
//...
});
})
)
)
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.
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.Tabs(tabs => {
tabs.RemoveByTitle("References");
//...
})
)
)
Call the ContextTabCategories method to access the collection of context tab categories. You can clear, add, and customize the default categories.
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.ContextTabCategories(categories => {
categories.Clear();
categories.AddHeaderAndFooterContextTabCategory();
//...
})
)
)
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:
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.Tabs(tabs => {
tabs.Clear();
tabs.Add("History")
.Items(items => {
items.AddUndoItem();
items.AddRedoItem();
//...
});
})
)
)
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) |
@(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.
function onCustomCommandExecuted(s, e) {
switch (e.commandName) {
case 'sendEmail':
var text = s.document.getText();
var mailto_link = 'mailto:[email protected]?subject=Test&body=' + encodeURIComponent(text);
window = window.open(mailto_link, 'emailWindow');
if(window && window.open && !window.closed)
window.close();
break;
}
}
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.
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.Tabs(tabs => {
tabs.GetByTitle("Home")
.Items(items => {
items.RemoveAt(0);
//...
});
})
)
)
Pass false to the ribbon’s Visible method to hide the ribbon.
@(Html.DevExpress().RichEdit("richEdit")
.Ribbon(ribbon => ribbon
.Visible(false)
//...
)
)
Call the static createOptions method to create control options. The ribbon option returns an object of the Ribbon type that contains ribbon settings.
var options = DevExpress.RichEdit.createOptions();
Use the removeTab(id) and insertTab(tab) methods to move a tab within the ribbon.
//move the Home tab to the third position
options.ribbon.insertTab(options.ribbon.removeTab(DevExpress.RichEdit.RibbonTabType.Home),2);
Use the insertTab(tab) method to add a custom tab to the ribbon.
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);
Use the following methods to remove a tab from the ribbon.
clearTabsRemoves all ribbon tabs.removeTab(id)Removes the tab with the specified ID from the ribbon.removeTab(tab)Removes the specified tab from the ribbon.
//remove the References tab
options.ribbon.removeTab(DevExpress.RichEdit.RibbonTabType.References);
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.
//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);
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);
}
});
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.
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:[email protected]?subject=Test&body=' + encodeURIComponent(text);
window = window.open(mailto_link, 'emailWindow');
if (window && window.open && !window.closed)
window.close();
break;
}
}");
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.
//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);
Set the visible property to false to hide the ribbon.
options.ribbon.visible = false;
Modify a Ribbon object and send it to the updateRibbon(callback) method to update the ribbon at runtime.
richEdit.updateRibbon(function (ribbon) {
ribbon.visible = false;
});
Call the setCommandEnabled(command, enabled) method to change the command’s availability.
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.