JavaScript Data GridReference Data

This section describes two different strategies for managing reference data in your application. Both approaches implement the same grid example so they can be easily compared.

The examples contained within this section use the following reference data. Note that the data returned from the server only contains codes (keys) which must be mapped to names (values) for display purposes.

// data from server
const rowData = [
    { make: 'tyt', exteriorColour: 'fg', interiorColour: 'bw', price: 35000 },
    { make: 'frd', exteriorColour: 'bw', interiorColour: 'cb', price: 32000 },
    ...
]

// supporting reference data
const carMappings = {
    'tyt': 'Toyota',
    'frd': 'Ford',
    'prs': 'Porsche',
    'nss': 'Nissan'
};

const colourMappings = {
    'cb': 'Cadet Blue',
    'bw': 'Burlywood',
    'fg': 'Forest Green'
};

Using Value Handlers

Value Handlers can be used to map keys contained within the row data to their corresponding display values. This approach involves more coding but allows for different data formats and offers more flexibility managing the data.

The main idea of this approach is to use a valueFormatter to convert the code (key) to a value which is displayed in the cell. Then use a valueParser to convert the name back to a code (key) when saving it down into the underlying data.

const gridOptions = {
    columnDefs: [
        {
            field: 'make',
            cellEditor: 'agSelectCellEditor',
            cellEditorParams: {
                values: extractKeys(carMappings) 
            },
            // convert code to value
            valueFormatter: params => {
                return lookupValue(carMappings, params.value);
            },
            // convert value to code
            valueParser: params => {
                return lookupKey(carMappings, params.newValue);
            }
        }
    ],

    // other grid options ...
}

When using the TextCellEditor with a valueFormatter, you may want to display the formatted text rather than the code when editing. In this case you should also include the useFormatter property as follows:

cellEditor: 'agTextCellEditor',
cellEditorParams: {
    useFormatter: true
}

Example: Value Handlers

The following example demonstrates how Value Handlers can be combined to work with reference data:

• 'Make' Column: uses the built-in 'select' Cell Editor. Mapped names are displayed in the dropdown list and selections are saved as 'make' codes in the underlying data.

• 'Exterior Colour' Column: uses the built-in 'richSelect' Cell Editor. Mapped names are displayed in the dropdown list and selections are saved as 'colour' codes in the underlying data.

• 'Interior Colour' Column: uses a Text Cell Editor with useFormatter=true. Mapped names are displayed in the cells and edited values are saved as 'colour' codes in the underlying data. (Note: a valid name must be entered or the value will be saved as undefined.)

• Set Filters: display a list of names rather than codes.

• 'Price' Columns: additionally demonstrate the use of valueGetters and valueSetters.

Using the 'refData' Property

Here we present the same example but this time using the refData ColDef property. This approach requires less coding and is more straightforward, but might not be flexible enough for scenarios involving more complex reference data formats.

All that is required with this approach is to specify the refData and the grid will take care of the rest, as shown below:

const gridOptions = {
    columnDefs: [
        {
            field: 'make',
            cellEditor: 'agSelectCellEditor',
            cellEditorParams: {
               values: extractKeys(carMappings)
            },
            refData: carMappings
        }
    ],

    // other grid options ...
}

Like in the previous example using Value Handlers, where the underlying data contains codes, the grid will use the specified reference data to display the associated values in the cells and save down the codes (keys) in the data when editing.

Example: 'refData' Property

The following example demonstrates how the refData property simplifies working with reference data:

• 'Make' Column: uses the built-in 'select' Cell Editor with the refData property specified. Mapped names are displayed in the dropdown list and selections are saved as 'make' codes in the underlying data.

• 'Exterior Colour' Column: uses the built-in 'richSelect' Cell Editor with the refData property specified. Mapped names are displayed in the dropdown list and selections are saved as 'colour' codes in the underlying data.

• 'Interior Colour' Column: uses a Text Cell Editor (not recommended) with refData. Mapped names are displayed in the cells but when editing, colour codes (cb,bw,fg) must be entered directly. As users should not know codes, the Text Cell Editor is not recommended for use with refData in real world applications.

• Set Filters: display a list of names rather than codes.

• 'Price' Columns: additionally demonstrate the use of valueGetters and valueSetters.