Running PrimeNG with SystemJS
PrimeNG (https://www.primefaces.org/primeng) is an open source library of rich UI components for Angular 2+. PrimeNG is derived from PrimeFaces--the most popular JavaServer Faces (JSF) component suite. If you know PrimeFaces, you will feel at home with PrimeNG due to similar API. Currently, PrimeNG has 80+ visually stunning widgets that are easy to use. They are divided into several groups such as input and select components, buttons, data iteration components, panels, overlays, menus, charts, messages, multimedia, drag-and-drop, and miscellaneous. There are also 22+ free and premium themes.
PrimeNG fits perfectly with the mobile and desktop development because it is a responsive and touch optimized framework. PrimeNG showcase is a good place to play with the components, try them in action, study documentation, and code snippets. Anyway, we need a systematic approach for getting started with PrimeNG. This is what this book tries to convey. In this chapter, we will set up and run PrimeNG with SystemJS (https://github.com/systemjs/systemjs)--universal module loader supporting various module formats. SystemJS is a good choice for learning purposes if you want to try TypeScript, Angular, PrimeNG code snippets, or write small applications in Plunker (https://plnkr.co) because it can load your files, transpile them (if needed) and resolve module dependencies on-the-fly. In the real applications, you should choose Webpack or Angular CLI-based setups that have more power and advanced configurations. They also bundle your application in order to reduce the amount of HTTP requests. Those setups will be discussed in the next two sections.
The SystemJS configuration for Angular
First of all, you need to install Node.js and npm, which we already mentioned in the TypeScript fundamentals you need to know section. Why do we need npm? In HTML and SystemJS configuration, we could reference all dependencies from https://unpkg.com. But, we prefer to install all dependencies locally so that IDEs are fine with autocompletion. For instance, to install SystemJS, you have to run the following command in a console of your choice:
npm install systemjs --saveFor readers, we created a complete demo seed project where all dependencies are listed in the package.json file.
Note
The complete seed project with PrimeNG and SystemJS is available on GitHub athttps://github.com/ova2/angular-development-with-primeng/tree/master/chapter1/primeng-systemjs-setup.
All dependencies in the seed project can be installed by running npm install in the project root. If you explore the index.html file, you can see that the SystemJS library is included in the <head> tag. After that, it becomes available as a global System object, which exposes two static methods: System.import() and System.config(). The first method is used to load a module. It accepts one argument--a module name, which can be either a file path or a logical name mapped to the file path. The second method is used for setting configuration. It accepts a configuration object as an argument. Normally, the configuration is placed within the systemjs.config.js file. Complete scripts to be included in index.html are TypeScript compiler, Polyfills, and SystemJS related files. The bootstrapping occurs by executing System.import('app'):
<script src="../node_modules/typescript/lib/typescript.js"></script>
<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/systemjs/dist/system.src.js"></script>
<script src="../systemjs.config.js"></script>
<script>
System.import('app').catch(function (err) {
console.error(err);
});
</script>An excerpt from the configuration object for Angular projects is listed here:
System.config({
transpiler: 'typescript',
typescriptOptions: {
"target": "es5",
"module": "commonjs",
"moduleResolution": "node",
"sourceMap": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true
},
map: {
'@angular/animations':
'node_modules/@angular/animations/bundles/animations.umd.min.js',
'@angular/common':
'node_modules/@angular/common/bundles/common.umd.min.js',
'@angular/compiler':
'node_modules/@angular/compiler/bundles/compiler.umd.min.js',
'@angular/core':
'node_modules/@angular/core/bundles/core.umd.min.js',
'@angular/forms':
'node_modules/@angular/forms/bundles/forms.umd.min.js',
...
'rxjs': 'node_modules/rxjs',
'app': 'src'
},
meta: {
'@angular/*': {'format': 'cjs'}
},
packages: {
'app': {
main: 'main',
defaultExtension: 'ts'
},
'rxjs': {main: 'Rx'}
});A brief explanation gives an overview of the most important configuration options:
- The
transpileroption specifies a transpiler for TypeScript files. Possible values aretypescript,babel, andtraceur. The transpilation happens in browser on-the-fly. - The
typescriptOptionsoption sets the TypeScript compiler options. - The
mapoption creates aliases for module names. When you import a module, the module name is replaced by an associated value according to the mapping. In the configuration, all entry points for Angular files are in UMD format. - The
packagesoption sets meta information for imported modules. For example, you can set the main entry point of the module. Furthermore, you can specify default file extensions to be able to omit them when importing.
Adding PrimeNG dependencies
Every project using PrimeNG needs the locally installed library. You can achieve this by running the following command:
npm install primeng --saveAs a result, PrimeNG is installed in your project root under the node_modules folder as well as added in package.json as a dependency. Here again, you can skip this step if you use the seed project hosted on GitHub--just run npm install. The next step is to add two new entries to the SystemJS configuration file. For shorter import statements, it is recommended to map primeng to node_modules/primeng. PrimeNG components are distributed as CommonJS modules ending with .js. That means we should set the default extension too:
System.config({
...
map: {
...
'primeng': 'node_modules/primeng'
},
packages: {
'primeng': {
defaultExtension: 'js'
},
...
}
});Now, you are able to import PrimeNG modules from primeng/primeng. For instance, write this line to import AccordionModule and MenuItem:
import{AccordionModule, MenuItem} from 'primeng/primeng';
This way of importing is not recommended in production because all other available components will be loaded as well. Instead of that, only import what you need using a specific component path:
import {AccordionModule} from 'primeng/components/accordion/accordion';
import {MenuItem} from 'primeng/components/common/api';In the demo application, we will only use ButtonModule and InputTextModule so that we need to import them as follows:
import {ButtonModule} from 'primeng/components/button/button';
import {InputTextModule} from 'primeng/components/inputtext/inputtext';The demo project we want to create consists of application code and assets. A detailed description of every file would go beyond the scope of this book. We will only show the project structure:
A typically PrimeNG application needs a theme. We would like to take the Bootstrap theme. The file index.html must have three CSS dependencies included within the <head> tag--the theme, the PrimeNG file, and the FontAwesome file for SVG icons (http://fontawesome.io):
<link rel="stylesheet" type="text/css"
href="../node_modules/primeng/resources/themes/bootstrap/theme.css"/>
<link rel="stylesheet" type="text/css"
href="../node_modules/primeng/resources/primeng.min.css"/>
<link rel="stylesheet" type="text/css"
href="src/assets/icons/css/font-awesome.min.css"/>All FontAwesome files were placed under src/assets/icons. Mostly PrimeNG components are native, but there is a list of components with third-party dependencies. These are explained in the following table:
Component | Dependency |
Schedule | FullCalendar and Moment.js |
Editor | Quill editor |
GMap | Google Maps |
Charts | Charts.js |
Captcha | Google Recaptcha |
Exact links to those dependencies will be shown later in concrete examples. For now, we have finished our setup. Let's start our first application by running npm start in the project root.
The application gets launched in browser with two PrimeNG components, as shown in the following screenshot. As you can see, a lot of single web resources (CSS and JS files) are being loaded in the browser:
