Note This description pertains to new external Wijmo core library modules introduced after build 211. This is a recommended way of Wijmo interop for Angular 2 usage. A description based on global Wijmo core library modules can be found here.
Wijmo components for Angular 2 allow you to use Wijmo controls in Angular 2 templates markup. In terms of the TypeScript class inheritance feature, Wijmo Angular 2 components "extend" the control classes they represent. This means that when you acquire a reference to a Wijmo component, the referenced instance is a Wijmo control with all its properties, events and methods, and an Angular 2 component at the same time. A Wijmo component extends a control class and adds the necessary functionality that allows the control to be used in the Angular 2 template markup, with the fully functional one-way and two-way property bindings and event bindings. This integration is smooth, as all the players, Wijmo controls, Wijmo Angular 2 components and Angular 2 itself are written in the same TypeScript language.
Wijmo Angular 2 components are shipped as a set of modules, one module per core library module, with the "angular2" word in their names. For example, "wijmo.angular2.grid.js" module represents components for controls from the core "wijmo.grid.js" module. Module files are located in subfolders of the NpmImages folder of Wijmo download zip. Each subfolder provides modules in a certain module format, like CommonJS or AMD, and is effectively an npm image that can be installed into your application using "npm install <path to subfolder>" command. Refer to the accompanying readme.txt files in these folders for more details.
All Wijmo modules should be imported using their ambient names, which are module names prefixed with "wijmo/", and without ".js" extension. For example, this import statement imports the content of the "wijmo.angular2.grid.js" module:
import * as wjGrid from 'wijmo/wijmo.angular2.grid';
Wijmo is not represented in npm registry. Instead, we ship npm images of Wijmo external modules in the NpmImages folder of Wijmo download zip, where the library can be installed from, using the conventional npm installation means ("npm install <path_to_folder>" command or a record in the "dependencies" option of the application's package.json file).
The NpmImages folder contains subfolders like wijmo-amd-min, wijmo-commonjs-min and wijmo-system-min, which are standalone npm images representing Wijmo modules in different module formats (AMD, CommonJS and System respectively).
A choice of a module format to use depends on the module loader and/or bundler tools that you use in your application. AMD and CommonJS formats will work in most cases.
So, you can install Wijmo into your application using "npm install <path_to_folder>" command in NodeJS command prompt, like this:
npm install ../wijmo_download/NpmImages/wijmo-amd-minThis command will add the folder content to the node_modules/wijmo folder of your application.
Alternatively, you can add the following record to the package.json file of your application:
"dependencies": {
"wijmo": "../wijmo_download/NpmImages/wijmo-amd-min",
… other libraries
}
After that, each time you execute "npm install" command in your application root folder,
Wijmo modules will be installed under the "node_modules" folder along with another libraries
enumerated in package.json.
With this setup, you may import Wijmo Angular 2 modules and use the components and directives they contain. For example, this code adds a WjFlexGrid component to MyCmp component's template, with the flex property containing a reference to the added grid:
import { Component, NgModule, ViewChild } from '@angular/core';
import { WjGridModule, WjFlexGrid } from 'wijmo/wijmo.angular2.grid';
@Component({
template: '<wj-flex-grid #flex [itemsSource]="data"></wj-flex-grid>',
selector: 'my-cmp',
})
export class MyCmp {
data: any[];
@ViewChild('flex') flex: WjFlexGrid;
}
@NgModule({
imports: [WjGridModule, BrowserModule],
declarations: [MyCmp]
})
export class MyModule {
}
Every Wijmo for Angular 2 JavaScript module contains an Angular 2 NgModule that exports all the components in the module. To use any of these components in your NgModule components' templates, you just need to add a reference to Wijmo NgModule to the imports metadata property of your NgModule decorator.
A name of NgModule is constructed from its JavaScript module name using the following schema:
Wj<JS module name without wijmo.angular2 prefix>Module
For example, WjInputModule NgModule for wijmo.angular2.input JavaScript module, or WjGridFilterModule NgModule for wijmo.angular2.grid.filter JavaScript module.
Wijmo components for Angular 2 are intended for a usage in templates markup. If you want to create a Wijmo control in code, you should use a Wijmo control from a core module for this purpose, instead of a component. A core module has the same name as a corresponding Angular 2 interop module, but without the "angular2" word in the name. For example, this code creates a FlexGrid control in code:
import { FlexGrid } from 'wijmo/wijmo.grid';
let flex = new FlexGrid('#host_element');
Note that we import FlexGrid control instead of WjFlexGrid component, and import it from the 'wijmo/wijmo.grid' module instead of 'wijmo/wijmo.angular2.grid'.
Let's consider specifics of adapting Wijmo to most popular module loaders and bundlers.
The only additional step required here is to include Wijmo css (the Dist/styles/wijmo.min.css file from Wijmo download zip) in a bundle. You should copy this file somewhere under the application's root and include it using standard WebPack means that you use for your own application's css:
import 'style!css!../styles/vendor/wijmo.min.css';
The style-loader and css-loader should be added to the "devDependencies" option of your
application's package.json file:
"devDependencies": {
"css-loader": "^0.23.1",
"style-loader": "^0.13.1",
... another libraries
}
You have to map Wijmo ambient module names to Wijmo .js files in the node_modules folder, by adding the following config options that you pass to the System.config method call:
map: {
'wijmo': 'node_modules/wijmo'
},
packages: {
'wijmo': {
defaultExtension: 'js'
}
}
The only additional step required here is to include Wijmo css (the Dist/styles/wijmo.min.css file from Wijmo download zip) in a bundle. You should copy this file somewhere under the application's root and include it using standard Angular CLI means that you use for your own application's css, namely by adding a reference to this file to the application's angular-cli.json file:
"apps": [
{
"styles": ["../styles/vendor/wijmo.min.css"],
}
],
... other options
Refer to the Angular 2 Markup Syntax topic for the description.