Framework:javascriptangularreactvue

Grid Interface

This section details the public interface that your application can use to interact with the grid, including methods, properties and events.

The grid interface is the combination of the following items:

  • Grid Properties: properties used to configure the grid, e.g. pagination = true.
  • Grid API: methods used to interact with the grid after it's created, e.g. api.getSelectedRows().
  • Grid Events: events published by the grid to inform applications of changes in state, e.g. rowSelected.
  • Grid Callbacks: callbacks are used by the grid to retrieve required information from your application, e.g. getRowHeight().
  • Row Node: each row in the grid is represented by a Row Node object, which in turn has a reference to the piece of row data provided by the application. The Row Node wraps the row data item. The Row Node has attributes, methods and events for interacting with the specific row e.g. rowNode.setSelected(true).

Grid Options

The gridOptions object is a 'one stop shop' for the entire interface into the grid. The grid options can be used regardless of the framework you are using, but if you are using a framework you might find it easier to use your framework's bindings. How to configure for a particular framework is explained further down this page.

The example below shows the different types of items available on gridOptions.

var gridOptions = {
    // PROPERTIES
    // Objects like myRowData and myColDefs would be created in your application
    rowData: myRowData,
    columnDefs: myColDefs,
    pagination: true,
    rowSelection: 'single',

    // EVENTS
    // Add event handlers
    onRowClicked: function(event) { console.log('A row was clicked'); },
    onColumnResized: function(event) { console.log('A column was resized'); },
    onGridReady: function(event) { console.log('The grid is now ready'); },

    // CALLBACKS
    isScrollLag: function() { return false; }
}

Once the grid is initialised, you will also have access to the grid API (api) and column API (columnApi) on the gridOptions object as shown:

// refresh the grid
gridOptions.api.refreshView();

// resize columns in the grid to fit the available space
gridOptions.columnApi.sizeColumnsToFit();

Listening to Events

In addition to adding event listeners directly via the gridOptions object, it is possible to register for events, similar to registering for events on native DOM elements. This means there are two ways to listen for events: either to use the onXXX() method on the API (where XXX is replaced with the event name), or to register for the event. The latter option allows you to add multiple handlers for the same event. The following example demonstrates the two options:

// create handler function
function myRowClickedHandler(event) {
    console.log('The row was clicked');
}

// option 1: use the API
gridOptions.onRowClicked = myRowClickedHandler;

// option 2: register the handler
gridOptions.api.addEventListener('rowClicked', myRowClickedHandler);

Events Are Asynchronous

Grid events are asynchronous so that the state of the grid will be settled by the time your event callback gets invoked.

Default Boolean Properties

Where the property is a boolean (true or false), then false (or left blank) is the default value. For this reason, on / off items are presented in a way that causes the most common behaviour to be used when the value is false. For example, suppressCellSelection is named as such because most people will want cell selection to be enabled.

Angular

The gridOptions are fully available for Angular. However, you can also take advantage of the properties and events provided by ag-Grid's Angular Component. This is done as follows:

  • Attributes: attributes are defined as normal HTML attributes and set non-bound values.
  • Properties: properties are defined as HTML attributes enclosed in square brackets and are Angular bound values.
  • Callbacks: callbacks are actually a type of property, but by convention they are always functions and are not for relaying event information. They are bound as properties using square brackets. As callbacks are not events, they do not impact the Angular event cycle, and as such should not change the state of anything.
  • Event Handlers: event handlers are defined as HTML attributes enclosed in normal brackets and are Angular bound functions.
  • API: the grid API and column API are accessible through the component.

All of the above (attributes, properties, callbacks and event handlers) are registered using their 'dash' syntax and not camel-case. For example, the property rowAnimation is bound using row-animation. The following example shows some bindings:

<ag-grid-angular
   #myGrid // assign an angular ID to the grid

   // these are boolean values, which if included without a value, default to true
   // (if they are not specified, the default is false)
   row-animation
   pagination

   // these are attributes, not bound, give explicit values here
   row-selection="multiple"

   // these are bound properties, bound to the AngularJS 1.x current context (that's what a
   // scope is called in Angular 2)
   [column-defs]="columnDefs"
   [show-tool-panel]="showToolPanel"

   // this is a callback
   [is-scroll-lag]="myIsScrollLagFunction"

   // these are registering event callbacks
   (cell-clicked)="onCellClicked($event)"
   (column-resized)="onColumnEvent($event)">
</ag-grid-angular>

The APIs are also accessible through the component. For example, above the ID is given as '#myGrid' which then allows the API to be accessed like this:

<button (click)="myGrid.api.deselectAll()">Clear Selection</button>

Next Steps

That's it, Doc! Now you know how to interface with the grid. Go now and find out about all the great properties, methods, callbacks and events you can use.