Project status: CTP
This project allows you to use DevExtreme Widgets in Angular 2 applications.
You can start either with running examples or with creating a new Angular 2 application.
Node.js and npm are required and essential to Angular 2 development.
Gulp is required to build the project and run tests.
Install the required node packages and run an http server:
npm install
npm start
Navigate to http://127.0.0.1:8875/examples/ in the opened browser window. Explore the examples folder of this repository for the examples source code.
We will use Angular 2 quick-start tutorial as a base project for this guide. Please follow the original tutorial steps to bootstrap the application.
Once the application is ready and works install the devextreme-angular2 npm package as follows:
npm install devextreme-angular2
Modify the references in the index.html file as follows:
<link rel="stylesheet" type="text/css" href="node_modules/devextreme/dist/css/dx.common.css" />
<link rel="stylesheet" type="text/css" href="node_modules/devextreme/dist/css/dx.light.css" />
<script src="node_modules/core-js/client/shim.min.js"></script>
<script src="node_modules/zone.js/dist/zone.js"></script>
<script src="node_modules/reflect-metadata/Reflect.js"></script>
<script src="node_modules/systemjs/dist/system.src.js"></script>
<script src="node_modules/jquery/dist/jquery.min.js"></script>
<script src="node_modules/devextreme/dist/js/dx.all.js"></script>
<script src="systemjs.config.js"></script>Make sure your html document has DOCTYPE specified:
<!DOCTYPE html>
<html>
...Modify the 'systemjs.config.js' file as follows:
var map = {
'app': 'app',
'@angular': 'node_modules/@angular',
'angular2-in-memory-web-api': 'node_modules/angular2-in-memory-web-api',
'rxjs': 'node_modules/rxjs',
'devextreme-angular2': 'node_modules/devextreme-angular2' // <== add this line
};
var packages = {
'app': { main: 'main.js', defaultExtension: 'js' },
'rxjs': { defaultExtension: 'js' },
'angular2-in-memory-web-api': { main: 'index.js', defaultExtension: 'js' },
'devextreme-angular2': { main: 'index.js', defaultExtension: 'js' } // <== add this line
};In the /app/app.component.ts file import the necessary devextreme component:
import { DxButton } from 'devextreme-angular2';Add the imported components as directives to the host component. Now you can use the widget in the component's template.
@Component({
selector: 'my-app',
template: '<dx-button text="Press me" (onClick)="helloWorld()"></dx-button>',
directives: [ DxButton ]
})
export class AppComponent {
helloWorld() {
alert('Hello world!');
}
}Run the application:
npm start
DevExtreme Angular 2 components mirror DevExtreme JavaScript API but use Angular 2 syntax for specifying widget options, subscribing to events and custom templates declaration.
To specify a widget's option statically (the text option of dxButton):
<dx-button text="Simple button"></dx-button>To bind the dxButton’s click event:
<dx-button (onClick)="handler()"></dx-button>If we want changes to the value of ‘bindingProperty’ of the host component to propagate to the value of the dxTextBox widget, a one-way binding approach is used:
<dx-text-box [value]="bindingProperty"></dx-text-box>In addition to the one-way binding, we can also perform two-way binding, which propagates changes from the bindingProperty to the widget or vice versa from the widget to the bindingProperty:
<dx-text-box [(value)]="bindingProperty"></dx-text-box>In case you want to customize the rendering of a DevExtreme widget, we support custom templates. For instance, we can specify the itemTemplate and groupTemplate of the dxList widget as follows:
<dx-list [grouped]="true" [items]="grouppedItems">
<div *dxTemplate="let item = data of 'itemTemplate'">
{{item.someProperty}}
</div>
<div *dxTemplate="let group = data of 'groupTemplate'">
{{group.someProperty}}
</div>
</dx-list>The local 'item' and 'group' variables (that are declared via the 'let' keyword) expose the corresponding item data object. You can use it to render the data where you need inside the template.
The DevExtreme Angular 2 editors support the 'ngModel' binding as well as the 'formControlName' directive, which are necessary for the Angular 2 forms features.
<form [formGroup]="form">
<dx-text-box
name="email"
[(ngModel)]="email"
[isValid]="emailControl.valid || emailControl.pristine"
[validationError]="{ message: 'Email is invalid'}">
</dx-text-box>
</form>@Component({
selector: 'my-app',
templateUrl: "app/app.component.html",
directives: [
DxTextBox,
DxTextBoxValueAccessor,
]
})
export class AppComponent implements OnInit {
email: string;
emailControl: AbstractControl;
form: FormGroup;
ngOnInit() {
this.form = new FormGroup({
email: new FormControl('', Validators.compose([Validators.required, CustomValidator.mailFormat]))
});
this.emailControl = this.form.controls['email'];
}
}You can access a DevExtreme widget instance by using the Angular 2 component query syntax and the component's 'instance' property. In the example below, the refresh method of the dxDataGrid is called:
import { Component, ViewChild } from '@angular/core';
import { DxDataGrid, DxButton } from "devextreme-angular2";
@Component({
selector: 'my-app',
template: `
<dx-data-grid [dataSource]="dataSource"></dx-data-grid>
<dx-button text="Refresh data" (onClick)="refresh()"></dx-button>
`,
directives: [ DxDataGrid, DxButton ]
})
export class AppComponent implements OnChanges {
@ViewChild(DxDataGrid) dataGrid:DxDataGrid
refresh() {
this.dataGrid.instance.refresh();
}
}Familiarize yourself with the DevExtreme Commercial License. Free trial is available!
DevExtreme Angular 2 components are released as a MIT-licensed (free and open-source) add-on to DevExtreme.
- For general Angular 2 topics, follow these guidelines
- For questions regarding DevExtreme libraries and JavaScript API, use DevExpress Support Center
- For DevExtreme Angular 2 integration bugs, questions and suggestions, use the GitHub issue tracker