columns lookup

    Specifies options of a lookup column.

    Type: Object
    Default Value: undefined

    Use a lookup column if you need to restrict the set of values that can be chosen when a user edits or filters a grid column. In a lookup column, each cell is a drop-down menu where items represent available values. Additionally, you can use a lookup column when you need to substitute displayed values for required values.

    For example, consider that you have two arrays of objects: Drivers and Buses.

    JavaScript
    var drivers = [
        { DriverID: 1, FirstName: 'John', LastName: 'Smith', BusID: 2 },
        { DriverID: 2, FirstName: 'Lizzy', LastName: 'Cook', BusID: 1 },
        { DriverID: 3, FirstName: 'Brian', LastName: 'Hawkins', BusID: 3 }
    ];
    
    var buses = [
        { BusID: 1, Plates: '123456' },
        { BusID: 2, Plates: 'AB-1234'  },
        { BusID: 3, Plates: 'CD-9876' }
    ];

    The objects of the Drivers array have the BusID field, which binds these two arrays together. If the Drivers array takes on the role of the main grid data source, the BusID grid column displays the IDs of buses, which do not matter to a user. In this situation, it will be more convenient to display the bus license plates specified in the Plates field. For this purpose, the Buses array must be set as a lookup data source for the BusID grid column using the lookup | dataSource option. Then, the valueExpr option must be set to "BusID" indicating the field whose values should be replaced. These values will be replaced by the values of the field specified by the displayExpr option.

    JavaScript
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: drivers,
            // ...
            columns: [
                // ...
                { dataField: 'BusID', lookup: { dataSource: buses, valueExpr: 'BusID', displayExpr: 'Plates' } },
                // ...
            ]
        });
    });

    With this code applied, the "BusID" grid column contains the bus license plates instead of the bus IDs. Moreover, now the user can choose a plate number using the drop-down menu in a filter row cell to filter records, or a column cell to edit this cell. If these features are not required, assign false to the allowFiltering or allowEditing column option correspondingly.

    Show Example:
    jQuery

    In this example, the "Format" is declared as a lookup column. To filter grid records by this column, use the select box appearing in this column's filter row cell. Additionally, you can edit grid records. Note that when you edit values in the "Format" column, a select box similar to the filtering one does not let you enter any values other than those represented in the select box.

    <div id="gridContainer" style="height:390px; max-width:800px; margin: 0 auto"></div>
    
    var books = [
       { author: 'J. D. Salinger', title: 'The Catcher in the Rye', year: 1951, genre: 'Bildungsroman', formatID: 2 },	
       { author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi', formatID: 1 },
       { author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi', formatID: 3 },
       { author: 'K. Vonnegut', title: "God Bless You, Mr. Rosewater, or Pearls Before Swine", year: 1965, genre: 'Novel', formatID: 2 },
       { author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction', formatID: 1 },
       { author: 'H. Lee', title: "To Kill a Mockingbird", year: 1960, genre: 'Novel', formatID: 3 },
       { author: 'G. Orwell', title: "Nineteen Eighty-Four", year: 1949, genre: 'Dystopian novel, political fiction', formatID: 1 },
       { author: 'G. Grass', title: "The Tin Drum", year: 1959, genre: 'Speculative fiction', formatID: 1 },
       { author: 'R. Bradbury', title: "Dandelion Wine", year: 1957, genre: 'Novel', formatID: 3 },
       { author: 'R. Bradbury', title: "The Martian Chronicles", year: 1950, genre: 'Sci-fi', formatID: 3 },
       { author: 'R. Bradbury', title: "Fahrenheit 451", year: 1953, genre: 'Dystopian novel', formatID: 2 },	
       { author: 'C. Dickens', title: "Great Expectations", year: 1861, genre: 'Realistic fiction', formatID: 2 },
       { author: 'F. Scott Fitzgerald', title: "The Great Gatsby", year: 1925, genre: 'Novel', formatID: 1 },
       { author: 'E. Hemingway', title: "For Whom the Bell Tolls", year: 1940, genre: 'War novel', formatID: 3 },
       { author: 'E. Hemingway', title: "Farewell to Arms", year: 1929, genre: 'War novel', formatID: 3 },
       { author: 'J. Austen', title: "Pride and Prejudice", year: 1813, genre: 'Novel of manners', formatID: 2 }
    ];
    
    var formats = [
        { id: 1, format: 'hardcover' },
        { id: 2, format: 'paperback' },
        { id: 3, format: 'e-book' },
    ];
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre',
                { dataField: 'formatID', caption: 'Format', lookup: { dataSource: formats, valueExpr: 'id', displayExpr: 'format' } }
            ],
            paging: { pageSize: 7 },
            filterRow: { visible: true },
            editing: { editEnabled: true }
        });
    });

    allowClearing

    Specifies whether or not a user can nullify values of a lookup column.

    Type: Boolean
    Default Value: false

    By default, when editing, a user cannot assign null to a cell of a lookup column. But if your data source accepts null values, set the lookup | allowClearing option to true for the column. In this case, a cell of a lookup column in the editing state is supplied with a button that nullifies this cell's value.

    Show Example:
    jQuery

    In this example, "Format" is declared as a lookup column. When a cell of this column is in the editing state, it is supplied with a button that nullifies its value. You can hide this button at runtime by toggling the check box under the grid.

    <div id="gridContainer" style="height: 350px; max-width: 800px; margin: 0 auto"></div>
    <div style="text-align:center">
        <div id="allowClearingCheckbox" style="height:25px; width:auto"></div>
    </div>
    
    var books = [
       { author: 'J. D. Salinger', title: 'The Catcher in the Rye', year: 1951, genre: 'Bildungsroman', formatID: 2 },	
       { author: 'D. Adams', title: "The Hitchhiker's Guide to the Galaxy", year: 1979, genre: 'Comedy, sci-fi', formatID: 1 },
       { author: 'K. Vonnegut', title: "Cat's Cradle", year: 1963, genre: 'Satire, sci-fi', formatID: 3 },
       { author: 'K. Vonnegut', title: "God Bless You, Mr. Rosewater, or Pearls Before Swine", year: 1965, genre: 'Novel', formatID: 2 },
       { author: 'M. Mitchell', title: "Gone with the Wind", year: 1936, genre: 'Historical fiction', formatID: 1 },
       { author: 'H. Lee', title: "To Kill a Mockingbird", year: 1960, genre: 'Novel', formatID: 3 },
       { author: 'G. Orwell', title: "Nineteen Eighty-Four", year: 1949, genre: 'Dystopian novel, political fiction', formatID: 1 },
       { author: 'G. Grass', title: "The Tin Drum", year: 1959, genre: 'Speculative fiction', formatID: 1 },
       { author: 'R. Bradbury', title: "Dandelion Wine", year: 1957, genre: 'Novel', formatID: 3 },
       { author: 'R. Bradbury', title: "The Martian Chronicles", year: 1950, genre: 'Sci-fi', formatID: 3 },
       { author: 'R. Bradbury', title: "Fahrenheit 451", year: 1953, genre: 'Dystopian novel', formatID: 2 },	
       { author: 'C. Dickens', title: "Great Expectations", year: 1861, genre: 'Realistic fiction', formatID: 2 },
       { author: 'F. Scott Fitzgerald', title: "The Great Gatsby", year: 1925, genre: 'Novel', formatID: 1 },
       { author: 'E. Hemingway', title: "For Whom the Bell Tolls", year: 1940, genre: 'War novel', formatID: 3 },
       { author: 'E. Hemingway', title: "Farewell to Arms", year: 1929, genre: 'War novel', formatID: 3 },
       { author: 'J. Austen', title: "Pride and Prejudice", year: 1813, genre: 'Novel of manners', formatID: 2 }
    ];
    
    var formats = [
        { id: 1, format: 'hardcover' },
        { id: 2, format: 'paperback' },
        { id: 3, format: 'e-book' },
    ];
    
    $(function () {
        $("#gridContainer").dxDataGrid({
            dataSource: books,
            columns: [
                'author',
                { dataField: 'title', width: 210 },
                'year', 'genre',
                { dataField: 'formatID', caption: 'Format', lookup: { dataSource: formats, valueExpr: 'id', displayExpr: 'format', allowClearing: true } }
            ],
            paging: { pageSize: 5 },
            filterRow: { visible: true },
            editing: {
                editEnabled: true,
                editMode: 'batch'
            }
        });
    
        $("#allowClearingCheckbox").dxCheckBox({
            value: true,
            text: 'Allow Clearing',
            onValueChanged: function (info) {
                var dataGrid = $('#gridContainer').dxDataGrid('instance');
                dataGrid.columnOption('Format', 'lookup.allowClearing', info.value);
            }
        });
    });

    dataSource

    Specifies the data source providing data for a lookup column.

    Default Value: undefined

    In order to have correspondence between the values from the main data source and those values that need to be displayed, specify a lookup data source. This data source can be one of the following.

    • An Array of objects
      The fields of each object will be used to provide data for the lookup select box.

    • A DataSource Configuration Object
      The DataSource is a stateful object that includes options for data sorting, grouping, filtering; it also keeps data transformation options and applies them each time data is loaded. The DataSource also provides events intended to handle changing data and the state. The DataSource underlying data access logic is isolated in a Store. Unlike the DataSource, a Store is a stateless object implementing a universal interface for reading and modifying data. To learn more, refer to the Data Layer topic.

    The lookup data source must contain fields that are used to define the valueExpr and displayExpr options of the lookup configuration object.

    When using a CustomStore to specify a data source for a lookup column, implementing its load and byKey functions is mandatory.

    displayExpr

    Specifies the expression defining the data source field whose values must be displayed.

    Type: String|function(data)
    Function parameters:
    data: Object
    A data object.
    Default Value: undefined

    This option specifies the field of the data source whose values must be displayed in place of the values of the field defined by the valueExpr option. When you need to simply substitute values of one field for values of another, assign the names of these fields to the valueExpr and displayExpr fields of the lookup object correspondingly. In case you need to compound the value to be displayed from several data source fields, assign a callback function returning this value to the displayExpr option. Within this function, you can access the object of the lookup data source using the function's parameter.

    valueExpr

    Specifies the expression defining the data source field whose values must be replaced.

    Type: String
    Default Value: undefined

    This option specifies the field of the data source whose values must be replaced by the values of the field defined by the displayExpr option.