Aurelia Datagrid

This page shows you how to get started with ag-Grid and Aurelia.

Download ag-Grid

NPM
npm install ag-grid-community
npm install ag-grid-aurelia
Github
Download ag-grid-community from Github
Download ag-grid-aurelia from Github

Download ag-Grid-Enterprise

NPM install ag-Grid NPM
npm install ag-grid-enterprise 		Github install ag-Grid Github
Download from Github

Referencing ag-Grid-Enterprise

In your application, before instantiating the grid, you need to reference the included ag-grid-enterprise dependency:

import {GridOptions} from "ag-grid-community"; import "ag-grid-enterprise";

If you are building an Aurelia application then you have the choice between A) using the plain JavaScript version of ag-Grid or B) using the ag-Grid Aurelia Component from the ag-grid-aurelia project. If you use the ag-Grid Aurelia Component, then the grid's properties, events and API will all tie in with the Aurelia ecosystem - this will make your Aurelia coding easier.

Please use the github project ag-grid-aurelia for feedback or issue reporting around ag-Grid's support for Aurelia.

ag-Grid Aurelia Features

Every feature of ag-Grid is available when using the ag-Grid Aurelia Component. The Aurelia Component wraps the functionality of ag-Grid, it doesn't duplicate, so there will be no difference between core ag-Grid and Aurelia ag-Grid when it comes to features.

Aurelia Full Example

This page goes through the ag-grid-aurelia-example on Github.

The example project includes a number of separate grids with each section demonstrating a different feature set:

  • A feature rich grid example, demonstrating many of ag-Grid's features using Aurelia as a wrapper
  • An example using markup to create a grid
  • A Cell Editor Example - one with a popup editor, and another with a numeric editor. Each demonstrates different editor related features
  • A Filter Example

Once you have the ag-Grid dependencies installed, you will then be able to access ag-Grid classes and components inside your application:

import {GridOptions, GridApi, ColumnApi} from "ag-grid-community";

You will need to include the CSS for ag-Grid, either directly inside your html page, or as part of creating your bundle if bundling. Teh following shows referencing the css from your web page:

<link href="node_modules/ag-grid-community/styles/ag-grid.css" rel="stylesheet" /> <link href="node_modules/ag-grid-community/styles/ag-theme-balham.css" rel="stylesheet" />

You will also need to configure Aurelia (aurelia_project/aurelia.json) to use ag-grid and ag-grid-aurelia as follows:

{ "name": "vendor-bundle.js", "prepend": [ "node_modules/bluebird/js/browser/bluebird.core.js", "scripts/require.js" ], "dependencies": [ "aurelia-binding", "aurelia-bootstrapper", ...other dependencies... { "name": "ag-grid-community", "path": "../node_modules/ag-grid-community", "main": "main" }, { "name": "ag-grid-aurelia", "path": "../../ag-grid-aurelia", "main": "main" } ] }

All the above items are specific to Aurelia and is intended to point you in the right direction. If you need more information on this, please see the Aurelia documentation.

Configuring ag-Grid in Aurelia

You can configure the grid in the following ways through Aurelia:

  • Events: All data out of the grid comes through events. These use Aurelia event bindings eg model-updated.call="onModelUpdated()". As you interact with the grid, the different events are fixed and output text to the console (open the dev tools to see the console).
  • Properties: All the data is provided to the grid as Aurelia bindings. These are bound onto the ag-Grid properties bypassing the elements attributes. The values for the bindings come from the parent controller.
  • Attributes: When the property is just a simple string value, then no binding is necessary, just the value is placed as an attribute eg row-height.bind="22".
  • Grid API via IDs: The grid in the example is created with an id by marking it with #agGrid. This in turn turns into a variable which can be used to access the grid's controller. The buttons Grid API and Column API buttons use this variable to access the grids API (the APIs are attributes on the controller).
  • Changing Properties: When a property changes value, Aurelia automatically passes the new value onto the grid. This is used in the following locations:
    a) The 'quickFilter' on the top right updates the quick filter of the grid. b) The 'Show Tool Panel' checkbox has its value bound to the 'showToolPanel' property of the grid. c) The 'Refresh Data' generates new data for the grid and updates the rowData property.

Notice that the grid has its properties marked as immutable. Hence for object properties, the object reference must change for the grid to take impact. For example, rowData must be a new list of data for the grid to be informed to redraw.

The example has ag-Grid configured through the template in the following ways:

// notice the grid has an id called agGrid, which can be used to call the API <ag-grid-aurelia #agGrid class="ag-theme-balham" // items bound to properties on the controller grid-options.bind="gridOptions" column-defs.bind="columnDefs" show-tool-panel.bind="showToolPanel" row-data.bind="rowData" // boolean values 'turned on' enable-col-resize enable-sorting enable-filter group-headers suppress-row-click-selection tool-panel-suppress-groups tool-panel-suppress-values debug // simple values row-height.bind="22" row-selection="multiple" // event callbacks model-updated.call="onModelUpdated()" cell-clicked.call="onCellClicked($event)" cell-double-clicked.call="onCellDoubleClicked($event)" cell-context-menu.call="onCellContextMenu($event)" cell-value-changed.call="onCellValueChanged($event)" cell-focused.call="onCellFocused($event)" row-selected.call="onRowSelected($event)" selection-changed.call="onSelectionChanged()" before-filter-changed.call="onBeforeFilterChanged()" after-filter-changed.call="onAfterFilterChanged()" filter-modified.call="onFilterModified()" before-sort-changed.call="onBeforeSortChanged()" after-sort-changed.call="onAfterSortChanged()" virtual-row-removed.call="onVirtualRowRemoved($event)" row-clicked.call="onRowClicked($event)" ready.call="onReady($event)" column-everything-changed.call="onColumnEvent($event)" column-row-group-changed.call="onColumnEvent($event)" column-value-changed.call="onColumnEvent($event)" column-moved.call="onColumnEvent($event)" column-visible.call="onColumnEvent($event)" column-group-opened.call="onColumnEvent($event)" column-resized.call="onColumnEvent($event)" column-pinned-count-changed.call="onColumnEvent($event)"> </ag-grid-aurelia>

The above is all you need to get started using ag-Grid in a Aurelia application. Now would be a good time to try it in a simple app and get some data displaying and practice with some of the grid settings before moving onto the advanced features of cellRendering and custom filtering.

Creating Grids with Markup

You can create Grids either programatically (with pure JavaScript/Typescript/Components), or declare them via declaratively with markup.

The above section details how to specify the Grid itself. To declare columns you can specify them as follows:

Column Definition

<ag-grid-column header-name="Name" field="name" width.bind="150" pinned.bind="true"> </ag-grid-column>

This example declares a simple Column Definition, specifying header name, field and width.

Setting Column Properties

There are some simple rules you should follow when setting column properties via Markup:

// string value property-name="String Value" property-name="'String Value'" property-name="${Interpolated Value}" // boolean value property-name.bind="true|false" property-name.bind="{{Interpolated Value}}" property-name.bind="functionCallReturningABoolean()" // numeric value property-name="Numeric Value" property-name.bind="functionCallReturningANumber()" // function value property-name.bind="functionName" property-name.bind="functionCallReturningAFunction()"

Setting a Class or a Complex Value:

You can set a Class or a Complex property in the following way:

// return a Class definition for a Filter filter.bind="getSkillFilter()" private getSkillFilter():any { return SkillFilter; } // return an Object for filterParams filter-params.bind.bind="getCountryFilterParams()" private getCountryFilterParams():any { return { cellRenderer: this.countryCellRenderer, cellHeight: 20 } }

Grouped Column Definition

To specify a Grouped Column, you can nest a column defintion:

<ag-grid-column header-name="IT Skills"> <ag-grid-column header-name="Skills" width.bind="125" suppress-sorting.bind="true" cell-renderer.bind="skillsCellRenderer" filter.bind="getSkillFilter()"> </ag-grid-column> <ag-grid-column header-name="Proficiency" field="proficiency" width.bind="120" cell-renderer.bind="percentCellRenderer" filter.bind="getProficiencyFilter()"> </ag-grid-column> </ag-grid-column>

In this example we have a parent Column of "IT Skills", with two child columns.

Cell Rendering & Cell Editing using Aurelia

It is possible to build cell renderers, cell editors and filters using Aurelia. Doing each of these is explained in the section on each.

Although it is possible to use Aurelia for your customisations of ag-Grid, it is not necessary. The grid will happily work with both Aurelia and non-Aurelia portions (eg cellRenderers in Aurelia or normal JavaScript).

If you do use Aurelia, be aware that you are adding an extra layer of indirection into ag-Grid. ag-Grid's internal framework is already highly tuned to work incredibly fast and does not require Aurelia or anything else to make it faster.

If you are looking for a lightning fast grid, even if you are using Aurelia and the ag-grid-aurelia component, consider using plain ag-Grid Components (as explained on the pages for rendering etc) inside ag-Grid instead of creating Aurelia counterparts.

Next Steps...

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