Toolbars

• Nov 20, 2020
• 6 minutes to read

The DevExpress ASPxGridView control enables you to group the most important or frequently used grid commands, and expose them through customizable toolbars for efficient end-user access.

See Online Demo: Toolbar

Note

The ASPxGridBase.KeyFieldName property should be specified when using the following grid features:

• data editing;
• adding new and deleting existing data item;
• selecting data item;
• master-detail view;
• endless paging.

Toolbar Object

The ASPxGridView stores toolbars in its ASPxGridView.Toolbars collection. Each toolbar is a GridViewToolbar class instance. You can add and remove toolbars in the collection and change the following characteristics of individual toolbars:

Toolbar Characteristic	Property	Description
Adaptive Behavior	GridToolbar.EnableAdaptivity	Specifies whether an adaptive behavior is enabled for the toolbar.
Availability	GridToolbar.Enabled	Gets or sets a value that indicates whether the toolbar is enabled, allowing the toolbar to respond to end-user interactions.
Item Alignment	GridToolbar.ItemAlign	Gets or sets the toolbar item alignment.
Name	GridToolbar.Name	Gets or sets the toolbar’s unique identifier name.
Position	GridToolbar.Position	Gets or sets the toolbar position.
Visibility	GridToolbar.Visible	Gets or sets a value specifying the visibility of the toolbar.

To populate a toolbar with toolbar items and to have indexed access to them, use the toolbar’s GridViewToolbar.Items property.

Toolbar Item Object

Toolbar items are instances of the GridViewToolbarItem class. It is a descendant of the MenuItem class and so it inherits the following key functionality making a toolbar item appear and behave as a menu item.

Toolbar Item Characteristic	Property	Description
Group Separation	MenuItem.BeginGroup	Gets or sets a value that specifies whether the current menu item starts a group.
Group Name	MenuItem.GroupName	Gets or sets the name of a logical check group to which the menu item belongs.
Image	MenuItem.Image	Gets the settings of an image displayed within the menu item.
Name	MenuItem.Name	Gets or sets the unique identifier name for the current menu item.
Template	MenuItem.Template	Gets or sets a template used to display the content of the current menu item.
Text	MenuItem.Text	Gets or sets the text content of the current menu item.
Tooltip	MenuItem.ToolTip	Gets or sets the current menu item’s tooltip text.

Additionally, you can use the following options explicitly implemented for toolbar items to properly customize their behavior and appearance.

Toolbar Item Characteristic	Property	Description
Display Mode	GridToolbarItem.DisplayMode	Gets or sets the display mode of the current toolbar item within the toolbar.
Command to Execute	GridViewToolbarItem.Command	Gets or sets the name of a command executed when clicking a toolbar item.
Child Items	GridViewToolbarItem.Items	Gets a collection that contains the toolbar items of the current toolbar item. Enables you to create hierarchies of nested toolbar items of unlimited depth.

Based on the GridViewToolbarItem.Command property setting, a toolbar item either triggers a standard grid command (that is, data item editing, deletion, creation, etc.) or performs a custom action, if required (this action should be implemented programmatically).

Standard Toolbar Item

To make a toolbar item execute a standard command, set the item’s GridViewToolbarItem.Command property to the desired command name listed by the GridViewToolbarCommand enumeration. A standard toolbar item automatically displays the command-related text and image (optional). Clicking a standard toolbar item executes the corresponding grid command.

Note

The GridToolbarItem.ClientEnabled and MenuItem.Enabled properties are not in effect for a standard toolbar item.

Example - How to create standard items

The code snippet below demonstrates how to create two standard toolbar items - for the New and Refresh commands - in the markup.

ASPX

<dx:ASPxGridView runat="server" ID="Grid" ...>
        ...
        <Toolbars>
            <dx:GridViewToolbar ItemAlign="Right">
                <Items>
                    <dx:GridViewToolbarItem Command="New" />
                    ...
                    <dx:GridViewToolbarItem Command="Refresh" BeginGroup="true" />
                    ...
                </Items>
            </dx:GridViewToolbar>
        </Toolbars>
    </dx:ASPxGridView>

Custom Toolbar Item

If you need a toolbar item to perform a custom action, create a new GridViewToolbarItem object and use one of the following two implementation options.

• Use Toolbar-Related Grid API

  Perform the following steps to identify the toolbar item and handle its clicks.

  1. Set Command to Custom

     Set the toolbar item’s GridViewToolbarItem.Command property to the GridViewToolbarCommand.Custom value (this is the default property setting).

  2. Set Name

     Specify a custom command name through the toolbar item’s MenuItem.Name property.

  3. Set Text or Image

     Specify item characteristics (such as text, image, or both) using the item’s MenuItem.Text and MenuItem.Image properties together with the GridToolbarItem.DisplayMode property.

  4. Handle Event(s)

     Handle the client ASPxClientGridBase.ToolbarItemClick event or server ASPxGridView.ToolbarItemClick event (or both) to identify the triggered custom command by its name and execute the required action.

     Note

     Custom toolbar item click is processed on the client side by default using the ASPxClientGridBase.ToolbarItemClick event handler. Set the ASPxClientProcessingModeEventArgs.processOnServer property to true to process a custom toolbar item click on the server side (ASPxGridView.ToolbarItemClick).

• Use a Template to Define Item

  Create the toolbar item’s template using the MenuItem.Template property to define the item content and provide custom logic to implement the item behavior.

By default, the grid displays only command items that allow you to edit data when the grid is in Changes Preview mode:

• New
• Edit
• Delete
• DeleteSelectedRowsOnPage
• Refresh
• Update
• Cancel

To display other command items (including custom and templated items) in Changes Preview mode, set a command item’s VisibleInBatchEditPreviewChanges property to true.

ASPX

<dx:ASPxGridView runat="server" ID="Grid" ...>
    <Toolbars>
        <dx:GridViewToolbar ItemAlign="Right">
            <Items>
                ...
                <dx:GridViewToolbarItem Text="Export to PDF" Name="CustomExportToPDF" VisibleInBatchEditPreviewChanges="True" >
                </dx:GridViewToolbarItem>
                ...
            </Items>
        </dx:GridViewToolbar>
    </Toolbars>        
    ...
    <ClientSideEvents ToolbarItemClick="OnToolbarItemClick" />
</dx:ASPxGridView>

Example - How to create custom items (specifying their names, texts and images)

The code below demonstrates how to create a custom ‘Export to’ toolbar item with three sub-items to export the grid data to different formats (PDF, XLSX and XLS).

ASPX

<dx:ASPxGridView runat="server" ID="Grid" OnToolbarItemClick="Grid_ToolbarItemClick" ...>
        <Toolbars>
            <dx:GridViewToolbar ItemAlign="Right">
                <Items>
                    ...
                    <dx:GridViewToolbarItem Text="Export to" Image-IconID="actions_download_16x16office2013" BeginGroup="true">
                        <Items>
                            <dx:GridViewToolbarItem Name="CustomExportToPDF" Text="PDF" Image-IconID="export_exporttopdf_16x16office2013" />
                            <dx:GridViewToolbarItem Name="CustomExportToXLS" Text="XLS(DataAware)" Image-IconID="export_exporttoxls_16x16office2013" />
                            <dx:GridViewToolbarItem Name="CustomExportToXLSX" Text="XLSX(WYSIWYG)" Image-IconID="export_exporttoxlsx_16x16office2013" />
                        </Items>
                    </dx:GridViewToolbarItem>
                    ...
                </Items>
            </dx:GridViewToolbar>
        </Toolbars>        
        ...
        <ClientSideEvents ToolbarItemClick="OnToolbarItemClick" />
    </dx:ASPxGridView>

JS

function OnToolbarItemClick(s,e) {
            if(IsExportToolbarCommand(e.item.name)){
                e.processOnServer=true;
                e.usePostBack=true;
            }
        }
        function IsExportToolbarCommand(command){
            return command == "CustomExportToPDF" || command == "CustomExportToXLSX" || command == "CustomExportToXLS" ;
        }

C#

protected void Grid_ToolbarItemClick(object source, ASPxGridToolbarItemClickEventArgs e) {
        switch(e.Item.Name) {
            case "CustomExportToPDF":
                Grid.ExportPdfToResponse();
                break;
            case "CustomExportToXLS":
                Grid.ExportXlsToResponse(new XlsExportOptionsEx { ExportType = ExportType.DataAware });
                break;
            case "CustomExportToXLSX":
                Grid.ExportXlsxToResponse(new XlsxExportOptionsEx { ExportType = ExportType.WYSIWYG });
                break;
            default:
                break;
        }
    }

Example - How to create a custom item (defining its template)

The following code illustrates how to create a custom toolbar item by defining its template to imitate the functionality of the grid search panel’s editor.

ASPX

<dx:ASPxGridView runat="server" ID="Grid" ...>
        <Toolbars>
            <dx:GridViewToolbar ItemAlign="Right">
                <Items>
                    ...
                    <dx:GridViewToolbarItem BeginGroup="true">
                        <Template>
                            <dx:ASPxButtonEdit ID="tbToolbarSearch" runat="server" NullText="Search..." Height="100%">
                                <Buttons>
                                    <dx:SpinButtonExtended Image-IconID="find_find_16x16gray" />
                                </Buttons>
                            </dx:ASPxButtonEdit>
                        </Template>
                    </dx:GridViewToolbarItem>
                </Items>
            </dx:GridViewToolbar>
        </Toolbars>        
        ...
        <SettingsSearchPanel CustomEditorID="tbToolbarSearch" />
        ...
    </dx:ASPxGridView>