Interfacing Overview

The interface to ag-Grid is modelled around Web Components. This gives ag-Grid a consistent feel to already existing DOM elements (nice for everyone). It also has the added benefit of fitting nicely into AngularJS 2.

Each interaction with the grid can be broken down into the following categories:

• Properties: Properties are for changing the state inside the grid. These are analogous to properties on a DOM object.
• Events: Events are for handling changes from the grid. These are analogous to events in the DOM.
• Callbacks: Functions that you provide that the grid calls, as a way of modifying behaviour of the grid. This is the grid asking the application a question such as 'what color should this cell be', it is not a means to pass state into or out of the grid.
• API: API into the grid, to provide features that are not representable via properties and events.

Even if you do not use AngularJS 2 or Web Components, the model above is good for understanding the interface, as it helps towards it been self documenting and predictable.

Grid Options

The gridOptions 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, however if you are using AngularJS 2 or Web Components, you can achieve what grid options provides you with in other ways.

The example below shows the different type of items on the gridOptions.

var gridOptions = {
    // PROPERTIES - object properties, myRowData and myColDefs are created somewhere in your application
    rowData: myRowData,
    colDef: myColDefs,

    // PROPERTIES - simple boolean / string / number properties
    enableColResize: true,
    groupHeaders: false,
    rowHeight: 22,
    rowSelection: 'single',

    // EVENTS - add event callback handlers
    onRowClicked: function(event) { console.log('a row was clicked'); },
    onColumnResized: function(event) { console.log('a column was resized'); },
    onReady: function(event) { console.log('the grid is now ready'); },

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

Once the grid is initialised, then the gridOptions will also have available the grid's api and columnApi as follows:

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

// get the grid to space out it's columns
gridOptions.columnApi.sizeColumnsToFit();

Two Ways of Event Binding

In addition to adding event listeners directly onto the gridOptions, 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, which again aligns with how DOM elements work. The first is to put an onXXX() method (where XXX = the event name) like in the example above, the second is to register for the event like in the following example:

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

// add the handler function
gridOptions.api.addEventListener('rowClicked', myRowClickedHandler);

Default Boolean Properties

Where the property is a boolean (true or false), then false (or leave blank) is the default value. For this reason, on / off items are presented in such was as the most common usage (which will be the default) is false, eg suppressCellSelection is worded as such as most people will want cell selection to be turned on.

Native Javascript and AngularJS 1.x

If you are using plain Javascript or AngularJS 1.x, then all of your interaction with ag-Grid will be through the gridOptions.

AngularJS 2

The gridOptions are fully available as stated above for AngularJS 2. However you can take advantage of AngularJS 2's properties and events provided by ag-Grids AngularJS 2's 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 AngularJS 2 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 AngularJS 2 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 AngularJS 2 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 camelcase. For example, the property enableSorting is bound using enable-sorting. enable-sorting. The following example shows some bindings:

<ag-grid-ng2
    // give an AngularJS ID to the grid
    #myGrid

    // these are boolean values, which if included without a value, default to true
    // (which is different to leaving them out, in which case the default is false)
    enable-sorting
    enable-filter

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

    // these are bound properties, bound to the AngularJS current context (that's what a
    // scope is called in Angular JS 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-ng2>

The API's are accessible through the component. This is useful in two situations. The first us by using an AngularJS 2 ID. In the example above, the ID is given as '#myGrid' which then allows something like this:

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

Web Components

The gridOptions are fully available as stated above for Web Components. However you can take advantage of Web Components attributes for setting properties and also directly accessing the Web Components DOM object for interacting with the component. This is done as follows:

• Attributes: Attributes are defined as normal HTML attributes and set non-bound values.
• Properties: Properties are set directly onto the DOM object using javascript.
• Callbacks: Callbacks, like properties, are also set directly on the DOM object using javascript.
• Event Handlers: Event handlers are registered as normal DOM event handlers, using either addEventListener(eventName, handler) or assigning an onXXX method on the DOM object.
• API: The grid API and column API are accessible through the DOM object.

Bindings are registered using their 'dash' syntax and not camelcase. For example, the property enableSorting is bound using enable-sorting.

Properties and callbacks are set using standard camelcase, no changes are done.

Web Components Events are all done using lowercase. This keeps the event handling consistent with native DOM elements, however breaks away from the camel case of how events are managed by the other frameworks ag-Grid supports.

This example shows setting up as a Web Component in HTML. Notice it's simliar to AngularJS 2, however no binding of properties or event handling.

<ag-grid-ng2
    // normal id for CSS selector inside Javascript
    id="myGrid"

    // these are boolean values, which if included without a value, default to Yes
    enable-sorting
    enable-filter

    // these are attributes, not bound, give explicit values here
    row-height="22"
    row-selection="multiple"
</ag-grid-ng2>

Then the callbacks and event handling are done in the Javascript as follows:

var myGrid = document.querySelector('#myGrid');
// calling a method directly on the ag-Grid DOM element.
// calling setGridOptions starts up the grid and is mandatory (even if gridOptions is empty)
myGrid.setGridOptions(gridOptions);

// add events to grid option 1 - add an event listener
myGrid.addEventListener('columnresized', function(event) {
    console.log('got an event via option 1');
});

// add events to grid option 2 - callback on the element
myGrid.oncolumnresized = function(event) {
    console.log('got an event via option 2');
};

// add events to grid option 3 - callback on the grid options
// remember we can still use everything in gridOptions, the
// Web Components features are all in addition
gridOptions.onColumnResized = function(event) {
    console.log('got an event via option 3');
};

// call something on the API
myGrid.api.refreshView();
myGrid.columnApi.sizeColumnsToFit();

// change a property
myGrid.quickFilterText = 'sandy';
myGrid.showToolPanel = true;

Next Steps...

And that's it Doc, now you know how to interface with the grid. Go now and find out about all the great attributes, properties, callbacks and events you can use. Interact well. Be safe. Don't do drugs.