Implementing the AngularJS Datagrid

When using AngularJS, you have the choice of using the bundled version of ag-Grid or the CommonJS version.

When the ag-Grid script loads, it does not register with AngularJS. This is because AngularJS is an optional part of ag-Grid and you need to tell ag-Grid you want to use it.

Pull in the ag-Grid Dependencies

You'll need to ensure you refer to the ag-grid library correctly - this can be done in a number of ways, but but you'll need to ensure you refer to either the ag-grid or the ag-grid-enterprise dependency, depending on which feature set you're using (i.e. if you're using any Enterprise features you'll need ag-grid-enterprise)

As an example we'll use NPM to manage our dependencies, and then refer to the dependencies in our HTML file:

Using ag-Grid
// package.json
"dependencies": {
    "ag-grid": "8.0.x",
}

// index.html
<html>
<head>
    <script src="node_modules/ag-grid/dist/ag-grid.js"></script>
    <script src="<your script>.js"></script>
</head>
Using ag-Grid-Enterprise
// package.json
"dependencies": {
    "ag-grid-enterprise": "8.0.x",
}

// index.html
<html>
<head>
    <script src="node_modules/ag-grid-enterprise/dist/ag-grid-enterprise.js"></script>
    <script src="<your script>.js"></script>
</head>

In either of the above examples we're using the full JS dependency which includes styles & themes - you can optionally chose to use the version without styles included (.noStyle.js). If you do this, you'll need to refer to the styles & themes separately, as below:

// index.html
<html>
<head>
    <script src="node_modules/ag-grid/dist/ag-grid.js"></script>
    <script src="node_modules/ag-grid/dist/styles/ag-grid.css"></script>
    <script src="node_modules/ag-grid/dist/styles/theme-fresh.css"></script>
    <script src="<your script>.js"></script>
</head>

Creating the AngularJS Module

Include ag-Grid as a dependency of your module like this:

// if you're using ag-Grid-Enterprise, you'll need to provide the License Key before doing anything else
// not necessary if you're just using ag-Grid
agGrid.LicenseManager.setLicenseKey("your license key goes here");

// get ag-Grid to create an Angular module and register the ag-Grid directive
agGrid.initialiseAgGridWithAngular1(angular);

// create your module with ag-Grid as a dependency
var module = angular.module("example", ["agGrid"]);

ag-Grid Div

To include a grid in your html, add the ag-grid attribute to a div. The value of the div should be the provided grid options on the scope.

It is also usual to provide a styling theme to the grid. Three themes come with the grid, ag-fresh, ag-dark and ag-blue. Each one is set by applying the corresponding class of the same name to the div. In the example, ag-fresh is used.

You must provide width and height to your grid. The grid is programmed to fill the width and height you give it.

<div ag-grid="gridOptions" class="ag-fresh" style="height: 100%;"></div>

(note: a div by default has 100% width, so the width is not specified explicitly above).

Grid Options

The grid options provide ag-Grid with the details needed to render. At a minimum you should provide the columns (columnDefs) and the rows (rowData).

Basic AngularJS 1.x Example

Advanced AngularJS 1.x Example

The below example has much more details. The mechanism for setting up the grid is the same as above. Don't worry about the finer details for now, how all the different options are configured is explained in the relevant parts of the documentation.

Angular Compiling

Angular 1.x is great. It allows us to build large end-to-end single page web apps with relative ease. However the author of ag-Grid is of the opinion that not everything should be built in Angular. Angular 1.x does come with a disadvantage, it can slow things down. ag-Grid does not use Angular 1.x (or any other framework) underneath the hood, it is all blazing fast raw Javascript.

But maybe you are not worried about performance. Maybe you are not displaying that many rows and columns. And maybe you want to provide your own cell renderers and use Angular here. For whatever reason, it is possible to turn Angular on for Angular version 1.x.

When Angular is turned on in ag-Grid, every time a row is inserted, a new child Angular Scope is created for that row. This scope gets the row attached to it so it's available to any Angular logic inside the cell.

Each cell within the row does not get a new child scope. So if placing item inside the child scope for the row, be aware that it is shared across all cells for that row. If you want a cell to have it's own private scope, consider using a directive for the renderer that will introduce a new scope.

Turn On Angular Compile

Angular compiling is turned on by setting the grid options attribute angularCompileRows to true.

  • angularCompileRows: Whether to compile the rows for Angular.
  • angularCompileFilters: Whether to compile provided custom filters.
  • angularCompileHeaders: Whether to compile the customer headers for AngularJS.

The default is always to have Angular compiling off for performance reasons.

Example using Angular Compile

Below then uses three columns rendered using custom Angular renderers.

  • Athlete: Uses simple binding to display text.
  • Age: Uses simple binding to display a button, with a button click event using ng-click.
  • Country: Uses a custom Angular directive to display the country.
When scrolling the example above up and down, the cells rendered using Angular are blank initially, and filled in during the next Angular digest cycle. This behaviour the author has observed in other Angular grid implementations. This is another reason why the author prefers non-Angular rendering for large grids.

Cell Templates

Cell Templates allow you to specify templates to use to render your cells. This is handy if you want to put JavaScript markup with AngularJS bindings as the cells. Cell templates are specified in the column definition by providing a template as a string or a templateUrl to load the template from the server.

If using templateUrl, then the html is cached. The server is only hit once per template and it is reused.

The example below uses cell templates for the first three columns.

  • Col 1 - The first column uses a static template. Pretty pointless as you can't change the content between rows.
  • Col 2 - The second column uses an inline template. AngularJS is then used to fetch the content from the scope via ng-bind.
  • Col 3 - The third column is similar to the second, with the difference that it loads the template from the server.

In the example, as you scroll up and down, the redraw on the AngularJS columns has a lag. This is waiting for the AngularJS digest cycle to kick in to populate the values into these rows.

Destroy

You do not need to manually clean up the grid. The grid ties in with the AngularJS 1 lifecycle and releases all resources when the directive is destroyed.

Next Steps...

Now you can go to interfacing to learn about accessing all the features of the grid.