Angular 2 UI and Visualization Components Based on DevExtreme Widgets

This project allows you to use DevExtreme Widgets in Angular 2 applications.

Getting started
Usage samples
Demos
API reference
Bundle size optimization
Server-side rendering
License
Support & feedback

Getting Started

You have the following options to start:

Play around with our Plunker without installing anything
Add DevExtreme to your existing Angular 2 application
Creating a new Angular 2 application and install DevExtreme
Run the local examples

Prerequisites

Node.js and npm are required and essential to Angular 2 development.

Gulp is required to build the project and run tests.

Adding DevExteme to an Existing Angular 2 Application

Install DevExtreme

Install the devextreme and devextreme-angular npm packages:

npm install --save devextreme devextreme-angular

Additional Configuration

The further configuration steps depend on which build tool, bundler or module loader you are using. Please choose the one you need:

Import DevExtreme Modules

Go to your main .ts file (usually src/app.module.ts) and import the required modules to your app:

...
import { DxButtonModule } from 'devextreme-angular'; 
 
@NgModule({ 
    ... 
    imports: [ 
        ... 
        DxButtonModule, 
        ... 
    ] 
})
export class AppModule {}

Note, you can import the DevExtremeModule module to include all the DevExtreme components at once, but it might affect the final bundle size and startup time. Check the bundle optimization section for more info.

Use DevExtreme Components

Now you can use a DevExteme component in your application:

@Component({
    selector: 'my-app',
    template: '<dx-button text="Press me" (onClick)="helloWorld()"></dx-button>'
})
export class AppComponent {
    helloWorld() {
        alert('Hello world!');
    }
}

Create a new Angular 2 Application

Depending on your requirements you can choose one of the following ways to start:

Running the Local Examples

# clone our repo
# --depth 1 removes all but one .git commit history
git clone --depth 1 https://github.com/DevExpress/devextreme-angular.git

# change directory to our repo
cd devextreme-angular

# install the repo with npm
npm install

# start the web-server
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.

Usage Samples

Static String Option Value

To specify a string widget's option statically (the text option of dxButton):

<dx-button text="Simple button"></dx-button>

Static Non-string Option Value

To specify a non-string widget's option statically (the disabled option of dxButton):

<dx-button [disabled]="false"></dx-button>

Event Handling

To bind the dxButton’s click event:

<dx-button (onClick)="handler()"></dx-button>

One-way Option Binding

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>

Two-way Option Binding

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>

Custom Templates

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 itemData of 'item'">
        {{itemData.someProperty}}
    </div>
    <div *dxTemplate="let groupData of 'group'">
        {{groupData.someProperty}}
    </div>
</dx-list>

The local 'itemData' and 'groupData' 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 'item' and 'group' names are default template names for the 'itemTemplate' and 'groupTemplate' options of the dxList widget.

Components with Transcluded Content

In addition to using dxTemplate, it is possible to put the content of the following widgets directly into the markup: DxResizable, DxScrollView, DxValidationGroup. For instance, we can set the content for the DxScrollView widget as shown below:

<dx-scroll-view>
    <div>Some scrollable content</div>
</dx-scroll-view>

Angular 2 Forms

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'
})
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'];
   }
}

Using DevExtreme Validation Features

You can use the built-in validators, validation summary and other DevExtreme validation features with Angular 2 DevExtreme editors.

<dx-validation-group>

    <dx-text-box [(value)]="email">
        <dx-validator [validationRules]="validationRules.email"></dx-validator>
    </dx-text-box>
    <dx-text-box [(value)]="password" mode="password">
        <dx-validator [validationRules]="validationRules.password"></dx-validator>
    </dx-text-box>

    <dx-validation-summary></dx-validation-summary>

    <dx-button (onClick)="validate($event)" text="Submit"></dx-button>

</dx-validation-group>

@Component({
    selector: 'my-app',
    templateUrl: 'app/app.component.html'
})
export class AppComponent {
    email: string;
    password: string;
    validationRules = {
        email: [
            { type: 'required', message: 'Email is required.' },
            { type: 'email', message: 'Email is invalid.' }
        ],
        password: [
            { type: 'required', message: 'Email is required.' }
        ]
    };
    validate(params) {
        let result = params.validationGroup.validate();
        if (result.isValid) {
            // form data is valid
            // params.validationGroup.reset();
        }
    }
}

Configuration Components

You can use dxo- ('o' is a contraction of 'option') prefixed components to configure complex nested options for widgets. The following example demonstrates how to configure the tooltip option of the TreeMap widget:

<dx-tree-map [dataSource]="treeData">
    <dxo-tooltip [enabled]="showTooltip" format="thousands"></dxo-tooltip>
</dx-tree-map>

<dx-button text="Toggle tooltip" (onClick)="toggleTooltip()"></dx-button>

@Component({
    selector: 'my-app',
    templateUrl: 'app/app.component.html'
})
export class AppComponent {
    treeData = ...;
    showTooltip = false;
    toggleTooltip() {
        this.showTooltip = !this.showTooltip;
    }
}

You can also use dxi- ('i' is a contraction of 'item') prefixed components to configure complex collection options for widgets. The following example demonstrates how to configure the columns option of the DataGrid widget:

<dx-data-grid [dataSource]="data">
    <dxi-column dataField="firstName" caption="First Name"></dxi-column>
    <dxi-column dataField="lastName" caption="Last Name" [visible]="showLastName"></dxi-column>
</dx-data-grid>

<dx-button text="Toggle the 'Last Name' column" (onClick)="toggleLastName()"></dx-button>

@Component({
    selector: 'my-app',
    templateUrl: 'app/app.component.html'
})
export class AppComponent {
    data = ...;
    showLastName = false;
    toggleLastName() {
        this.showLastName = !this.showLastName;
    }
}

To configure options that can accept a configuration object or an array of configuration objects, use dxi- prefixed components. The following example demonstrates how to configure the valueAxis option of the Chart widget:

<dx-chart [dataSource]="data">
    <dxi-series valueField="value" argumentField="argument"></dxi-series>
    <dxi-value-axis>
        <dxo-label format="millions"></dxo-label>
    </dxi-value-axis>
</dx-chart>

@Component({
    selector: 'my-app',
    templateUrl: 'app/app.component.html'
})
export class AppComponent {
    data = ...;
}

It is possible to specify an item template inside the dxi- prefixed components and use Angular structural directives such as ngFor. Note that the available item properties are described in the Default Item Template section of a corresponding widget documentation reference.

<dx-list>
    <dxi-item>
        <h1>Items available</h1>
    </dxi-item>
    <dxi-item *ngFor="let item of listItems" [badge]="item.badge">
        <h2>{{item.text}}</h2>
    </dxi-item>
</dx-list>

@Component({
    selector: 'my-app',
    templateUrl: 'app/app.component.html'
})
export class AppComponent {
    listItems = [
        {
            text: 'Cars',
            badge: '12'
        },
        {
            text: 'Bikes',
            badge: '5'
        }
    ];
}

Angular has a built-in template directive. To define the template property of the configuration component (for example, dxo-master-detail), use the following code:

<dxo-master-detail [template]="'masterDetail'"></dxo-master-detail>

Accessing a DevExtreme Widget Instance

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 { DxDataGridComponent } from "devextreme-angular";

@Component({
    selector: 'my-app',
    template: `
        <dx-data-grid [dataSource]="dataSource"></dx-data-grid>
        <dx-button text="Refresh data" (onClick)="refresh()"></dx-button>
    `
})
export class AppComponent implements OnChanges {
    @ViewChild(DxDataGridComponent) dataGrid:DxDataGridComponent
    refresh() {
        this.dataGrid.instance.refresh();
    }
}

Demos

API Reference

DevExtreme Angular 2 components mirror DevExtreme JavaScript API but use Angular 2 syntax for specifying widget options, subscribing to events and custom templates declaration.

Bundle Size Optimization

Bundlers with Tree Shaking Support

Tree shaking can greatly reduce the downloaded size of the application by removing unused portions of both source and library code. There are a number of bundlers with tree shaking support, such as Webpack 2, Rollup, SystemJS Bundler, etc. Due to specifics of the tree shaking algorithm, your project typescript sources should be prepared accordingly to make tree shaking available. This preparations are performed by the Angular Compiler. You can follow one of the existing guides to configure tree shaking with your bundler (Webpack 2, Angular CLI, Rollup).

To make it work with DevExtreme Angular 2 package, you just need to import only the modules required in your application, not the whole DevExtremeModule. For instance, you can import only DxButtonModule as follows:

import { DxButtonModule } from 'devextreme-angular';

Note, AOT Compilation also decreases a bundle size by precompiling your HTML templates. So, the markup and the template compiler are not included into the final bundle.

Bundlers without Tree Shaking Support

If you are not going to configure tree shaking, you can optimize your bundle size by using imports from specific modules, not from the main 'devextreme-angular' module. You can do this as follows:

import { DxButtonModule } from 'devextreme-angular/ui/button';

Server-side Rendering

Currently, DevExtreme components do not support server side rendering (check this issue). So, you are required to switch this feature off.

License

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.

Support & Feedback

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

adrian-d-hidalgo / devextreme-angular Goto Github PK

devextreme-angular's Introduction