Documentation

Angular UI Components for jQWidgets

Angular is a development platform for building mobile and desktop web applications. It provides a way to build apps for any deployment target by reusing existing code. Using HTML as the template language, Angular offers developers the possiblity to create their own components.


Prerequisites

  • Node.js - to verify that you have it installed, run the command node -v in cmd. It will output the current version.

Note: Make sure that you are running on the latest Node.js and npm versions.

Steps:

  1. Create your project folder structure
  2. Configurate and install all required packages
  3. Build the app

Step 1 - Create your root project folder

The root folder contains a few configuration files and the app folder which holds the main content of the application.


 /root
    /app
        /index.html
        /src
            /app.component.ts
            /app.module.ts
            /main.ts
        /assets
    /package.json
    /tsconfig.json
    /tsconfig.aot.json
    /webpack.config.js

Note: Structure may vary based on your application needs.

Step 2 - Install and configurate all required packages

Apart from the package.json and tsconfig.json you will need tsconfig.aot.json and webpack.config.js files.
The tsconfig.aot.json is a normal tsconfig.json file, but with AoT-oriented settings.
Let's take a look at the config files:


package.json

 {
    "name": "angular_jqwidgets_aot_webpack",
    "description": "Angular AOT (Ahead Of Time) Compilation With Webpack",
    "version": "1.0.0",
    "scripts": {
        "ngc": "ngc -p ./tsconfig.aot.json",
        "watch": "npm-watch",
        "webpack": "webpack --config webpack.config.js --optimize-minimize",
        "start": "npm run ngc && npm run webpack"
    },
    "watch": {
        "start": {
            "extensions": "ts,css,htm",
            "patterns": [
                "./app"
            ],
            "quiet": true
        }
    },
    "dependencies": {
        "angular2-template-loader": "0.6.2",
        "awesome-typescript-loader": "3.1.3",
        "core-js": "2.4.1",
        "css-loader": "0.28.4",
        "img-loader": "^2.0.0",
        "raw-loader": "0.5.1",
        "style-loader": "0.18.2",
        "rxjs": "5.4.0",
        "typescript": "2.3.4",
        "webpack": "2.6.1",
        "zone.js": "0.8.11"
    },
    "devDependencies": {
        "@angular/common": "4.1.3",
        "@angular/compiler": "4.1.3",
        "@angular/compiler-cli": "4.1.3",
        "@angular/core": "4.1.3",
        "@angular/forms": "4.1.3",
        "@angular/http": "4.1.3",
        "@angular/platform-browser": "4.1.3",
        "@angular/platform-browser-dynamic": "4.1.3",
        "@angular/platform-server": "4.1.3",
        "@ngtools/webpack": "1.4.0",
        "@types/core-js": "0.9.41",
        "@types/jquery": "2.0.46",
        "@types/node": "7.0.28"
    }
}
  • ngc compiles our .ts files to .js. It is a drop-in replacement for tsc.
  • webpack gets the transpiled .js files and bundles them to a single .js file.

When we type npm start in our CLI it executes both the commands. We just need to include the bundled file in or HTML and run it.

Here we have also added a watch command, which executes start on every save we make in a .ts/.css/htm file.


tsconfig.json

{
    "compileOnSave": false,
    "buildOnSave": false,
    "compilerOptions": {
        "target": "es5",
        "module": "es2015",
        "moduleResolution": "node",
        "removeComments": true,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "sourceMap": true,
        "typeRoots": [ "./node_modules/@types" ],
        "types": [
            "core-js",
            "node",
            "jquery"
        ],
        "lib": [ "dom", "es2015" ]
    },
    "exclude": [
        "node_modules",
        "aot",
        "temp"
    ]
}

tsconfig.aot.json

{
    "compilerOptions": {
        "target": "es2015",
        "module": "es2015",
        "moduleResolution": "node",
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "suppressImplicitAnyIndexErrors": true,
        "outDir": "temp",
        "typeRoots": [ "./node_modules/@types" ],
        "types": [
            "node",
            "jquery"
        ]
    },
    "angularCompilerOptions": {
        "skipMetadataEmit": true,
        "genDir": "temp"
    },
    "exclude": [
        "node_modules",
        "aot",
        "temp"
    ]
}

What's really new is the ngc section called angularCompilerOptions. Here we say to the compiler to skip generating metadata files. We have also set genDir which means all of our recompiled files will go in that folder. For more information about AOT please refer to the official Ahead-Of-Time Compilation CookBook.


webpack.config.js

'use strict';
let path = require('path');
let webpack = require('webpack');
 
module.exports = 
{
    entry: 
    {
        main: './app/src/main.ts'
    },
 
    output: 
    {
        path: path.resolve(__dirname + '/aot'),
        filename: '[name].bundle.js'
    },
 
    module: 
    {
        loaders:
        [
            {
                test: /\.ts$/,
                loaders: ['awesome-typescript-loader', 'angular2-template-loader?keepUrl=true'],
                exclude: [/\.(spec|e2e)\.ts$/]
            },
            {
                test: /\.html$/,
                use: 'raw-loader'
            },
            {
                test: /\.css$/,
                loaders: ['style-loader', 'css-loader']
            },
            {
                test: /\.(jpe?g|png|gif|svg)$/i,
                use: [
                    'raw-loader',
                    'img-loader'
                ]
            }
        ]
    },
 
    plugins: 
    [
        new webpack.ProgressPlugin(),
        new webpack.ContextReplacementPlugin(
            /angular(\\|\/)core(\\|\/)@angular/,
            path.join(process.cwd(), 'app')
        )
    ],
 
    resolve: 
    {
        extensions: ['.ts', '.js']
    }
};

For more information about Webpack please refer to the official guide.

Step 3 - Build the app

I. index.html

Add the needed references and the <app-root></app-root> tag to the body of index.html. That's the tag where we initialize the main component.
Then import the bundled file we received after running the npm start command. 

<!DOCTYPE html>
<html>
    <head>
        <title>Angular BarGauge</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
 
        <!-- Styles -->
        <link rel="stylesheet" href="./assets/jqwidgets/styles/jqx.base.css" type="text/css" />
 
        <!-- jQWidgets -->
        <script src="./assets/jqwidgets/jqxcore.js"></script>
        <script src="./assets/jqwidgets/jqxdraw.js"></script>
        <script src="./assets/jqwidgets/jqxbargauge.js"></script>
 
        <!-- Angular -->
        <script src="../node_modules/core-js/client/shim.min.js"></script>
        <script src="../node_modules/zone.js/dist/zone.min.js"></script>
        <script src="../node_modules/zone.js/dist/long-stack-trace-zone.min.js"></script>
 
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-2FX5PV9DNT"></script><script>window.dataLayer = window.dataLayer || [];function gtag(){dataLayer.push(arguments);}gtag('js', new Date());gtag('config', 'G-2FX5PV9DNT');</script></head>
 
    <!-- Display the application -->
    <body>
 
        <app-root>Loading...</app-root>
 
        <script src="./aot/main.bundle.js"></script>
 
    </body>
 
</html>

II. app.module.ts

import { NgModule }       from '@angular/core';
import { BrowserModule }  from '@angular/platform-browser';
 
import { AppComponent }         from './app.component';
import { jqxBarGaugeComponent } from '../assets/jqwidgets-ts/angular_jqxbargauge';
 
@NgModule({
    imports: [BrowserModule],
    declarations: [AppComponent, jqxBarGaugeComponent],
    bootstrap: [AppComponent]
})
 
export class AppModule { }

III. main.ts

IV. app.component.ts

Imports:

@Component decorator:

The Class:

In the above example we create the widget through attributes.
There is another way through method called createComponent. It takes just one argument - an object containing the settings for the widget.

Events Methods & Properties

I. Events

Event Names in the Angular Components are the same as the Event Names in the Javascript Widgets.
The only thing you need to do is to put "on" before the Javascript widget event name and upperCase it's first letter.


II. Methods & Properties


Every widget also have a method setOptions which accepts an object as an argument. This object contains widget settings.

Two Way Data Binding

We often want to both display a data property and update that property when the user makes changes.
Let's take a look at the following example:

IV. app.component.ts

Important:

If you are using any of the Input based widgets like jqxInput, jqxComplexInput, jqxDateTimeInput and so on you must import the FormsModule in your app.module.ts file and add it to the @NgModel imports: