The page you are viewing does not exist in version 13.2. This link will take you to the Overview page.
The page you are viewing does not exist in version 13.1. This link will take you to the Overview page.
Configure DataGrid /
« Prev step
Next step »
In this tutorial, you will learn how to configure basic features of the dxDataGrid widget. As an example, you will implement a grid containing data about books. This grid can be used to sort out the contents of a private book collection or to represent the assortment of an online bookstore.
To learn grid concepts and feature overviews, refer to the Data Grid section within the UI Widgets guides.
To find a full list of DevExtreme UI widgets, refer to the Reference section.
First, reference files required by the dxDataGrid on your HTML page. Add these files as scripts or links to the head of the page as it is done in the HTML file below. Note that in addition to the usual jQuery/Knockout/Angular, Globalize and widget scripts, dxDataGrid requires at least two stylesheet files. These mandatory files are the "dx.common.css", which provides the core styles and a theme-file that provides the distinctive look for dxDataGrid. You can find the libraries and stylesheets in your DevExtreme package.
For more information on linking libraries, refer to the Installation article.
Once the required libraries are referenced, you can create the dxDataGrid widget on your page. Add a div element to the body of the HTML document. It will be the container for the dxDataGrid widget.
Then, add a .js file to your project and reference it in the head of your HTML file just like you did for the libraries in the previous step. Create the dxDataGrid widget within the added div container by putting the code below into the .js file.
If you run the code now, you will see an empty widget indicating that there is no data in it. In the next step, you will provide data for the dxDataGrid widget.
dxDataGrid supports two types of data sources: an array of objects and a DataSource object. When an array of objects is used, fields of each object from this array provide data for corresponding grid columns. Using a DataSource object is a more sophisticated but flexible approach to providing data. This object is specially designed to easily retrieve data from any storage (local, memory or a data service). As a stateful object, DataSource includes options for data sorting, grouping, filtering; it also keeps data transformation options and applies them each time data is loaded. To learn more about the DataSource object, refer to the Data Layer topic.
Although the DataSource object provides a wider range of capabilities, it is more complex than an array of plain objects. For the sake of simplicity, this tutorial will use the array of objects. A grid with a remote data source is demonstrated in the Use Remote Data for DataGrid tutorial.
To provide data for the grid, declare an array of objects and assign it to the dataSource option of dxDataGrid. Each object in this array contains information about a book.
To get detailed information about providing and binding your data to the dxDataGrid widget, see the Data Binding topic.
Run the resulting code and you will see a grid with columns generated for each field of the objects in the assigned array. In the next step, you will configure the appearance of these columns.
To configure grid columns, assign an array to the columns option. Each object in this array represents a column. If it is not necessary to specify column options except for the data field, include the name of the data field in this array instead of the whole object. The order of objects/data fields in the columns array defines the resulting order of columns in a grid.
In our example, the "Language" column may be redundant if all books in the collection are written in one language. In which case, it (the column) is omitted from the columns array. Data contained in the "Price" and "Genre" columns is optional either, but it may be useful in some cases. Make these columns hidden by default by setting the visible option to false for them.
A user can make hidden columns visible using the column chooser that can be invoked by a click on a button that appears in the upper-right corner of the grid layout. By default, the column chooser is disabled, so set the enabled option of the columnChooser object to true. Additionally, adjust the width of the columns using the width option in order to make the grid more comprehensible.
If you run the code now, you will see the executed changes applied. Move to the next step to discover how to specify column reordering settings.
You can allow a user to reorder grid columns by setting the allowColumnReordering option to true. If you do so, the user can drag-and-drop columns to reorder them. However, certain columns can be restricted from being used in reordering. Set the allowReordering option for those columns to false, if such a restriction is required.
In your grid, allow column reordering for the grid and move to the next step where you will learn to configure sorting in the dxDataGrid widget.
To sort grid records by values of a column, a user must click the header of this column or choose a required sort order from a context menu appearing by a right-click on the column header. If you set the sorting | mode option to "multiple", the user will be able to sort records of several columns. Sorting of several columns can be performed using the context menu only. Additionally, sorting can be disabled in certain columns by setting the allowSorting option of these columns to false.
Grid records may appear sorted if a sort index and sort order is set for a column. In the grid being configured, specify an ascending initial sort order for the "Year" column and a multiple sorting mode for the grid as it is shown in the code below.
If you run the code you have by now, you will see that books in the grid are sorted by year initially, and all columns are available to be sorted. The next step will take you through steps needed for specifying grouping settings.
To group grid records, a user must drag-and-drop a column onto a group panel located in the upper-left corner of the grid layout. In order to enable grouping, make the group panel visible by setting the groupPanel | visible option to true. Certain columns can be restricted from being grouped. For these columns, the allowGrouping option must be set to false. The appearance of the group panel can be configured using options of the groupPanel object.
In the grid being configured, make the group panel visible and disable grouping for the "Title", "Year", "Price" and "Length" columns. Then, move to the next step to configure paging.
When paging is used, data from the source is loaded page-by-page, while size of the pages is specified by the paging | pageSize option. To navigate through pages, you can use a pager and/or scrolling. To configure the pager, use options of the pager object. Scrolling options can be set in the scrolling object.
If you have decided to use the pager, you can allow a user to change the page size at runtime. Specify the available page sizes using the allowedPageSizes option of the pager object.
If scrolling is your choice, set one of the scrolling modes using the scrolling | mode option. Note that you can use both the pager and scrolling if it suits your needs best, but not if the scrolling mode is "infinite".
Due to the small size of the data source, the grid in our example uses a pager to navigate through pages. The page size is set to 7.
You have completed configuring the main appearance of the dxDataGrid widget. In the following steps, you will discover how to manipulate data in a grid.
To enable grid editing, set its editing | editEnabled option to true.
Grid records can be edited in one of two modes - "row" and "batch" - specified by the editing | editMode option. In row mode, grid records are edited by rows. To edit a row, a user must click the "Edit" button located in a specific grid column. Changes made in the row can be saved or discarded by clicking the "Save" or "Cancel" button in this row.
In batch mode, all changes made in the grid will not be saved until the "Save" button is clicked. This button becomes active when the user makes changes. The "Revert" button also becomes active. When this button is clicked, the changes are reverted. In this mode, grid records are edited in cells. To edit a cell, a user must click it. Moreover, in batch mode, the user can recover deleted rows if changes have not yet been saved. For this purpose, he or she must use the "Undelete" button, which appears instead of the "Delete" button in the removed row.
Additionally, you can prohibit editing in a specific column. For this purpose, set the allowEditing option of the column to false.
For the grid being configured, the row edit mode suits better, so enable editing and set the editMode option to "row" as shown below.
To specify whether or not records can be added to and removed from a grid, set the insertEnabled and removeEnabled options of the editing configuration object. In order to add a record, a user must click the "Add New Item" button located in the upper-right-corner of the grid layout. The added record appears empty as the first record of the grid telling the user to enter data into its cells.
To remove a record, the user must click the "Delete" button that accompanies this record. In the batch edit mode, the removed record can be recovered by clicking the "Undelete" button appearing in place of the "Delete" button.
To enable a user to add and remove grid records in the grid being implemented, set the insertEnabled and removeEnabled options of the editing object. After that, move to the next step, where you will discover how to configure filtering and searching in the dxDataGrid widget.
Basically, searching and filtering in dxDataGrid are very similar. Filtering is searching in a single column. Due to this similarity, both filtering and searching are specified by the allowFiltering option. If this option is set to true for a column, grid records can be filtered by the values of this column, and the values within this column can be searched.
Filtering can be performed using a filter row, whose settings are specified by options of the filterRow object. Additionally, a user can choose a filter to be applied to the column from a menu. This menu can be invoked by clicking a magnifying glass icon that accompanies the filter row cell of the columns where filtering is allowed.
Searching can be performed by typing a search string in a search panel, whose settings are specified by options of the searchPanel object.
You can disable filtering or searching completely, if necessary. For this purpose, hide the filter row or the search panel by setting the visible option of the configuration object corresponding to the grid element to be hidden.
Configure the grid by making the filter row and search panel visible, and then move on to the final step, where you will learn how to adjust the selection functionality in the dxDataGrid widget.
Selection in the dxDataGrid widget can be carried out in a single or multiple mode. The single mode is preferable when you only require one grid record to be selected at a time. In this mode, when a user selects another record, the previously selected record becomes unselected. To set this mode, assign "single" to the selection | mode option.
When selecting several grid records is required, set the multiple selection mode. In this mode, a grid is supplemented with a selection column that contains check boxes accompanying each grid record. A user can select grid records using these check boxes.
For the grid with books, selection is not necessary, so the selection | mode option is set to none in the code in the playground below. However, you can experiment with it and try to assign "single" or "multiple" to the aforementioned option.
In this tutorial, you have learned to configure the basic features of the dxDataGrid widget. For the full list of its options, you see our Reference section. In case you want to see dxDataGrid demos, visit our Visualization Gallery.