ag-Grid Angular Overview
Full working examples of ag-Grid and Angular can be found in Github, illustrating
(amongst others) rich grids, filtering with angular components, master/detail grid and so on.
Every feature of ag-Grid is available when using the ag-Grid Angular component. The Angular component wraps the
functionality of ag-Grid, it doesn't duplicate, so there will be no difference between core ag-Grid and
Angular ag-Grid when it comes to features.
Configuring ag-Grid in Angular
You can configure the grid in the following ways through Angular:
- Events: All data out of the grid comes through events. These use
Angular event bindings eg
(modelUpdated)="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 Angular
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
rowHeight="22". Notice that boolean attributes are defaulted
to true IF they attribute is provided WITHOUT any value. If the attribute
is not provided, it is taken as false.
- 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, Angular
automatically passes the new value onto the grid. This is used in
the following locations in the feature rich grid example above:
a) The quick filter 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.
Sometimes the gridReady grid event can fire before the Angular component is ready to receive it, so in
an Angular environment its safer to rely on AfterViewInit instead before using the API.
Providing Angular Components to ag-Grid
In order for ag-Grid to be able to use your Angular components, you need to provide them in the top
level module:
@NgModule({
imports: [
BrowserModule,
FormsModule,
RouterModule.forRoot(appRoutes),
AgGridModule.withComponents(
[
SquareComponent,
CubeComponent,
// ...other components
You can then use these components as editors, renderers or filters. For example, to use an Angular
Component as a
Cell Renderer, you would do the following:
let colDefs = [
{
headerName: "Square Component",
field: "value",
cellRendererFramework: SquareComponent,
editable:true,
colId: "square",
width: 175
},
...other column definitions
]
Please see the relevant sections on cell renderers,
cell editors and
filters
for configuring and using Angular components in ag-Grid.
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-angular #agGrid style="width: 100%; height: 350px;" class="ag-theme-balham"
// items bound to properties on the controller
[gridOptions]="gridOptions"
[columnDefs]="columnDefs"
[showToolPanel]="showToolPanel"
[rowData]="rowData"
// boolean values 'turned on'
animateRows
pagination
// simple values, not bound
rowHeight="22"
rowSelection="multiple"
// event callbacks
(modelUpdated)="onModelUpdated()"
(cellClicked)="onCellClicked($event)"
(cellDoubleClicked)="onCellDoubleClicked($event)">
</ag-grid-angular>
The above is all you need to get started using ag-Grid in a Angular 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.
Child to Parent Communication
There are a variety of ways to manage component communication in Angular (shared service, local variables
etc),
but you
often need a simple way to let a "parent" component know that something has happened on a "child"
component. In
this case
the simplest route is to use the gridOptions.context to hold a reference to the parent,
which the
child can then access.
// in the parent component - the component that hosts ag-grid-angular and specifies which angular components to use in the grid
constructor() {
this.gridOptions = <GridOptions>{
context: {
componentParent: this
}
};
this.gridOptions.rowData = this.createRowData();
this.gridOptions.columnDefs = this.createColumnDefs();
}
// in the child component - the angular components created dynamically in the grid
// the parent component can then be accessed as follows:
this.params.context.componentParent
Note that although we've used componentParent as the property name here it can be anything -
the main point is that you can use the context mechanism to share information between the components.
The "A Simple Example, using CellRenderers created from Angular Components"
above illustrates this in the Child/Parent column:
Building & Bundling
There are many ways to build and/or bundle an Angular Application. In the Getting Started/Overview
section we
went
through using Angular CLI to create an ag-Grid Angular application, but we also provide full working
examples
using
either SystemJS, Webpack or Webpack 2 as part of the ag-grid-angular-example project on
GitHub.
We document the main parts of these tools below, but please refer to the examples for more detail.
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 headerName="Name" field="name" [width]="150"></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
propertyName="String Value"
[propertyName]="'String Value'"
[propertyName]="{{Interpolated Value}}"
[propertyName]="functionCallReturningAString()"
// boolean value
[propertyName]="true|false"
[propertyName]="{{Interpolated Value}}"
[propertyName]="functionCallReturningABoolean()"
// numeric value
[propertyName]="Numeric Value"
[propertyName]="functionCallReturningANumber()"
// function value
[propertyName]="functionName"
[propertyName]="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]="getSkillFilter()"
private getSkillFilter():any {
return SkillFilter;
}
// return an Object for filterParams
[filterParams]="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 headerName="IT Skills">
<ag-grid-column headerName="Skills" [width]="125" [sortable]="false" [cellRenderer]="skillsCellRenderer" [filter]="getSkillFilter()"></ag-grid-column>
<ag-grid-column headerName="Proficiency" field="proficiency" [width]="120" [cellRenderer]="percentCellRenderer" [filter]="getProficiencyFilter()"></ag-grid-column>
</ag-grid-column>
In this example we have a parent Column of "IT Skills", with two child columns.
Example: Rich Grid using Markup
The example below shows the same rich grid as the example above, but with configuration done via Markup.
Cell Rendering & Cell Editing using Angular
It is possible to build
cell renderers,
cell editors and
filters using Angular. Doing each of these
is explained in the section on each.
Although it is possible to use Angular for your customisations of ag-Grid, it is not necessary. The grid
will happily work with both Angular and non-Angular portions (eg cellRenderers in Angular or normal
JavaScript).
Testing ag-Grid Angular Applications with Karma & Jasmine
As with your actual application, you need to ensure you import the AgGridModule when
specifying your tests:
TestBed.configureTestingModule({
imports: [
AgGridModule.withComponents([...optional Angular Components...]
]
...rest of module definition
You also need to aware that the Grid API and ColumnAPI will only be available after your
fixtures detectChanges has been invoked:
it('grid API is not available until `detectChanges`', () => {
expect(component.gridOptions.api).not.toBeTruthy();
});
it('grid API is available after `detectChanges`', () => {
fixture.detectChanges();
expect(component.gridOptions.api).toBeTruthy();
});