DevExtreme Data Grid & Tree List - New Toolbar Customization API (v21.2)

DevExtreme Team Blog
22 October 2021
As you may already know, our next major update is set to ship in a few weeks. If you have not yet done so, please take a moment to review our What’s New webpage for information on our upcoming release.
In this blog post, I’ll describe our new DataGrid and TreeList Toolbar Customization API and show you how to leverage its capabilities in your next DevExtreme-powered app.

New toolbar Property

In previous versions, you could customize our toolbar using the onToolbarPreparing event handler. Though this approach addressed basic use cases, it did not allow you to modify the toolbar dynamically or configure the toolbar declaratively (important for Angular, React, and Vue users). To address this limitation, v21.2 ships with a new toolbar property:
toolbar: {
  visible: Boolean,  // `true` - the toolbar is visible;
                     // `false` - the toolbar is hidden;
                     // `undefined` - the toolbar is visible if it contains items
  disabled: Boolean, // Specifies whether the toolbar responds to user interaction
  items: Object[]    // Configures toolbar items
} 

Common Use Cases

In the following sections, we’ll describe a few usage scenarios and discuss the use of our new toolbar property. Please note that while each code listing targets only one of our supported frameworks, all our new features are available for Angular, Vue, React, jQuery, ASP.NET MVC, and ASP.NET Core.

Add a Custom Toolbar Item

To configure toolbar items, you need to specify the items array. This array can contain predefined items (Export button, Search Panel, etc.) and custom items. The following code adds a custom 'Refresh’ button to the toolbar. Note: You should also declare predefined items (such as the Column Chooser button) in your code if you wish to make them available to end-users.
Angular
<!-- app.component.html -->
<dx-data-grid id="gridContainer">
  <dxo-column-chooser [enabled]="true"></dxo-column-chooser>
  <dxo-toolbar>
    <dxi-item location="after">
      <dx-button
        icon="refresh"
        (onClick)="refreshDataGrid($event)">
      </dx-button>
    </dxi-item>
    <dxi-item name="columnChooserButton"></dxi-item>
  </dxo-toolbar>
</dx-data-grid> 
// app.component.ts
// ...
import {
  DxDataGridModule,
  DxDataGridComponent
} from "devextreme-angular/ui/data-grid";
import { DxButtonModule } from "devextreme-angular/ui/button";

@Component({
  // ...
})
export class AppComponent {
  @ViewChild(DxDataGridComponent, { static: false }) dataGrid: DxDataGridComponent;
  refreshDataGrid() {
    this.dataGrid.instance.refresh();
  }
}

Remove or Rearrange Toolbar Items

If you declare a custom items array, the default array will be overridden. You can leverage this behavior to remove a toolbar item (do not include it in the custom array).
Toolbar items within the UI preserve the order in which they are declared. If you wish to rearrange toolbar items, simply modify their declaration order. You can also control the location wherein a toolbar item appears (the location property specifies the location of a toolbar item within the toolbar itself). In the following sample, the location property is used to move the Search Panel to the left side of the toolbar:
React
export default function App() {
  return (
    <DataGrid>
      <ColumnChooser enabled={true} />
      <SearchPanel visible={true} />
      <Editing allowAdding={true} allowUpdating={true} allowDeleting={true} />
      <Toolbar>
        <Item name="searchPanel" location="before" />
        <Item name="columnChooserButton" />
        <Item name="addRowButton" />
      </Toolbar>
    </DataGrid>
  );
}

Customize Predefined Toolbar Items

If you do not wish to define toolbar items from scratch, you can customize predefined items with the options property. This property accepts the configuration of a DevExtreme component used as the toolbar item. For instance, to customize the Add Row button, use DevExtreme Button properties; for the Export button, use DropDownButton properties, etc. The following code overrides the onClick event handler of the Add Row button and adds a custom item to the Export drop-down menu. Note that the Export menu items array contains undefined entries. They are used as placeholders for default menu commands.
React
export default function App() {
  const dataGridRef = useRef();
  const addRowButtonOptions = useMemo(() => {
    return {
      onClick() {
        dataGridRef.current.instance.addRow();
        notify("Add Row was clicked");
      }
    };
  }, []);
  const exportButtonOptions = useMemo(() => {
    return {
      items: [
        undefined,
        undefined,
        {
          icon: "export",
          text: "Export to CSV",
          onClick() {
            notify("Export to CSV was selected");
          }
        }
      ]
    };
  }, []);

  return (
    <DataGrid
      ref={dataGridRef}>
      <Editing allowAdding={true} allowUpdating={true} allowDeleting={true} />
      <Export enabled={true} allowExportSelectedData={true} />
      <Toolbar>
        <Item name="addRowButton" options={addRowButtonOptions} />
        <Item name="exportButton" options={exportButtonOptions} />
      </Toolbar>
    </DataGrid>
  );
}

Disable/Enable a Toolbar Item

Toolbar items include a disabled property. You can use this property to control user interaction with individual toolbar items (whether the toolbar item responds to a click).
Vue
<template>
  <DxDataGrid>
    <DxColumnChooser :enabled="true" />
    <DxSearchPanel :visible="true" />
    <DxToolbar>
      <DxItem name="columnChooserButton" :disabled="isColumnChooserDisabled" />
      <DxItem name="searchPanel" />
    </DxToolbar>
  </DxDataGrid>
  <DxCheckBox
    text="Disable the Column Chooser Button"
    v-model="isColumnChooserDisabled"
  />
</template>
<script>
// ...
export default {
  // ...
  data() {
    return {
      isColumnChooserDisabled: true
    };
  }
};
</script> 

Hide/Display the Toolbar

To control toolbar visibility, use the visible property.
Angular
<!-- app.component.html -->
<dx-data-grid>
  <!-- … -->
  <dxo-toolbar [visible]="isToolbarVisible"></dxo-toolbar>
</dx-data-grid>
<dx-check-box
  text="Display the Toolbar"
  [(value)]="isToolbarVisible">
</dx-check-box> 
// app.component.ts
// …
export class AppComponent {
   isToolbarVisible: boolean = true;
   // ...
} 

Your Feedback Matters

As always, we welcome your thoughts and feedback. Let us know what you think of our new Toolbar Customization API. Feel free to leave a comment below or contact us via the DevExpress Support Center.
 

FREE DevExpress Xamarin UI Controls

Deliver high-impact native mobile apps with our feature-rich Data Grid, Scheduler, Chart, TabView, Editors, and utility controls. Reserve your free copy today!
alex anashkin
alex anashkin
please give us a multiline toolbar option
22 October 2021
Rob Voutt
Rob Voutt
This is awesome.  I was trying just yesterday to figure out how to change the toolbar after it was initially prepared.
22 October 2021
CRM-0cd4a9d0-8830-437d-8f3f-751a85cdbbba
Customer229902
How the ASPxRichEdit control stands up the text?
24 October 2021
Alex B (DevExpress)
Alex B (DevExpress)
Thanks everyone for your feedback.


@alex anashkin The multiline option is in our long-term plans. In the meantime, you can add a standalone toolbar above the DataGrid to simulate multiline mode.

@Rob Voutt Happy to hear that :)

@Customer229902 I'm afraid it's not quite clear what you mean. Could you please elaborate?
2 November 2021

Please login or register to post comments.