DxRichEdit.CustomizeToolbar Event

Allows you to customize the Rich Text Editor’s toolbar.

Namespace: DevExpress.Blazor.RichEdit

Assembly: DevExpress.Blazor.RichEdit.v23.2.dll

NuGet Package: DevExpress.Blazor.RichEdit

Declaration

[Parameter]
public EventCallback<IToolbar> CustomizeToolbar { get; set; }

Parameters

Type	Description
IToolbar	The toolbar model.

Remarks

Set the BarMode property to Toolbar to display the built-in toolbar in the Rich Text Editor. The toolbar consists of groups, and each group contains one or more items. Handle the CustomizeToolbar event to access and customize the built-in toolbar’s settings before the control is initialized.

Run Demo: Toolbar Customization

Refer to the following section for more information on how to customize the Rich Text Editor’s toolbar dynamically: Runtime Toolbar Customization.

Modify the Group Collection

Access Groups

The CustomizeToolbar event’s parameter allows you to access the built-in toolbar. Use the toolbar’s Groups property to access its group collection. You can get a group by its name or index:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        // Accesses the first group
        IBarGroup firstGroup = toolbar.Groups[0];
        // Accesses the Table group
        IBarGroup tableGroup = toolbar.Groups[RichEditToolbarGroupNames.Table];
    }
}

Add Default Groups

The Add method overloads allow you to add a default group with the specified name to the group collection. The RichEditToolbarGroupNames class contains names of all built-in groups in the toolbar. Use properties of this class to get the name of a default group.

The example below clears the group collection and adds the default File and Picture groups to this collection:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        toolbar.Groups.Clear();
        // Inserts the Picture group at the end of the group collection
        toolbar.Groups.Add(RichEditRibbonGroupNames.Picture);
        // Inserts the File group at the first position in the group collection
        toolbar.Groups.Add(0, RichEditToolbarGroupNames.File);
    }
}

Add Custom Groups

The AddCustomGroup method overloads allow you to create a custom group and add it to the group collection. You should add an item in the new group to make it visible because the Rich Text Editor hides groups that contain no visible or enabled items.

The example below demonstrates how to insert a custom group and populate it with default items:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        // Inserts a new group at the end of the group collection
        IBarGroup clipboardGroup = toolbar.Groups.AddCustomGroup();
        clipboardGroup.Items.Add(RichEditBarItemNames.ClipboardMenu);
        // Inserts a new group at the first position in the group collection
        IBarGroup undoRedoGroup = toolbar.Groups.AddCustomGroup(0);
        undoRedoGroup.Items.Add(RichEditBarItemNames.Undo);
        undoRedoGroup.Items.Add(RichEditBarItemNames.Redo);    
    }
}

Customize Groups

Use a group’s properties to customize its visibility and appearance. The example below demonstrates how to customize the Table group:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar @bind-Selection=@selection />

@code {
    Selection selection;

    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup tableGroup = toolbar.Groups[RichEditToolbarGroupNames.Table];
        tableGroup.GetVisible = () => selection.ActiveSubDocument.Type == SubDocumentType.Main;
        tableGroup.Text = "Table";
        tableGroup.Tooltip = "Insert a table in the main sub-document";
        tableGroup.IconUrl = "your-icon-url";
    }
}

Remove Groups

The Remove method overloads allow you to remove a group with the specified name or index from the group collection. To remove all groups from the collection, call the Clear() method.

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        // Removes the first group
        toolbar.Groups.Remove(0);
        // Removes the File group
        toolbar.Groups.Remove(RichEditToolbarGroupNames.File);
        // Removes all groups
        toolbar.Groups.Clear();
    }
}

Modify the Item Collection

A group‘s Items property allows you to access the collection of this group’s items. An item collection can contain various items of the following types:

• Button
• Checkable button
• Color edit
• Combo box
• Drop down
• Spin edit

You can get an item by its name or index:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup fontGroup = toolbar.Groups[RichEditToolbarGroupNames.Font];
        // Accesses the first item
        IBarItem fontNameItem = fontGroup.Items[0];
        // Accesses the Font Name item
        IBarItem fontNameItem = fontGroup.Items[RichEditBarItemNames.FontName];
    }
}

Add Default Items

The Add method overloads allow you to add a default item with the specified name to the item collection. The RichEditBarItemNames class contains names of all built-in items. Use properties of this class to get the name of a default item.

The example below clears the item collection and adds the default Undo and Redo items to this collection:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup undoRedoGroup = toolbar.Groups[0];
        undoRedoGroup.Clear();
        // Inserts the Redo item at the end of the item collection
        undoRedoGroup.Items.Add(RichEditBarItemNames.Redo);
        // Inserts the Undo item at the first position in the item collection
        undoRedoGroup.Items.Add(RichEditBarItemNames.Undo, 0);
    }
}

Add Custom Items

Call one of the following method overloads to create a custom item and add it in the item collection:

• AddCustomButton
• AddCustomCheckButton
• AddCustomColorEdit
• AddCustomComboBox
• AddCustomDropDown
• AddCustomSpinEdit

The example below demonstrates how to add custom button and combo box items that allow users to export an open document:

<DxRichEdit @ref=@rich DocumentFormat=@documentFormat @bind-Modified=@modified 
    CustomizeToolbar=OnCustomizeToolbar BarMode=BarMode.Toolbar/>

@code {
    DxRichEdit rich;
    DocumentFormat documentFormat = DocumentFormat.OpenXml;
    bool modified = false;

    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup fileCommonGroup = toolbar.Groups.AddCustomGroup(0);
        // Inserts a custom combo box at the end of the item collection
        IBarComboBox documentFormatComboBox = fileCommonGroup.Items.AddCustomComboBox(
            () => documentFormat,
            (value) => Task.FromResult(documentFormat = (DocumentFormat)value)
        );
        documentFormatComboBox.Items.Add("DOCX", DocumentFormat.OpenXml);
        documentFormatComboBox.Items.Add("RTF", DocumentFormat.Rtf);
        // Inserts a custom button at the first position in the item collection
        IBarButton exportButton = fileCommonGroup.Items.AddCustomButton(0, "Export", DownloadDocumentAsync);
    }

    async Task DownloadDocumentAsync() {
        if (documentFormat == DocumentFormat.OpenXml)
            await rich.ExportDocumentAsync("C:\\Users\\Public\\annual-report.docx", documentFormat);
        else
            await rich.ExportDocumentAsync("C:\\Users\\Public\\annual-report.rtf", documentFormat);
    }
}

Customize Items

Use an item’s properties to customize its visibility, appearance, and behavior. The example below demonstrates how to customize a combo box item:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup fontGroup = toolbar.Groups[RichEditToolbarGroupNames.Font];
        IBarItem fontNameItem = fontGroup.Items[RichEditBarItemNames.FontName];
        if (fontNameItem.Type == BarItemTypes.ComboBox) {
            IBarComboBox fontNameComboBox = (IBarComboBox)fontNameItem;
            fontNameComboBox.Items.Clear();
            fontNameComboBox.Items.Add("Times New Roman");
            fontNameComboBox.Items.Add("Arial");
            fontNameComboBox.Items.Add("Courier New");
            fontNameComboBox.Items.Add("Calibri");
            fontNameComboBox.AllowUserInput = false;
        }
        fontNameItem.Text = "Font Name:";
        fontNameItem.Tooltip = "Changes the selected text's font name.";
    }
}

Remove Items

The Remove method overloads allow you to remove an item with the specified name or index from the item collection. To remove all items from the collection, call the Clear() method.

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup fileCommonGroup = toolbar.Groups.Add(RichEditRibbonGroupNames.FileCommon);
        // Removes the first item
        fileCommonGroup.Items.Remove(0);
        // Removes the Download Menu item
        fileCommonGroup.Items.Remove(RichEditBarItemNames.DownloadMenu);
        // Removes all items
        fileCommonGroup.Items.Clear();
    }
}

Runtime Toolbar Customization

The Rich Text Editor automatically disables items and hides groups that contain no visible or enabled items. You can use the following properties to disable items and hide groups or items at runtime manually:

GetVisible

The GetVisible property of a group or item accepts a method that defines display criteria for the group or item.

GetEnabled

An item’s GetEnabled property accepts a method that defines enable criteria for the item.

The example below demonstrates how to change a group’s visibility and an item’s availability dynamically:

<DxRichEdit BarMode=BarMode.Toolbar CustomizeToolbar=OnCustomizeToolbar @bind-Selection="@selection"/>

@code {
    Selection selection;

    void OnCustomizeToolbar(IToolbar toolbar) {
        IBarGroup tableGroup = toolbar.Groups[RichEditToolbarGroupNames.Table];
        tableGroup.GetVisible = () => selection.ActiveSubDocument.Type == SubDocumentType.Main;
        IBarItem insertHeader = toolbar.Groups.AddCustomGroup().Items.Add(RichEditBarItemNames.InsertPageHeader);
        insertHeader.GetEnabled = () => selection.ActiveSubDocument.Type != SubDocumentType.Header;
    }
}

Handle Item Exceptions

The Rich Text Editor runs asynchronous code to respond to user actions. Use the BarItemExceptionRaised event to handle runtime exceptions that can occur after a user interacts with an item in the toolbar.

The example below demonstrates how to write exception log messages.

ToolbarCustomization.razor

@using Microsoft.Extensions.Logging;
@inject ILogger<ToolbarCustomization> Logger;

<DxRichEdit BarMode=BarMode.Toolbar 
            CustomizeToolbar=OnCustomizeToolbar 
            BarItemExceptionRaised=OnBarItemExceptionRaised />

@code {
    void OnCustomizeToolbar(IToolbar toolbar) {
        // ...
    }
    void OnBarItemExceptionRaised(BarItemExceptionEventArgs args) {
        Logger.LogError(args.Exception, args.Exception.Message);
        args.Handled = true;
    }
}