Polymer Datagrid

Here we explain how to use ag-Grid inside an Polymer application. It is broken down into the following sections:

Getting Started

Learn how to get a simple application working using ag-Grid and Polymer 2 Start here to get a simple grid working in your application, then follow on to further sections to understand how particular features work.

Go to Getting Started

More Details

Dive deeper in how to use ag-Grid with Polymer 2, including more examples and an overview on interfacing.

Go to More Details

Feature Roadshow

Enterprise Grade Features

Aggregation

When grouping you can also do Aggregation to get aggregate values for the data i.e. sum, min, max etc. Use the built in aggregate functions or create your own.

columnDefs = [
    {field: 'country', rowGroup: true},
    {field: 'gold', aggFunc: 'sum'},
    ...
]

Clipboard

Copy and paste data to and from the Clipboard. Users will be able to edit data in Excel, then copy the data back into the grid when done.

Column Menu

The Column Menu drops down from the column header. Use the default options or provide your own.

Context Menu

The Context Menu appears when you right click on a cell. Use the default options or provide your own.

Excel Export

Export in native Excel Format which will maintain the column widths and also allow exporting of styles. For example, you can color cells in the grid and have the equivalent cells colored in the Excel export.

Grouping Rows

Use Grouping Rows to group the data over selected dimensions. You can set the data to group by specific columns, or allow the user to drag and drop columns of their choice and have it grouped on the fly.

columnDefs = [
    {field: 'country', rowGroup: true},
    {field: 'sport'},
    ...
]

Master / Detail

Use Master Detail to expand rows and have another grid with different columns inside.

Pivoting

Make columns out of values by Pivoting on the data, similar to Pivot Tables in Excel.

columnDefs = [
    {field: 'country', rowGroup: true},
    {field: 'sport', pivot: true},
    {field: 'gold', aggFunc: 'sum'},
    ...
]

Range Selection

Drag the mouse over cells to create a Range Selection. This is handy for highlighting data or for copying to the clipboard.

// enable sorting with grid option
gridOptions = {
    enableRangeSelection: true,
    ...
}

Set Filter

Set Filter works like Excel, providing checkboxes to select values from a set.

colDef = {
    field: 'country',
    filter: 'set'
}

Status Bar

The Status Panel appears on the bottom of the grid and shows aggregations (sum, min, max etc.) when you select a range of cells using range selection. This is similar to what happens in Excel.

Tool Panel

The Tool Panel allows the user to manipulate the list of columns, such as show and hide, or drag columns to group or pivot.

gridOptions: {
    showToolPanel: true,
    ...
}

Tree Data

Use Tree Data to display data that has parent / child relationships where the parent / child relationships are provided as part of the data. For example, a folder can contain zero or more files and other folders.

Core Grid Features

Accessibility

The grid has ARIA roles inside the cells for Accessibility to enable navigation with screen readers.

Aligned Grids

Have one or more grids horizontally Aligned so that any column changes in one grid impact the other grid. This allows two grids with different data to be kept horizontally in sync.

Cell Editing

Users can update data with Cell Editing. Use one of the provided cell editors or create your own to suit your business needs.

colDef = {
    field: 'country',
    cellEditor: 'richSelect',
    cellEditorParams: {
        values: ['Ireland','United Kingdom']
    }
    ...
}

Column Filter

Column Filters appear in the column menu. The grid comes with filters out of the box: text, number, date and set filters. You can also create your own customer filter.

gridOptions = {
    // turn on filtering
    enableFilter: true,
    ...
    columnDefs: [
    {field: "athlete", filter: "text"},
    {field: "age",     filter: "number"},
    {field: "sport",   filter: MyCustomerFilter}
]}

Column Groups

Columns can be grouped together into Column Groups. Additionally you can configure groups to be expandable to show and hide columns within the group.

columnDefinitions = [
    {group: 'User Details', children: [
        {field: 'firstName', pinned: 'left'},
        {field: 'lastName', width: 100},
        {field: 'phoneNumber'}
    ]};
];

Column Moving

Columns can be moved inline by either dragging the column with the mouse, or my using the API.

Column Pinning

Use Column Pinning to pin one or more columns to the left or to the right. Pinned columns are always present and not impacted by horizontal scroll.

var columns = [
    {field: 'athlete', pinned: 'left'},
    {field: 'total', pinned: 'right'},
    ...
]

Column Resizing

Resize columns by dragging the edge of the column header, Auto Fill to fill the grid width, or Auto Size columns to fit their content.

// get columns to fit the grid width
api.sizeColumnsToFit();

// get columns to fit content
columnApi.autoSizeAllColumns();

CSV Export

Use CSV Export to take data out of the grid and into another application for further processing such as Excel.

Custom Filter

Create your own Custom Filter to match your own business requirements.

colDef = {
    field: 'name',
    filter: MyCustomFilter
}

Date Filter

Date Filter allows filtering dates with {equals, notEquals, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}.

colDef = {
    field: 'date',
    filter: 'date'
}

External Filter

External Filter allows you to build filters that live outside of the grid. For example, you can include your own widgets outside the grid for your own filter.

Keyboard Navigation

With Keyboard Navigation users can use cursor keys and tab keys to navigate between cells.

Layout For Print

Use For Print to have the grid render without using any scrollbars. This is useful for printing the grid, where all rows should be printed, not just what's visible on the screen.

Number Filter

Number Filter allows filtering numbers with {equals, notEquals, lessThanOrEqual, greaterThan, greaterThanOrEqual, inRange}

colDef = {
    field: 'totalWinnings',
    filter: 'number'
}

Pagination

Use Pagination when you don't want the user to have to scroll. Pagination allows viewing rows one page at a time.

gridOptions = {
    pagination: true,
    ...
}

Quick Filter

Quick Filter filters all columns simultaneously with a simple text search, just like how you filter your Gmail.

// you pass the filter text to the grid
// via the grid's API
api.setQuickFilter(searchText)

Row Selection

Row Selection to select rows. Choose between click selection or checkbox selection. Selecting groups will select children.

// enable sorting with grid option
gridOptions = {
    // set to 'single' or 'multiple'
    rowSelection: 'multiple',
    ...
}

Row Sorting

Row Sorting will sort the data. Sort a column by clicking the header. Sort multiple columns by holding down shift.

// enable filtering with grid option
gridOptions = {
    enableSorting: true,
    ...
}

Row Dragging

Row Dragging allows you to re-arrange rows by dragging them.

Text Filter

Text Filter allows filtering text strings with {equals, notEqual, contains, notContains, startsWith, endsWith}.

colDef = {
    field: 'athlete',
    filter: 'text',
    filterOptions: {'equals', 'contains'}
}

Touch Support

User can navigate the features of the grid on a touch device with the built-in Touch Support. You don't need to do anything, it works out of the box.

Configuration

Column Definitions

Columns are configured in the grid by providing a list of Column Definitions. The attributes you set on the column definitions define how the columns behave e.g. title, width etc.

columnDefinitions = [
    {field: 'firstName', width: 100px},
    {field: 'lastName', width: 100px},
    {field: 'phoneNumber', width: 200px}
];

Grid Size

Set the Width and Height of the grid using CSS. If your application changes the size of the grid at run time, the grid will dynamically adjust to the new size.

<!-- set using exact pixel -->
<ag-grid style="height: 200px; width: 400px;"/>

<!-- or set using percent -->
<ag-grid style="height: 100%; width: 100%;"/>

Styling & Appearance

Animation

Rows in the grid will Animate into place after the user sorts or filters.

gridOptions = {
    animateRows: true
    ...
}

Cell Rendering

Use Cell Rendering to have cells rendering values other than simple strings. For example, put country flags beside country names, or push buttons for actions.

colDef = {
    field: 'country',
    cellRenderer: MyCountryCellRenderer
    ...
}

Cell Styling

Use CSS rules to define Cell Style based on data content, e.g. put a red background onto cells that have negative values, and green on values greater than 100.

cellClassRules = {
    // put CSS class 'highlight-negative' onto cells
    // that have negative values.
    'highlight-negative': 'x < 0'
    'highlight-large-value': 'x > 100'
}

Column Headers

The display of column headers can be fine-tuned to change Header Height and Text Orientation for example.

// set heights as a grid option
gridOptions = {
    headerHeight: 25,
    headerHeight: 40    
}

// display text vertically using CSS
.ag-header-cell-label .ag-header-cell-text {
    transform: rotate(90deg);
}

Column Spanning

Column Spanning allows cells to span columns, similar to cell span in Excel

colDef = {
    field: 'country',
    colSpan: function(params) {
        // span 2 cols for Russia, otherwise 1
        var country = params.data.country;
        return country==='Russia' ? 2 : 1;
    }
    ...
};

Custom Icons

All the icons in the grid can be replaced with your own Custom Icons. You can either use CSS or provide your own images.

gridOptions = {
    icons: {
        // use font awesome for menu icons
        menu: '<i class="fa fa-bath"/>',
        filter: '<i class="fa fa-long-arrow-down"/>',
        columns: '<i class="fa fa-handshake-o"/>'
    }
    ...
}

Full Width Rows

Full Width Rows allow you to have one cell that spans the entire width of the tables. This allows a card layout to work alongside the normal cells.

gridOptions = {
     isFullWidthCell: function(rowNode) {
        // return every second row as full width
        return rowNode.rowIndex % 2 === 0;
    },
    // use custom component for the full width row
    fullWidthCellRenderer: MyCardComponent
}

Internationalisation

Support multiple languages with Internationalisation.

gridOptions = {
    localeText: {
        lessThanOrEqual: 'menor o igual',
        greaterThanOrEqual: 'mayor o igual',
        ...
    }
}

Overlays

Full control of Overlays to display messages to the user on top of the grid

Row Height

Rows can have different Row Height. You can even change the row height dynamically at run time.

gridOptions = {
    // getRowHeight is a grid callback
    getRowHeight = function(params) {
        // 25 px for even rows, 50 px for other rows
        var rowIndex = params.node.rowIndex;
        var rowEven = rowIndex % 2 === 0;
        return rowEven ? 25 : 50;
}

Row Pinning

Use Pinned Rows to pin one or more rows to the top or the bottom. Pinned rows are always present and not impacted by vertical scroll.

// set pinned column using grid property
gridOptions = {
    pinnedTopRowData: [],
    pinnedBottomRowData: [],
    ...
}

RTL

Use Right to Left alignment to allow languages such as Arabic & Hebrew.

Working with Data

Accessing Data

Once data is in the grid, you can Access the Data using the grid's API.

// get the number of displayed rows
gridApi.getDisplayedRowCount()

// get the first row
gridApi.getDisplayedRowAtIndex(0);

Change Detection

As you change data inside the grid, the grid runs Change Detection to check if any other cells need to be updated to reflect the change.

Expressions

Expressions allow you to use simple strings instead of functions for value getters, setters, formatters and parsers.

var columns = [
    {        
        valueGetter: 'data[0]',
        valueSetter: 'data[0] = newValue',
        valueFormatter: '"$"+value',
        valueParser: 'Number(params.newValue)'
    }
];

Reference Data

Use Reference Data for easier editing of data that uses reference data for display. For example, you might have country codes in your data e.g. {IE, UK, USA} but you display values e.g. {Ireland, Great Britain, United States of America}). Using reference data simplifies this, especially if editing.

Setters and Parsers

Value Setters and Value Parsers are the inverse of value getters and value formatters. Value setters are for placing values into data when field cannot be used. Value parser is for parsing edited values, e.g. removing formatting before storing into the data.

var columns = [
    // this example assumes the data is in an array,
    // so you want to access indexes of the array rather
    // than using field
    {
        // value getter returns first array element
        valueGetter: function(params) {
            var data = params.data;
            return data[0];
        },
        // value setter sets first array element
        valueSetter: function(params) {
            var data = params.data;
            data[0] = params.newValue;
        }
    },
    // this column is for a number, the default editor sets
    // strings, so we convert the string to a number
    {
        field: 'amount',
        valueFormatter: function(params){
            return Number(params.newValue);
        }
    }
];

Updating Data

Data can be updated in real time. The grid can highlight the change by flashing the cells or by animation inside the cell as the cell refreshes.

// get a reference to the right row
var rowNode = api.getRowNode('22');

// set new value into the row
rowNode.setDataValue('bid', 33.24);

Value Cache

The Value Cache is used to store results of value getters. It is always on, enhancing the performance of the grid.

Value Getters & Value Formatters

Value Getters & Value Formatters are about getting and formatting the data to display. Use Value Getters when the data is not a simple field. Use Value Formatters to format values for display.

var columns = [
    // two simple cols, A and B
    {field: 'a'},
    {field: 'b'},
    // total column, giving sum of A and B
    {headerName: 'Total', 
        valueGetter: function(params) {
            var data = params.data;
            return data.a + data.b;
        }
    },
    {field: 'price', 
        // simple currency formatter putting in dollar sign
        valueFormatter: function(params){
            return '$' + params.value;
        },
    }
];

Value Handlers

Each grid column typically has a field where it gets the value to display. However you can provide more logic here to get finer control over how data is retrieved (for display) and stored (after editing) with the family of Value Handlers.

var columns = [
    // two simple cols, A and B
    {field: 'a'},
    {field: 'b'},
    // total column, giving sum of A and B
    {headerName: 'Total', 
        valueGetter: function(params) {
            var data = params.data;
            return data.a + data.b;
        }
    },
    {field: 'price', 
        // simple currency formatter putting in dollar sign
        valueFormatter: function(params){
            return '$' + params.value;
        },
    }
];

View Refresh

If the data changes outside of the grid, get the grid to do a View Refresh to update the UI to the latest values. The grid will use change detection to only refresh values that have changed.

// refresh all cells in the grid
gridApi.refreshCells();

Performance

Performance

The core grid engine gives Performance unlike that seen before. The grid uses row and column virtualisation, animation frames and many other techniques.