We’ve recently received a barrage of questions regarding Wijmo integration with various module loaders and bundlers (like SystemJS, WebPack, Angular CLI, etc), which is possible, but requires a number of extra steps. We also received a question about Wijmo npm installation, which is tightly coupled with the former.
I’d like to share with you the status of our effort destined to eliminate this complexity.
External modules
The main trouble with settling Wijmo to the aforementioned tools is that the library core (non-Ng2) modules are not "external.” Rather, they’re "global" modules accessible via the global "wijmo" variable. Loaders/bundlers work smoothly only with true (“external”) modules by following the TS/ES6 “import” statements chain in order to load or collect all necessary modules, and require a special setup for global modules.
Because of this, we created true (“external”) versions of Wijmo core library modules that should be consumed using ES6/TS ‘import’ statement. For example, the following code that used Wijmo global module:
@ViewChild('flex1') flex1: wijmo.grid.FlexGrid;
let gr = new wijmo.grid.GroupRow();
looks like here with external modules:
import * as wjcGrid from 'wijmo/wijmo.grid';
@ViewChild('flex1') flex1: wjcGrid.FlexGrid;
let gr = new wjcGrid.GroupRow();
Being true modules, they can be placed to the node_modules/wijmo folder and consumed by various loaders/bundlers in a natural way, with minimal tunings, or without tuning at all.
Npm images
The Wijmo download zip now includes the NpmImages folder with wijmo-amd, wijmo-commonjs and wijmo-system subfolders containing Wijmo external modules in different module formats (AMD, CommonJS and System respectively).
An important point here: each of these subfolder is effectively an npm image that can be installed by a command like this:
npm install <some_path>/NpmImages/wijmo-amd
The command above will install Wijmo AMD modules in the node_modules/wijmo folder of the directory from which the command was issued.
Usage examples
All Wijmo Angular 2 samples are reworked to use these new modules, and have the following record in their package.json files:
"dependencies": {
"wijmo": "../../../../../NpmImages/wijmo-amd",
… another modules (Ng2 etc)
}
So, it’s just enough to run “npm install” in the project folder to install both Ng2 and Wijmo libraries. The only Wijmo file which is added to projects manually is wijmo.css, which is reasonable. The only downside: if you move a sample to another location, you have to update a path to wijmo npm image in package.json.
In addition, we plan to publish .tgz files with npm images on our site and reference them in the samples using this remote location.
With this approach, projects can be freely moved to other locations without breaking the references to Wijmo npm image. Right now this is only available for evaluation versions. We’re considering whether we can apply such an approach to licensed versions, too.
WebPack
Here’s the Angular 2 CellTemplateIntro sample adapted for usage with WebPack: http://publicfiles.componentone.com/Wijmo%205%20Files/Angular2/CellTemplateIntro_Ng2_WP.zip
The only Wijmo-specific setting here is the
import '../styles/vendor/wijmo.min.css';
statement in the src/vendor.ts file that includes wijmo.css to a bundle.
You need to perform the following steps to build and run it.
Step 1: Unzip.
It has two root folders: CellTemplateIntro, which contains the sample itself, and wijmo_zip_image, which emulates Wijmo dowload zip image, but contains only the stuff necessary for this demonstration (namely wijmo-amd npm image).
Note that the sample doesn't contain any Wijmo library file—neither .js nor .d.ts. The only exception is wijmo.min.css in the styles\vendor folder. Because .css always requires a special treatment, this is not a wijmo-specific issue.
Step 2: Run NodeJS command prompt.
Step 3: cd to the CellTemplateIntro\CellTemplateIntro folder.
Step 4: Run "npm install"
This installs all the necessary libraries to node_modules, including the wijmo folder retrieved from the aforementioned wijmo_zip_image\NpmImages\wijmo-amd folder. The folder contains all wijmo library modules, both Ng2 interop and core (both wijmo.angular2.grid and wijmo.grid). And for each module it contains both .min.js and .d.ts files.
Step 5: Run "npm run build"
This runs the WebPack that creates an app bundle in the dist folder.
Step 6: Open wpbundle.html page in a browser.
This file loads the bundle created on the previous step and should be hosted in some web server. If you use Visual Studio, then the simplest way to run it is to open the sample solution, set wpbundle.html as a default page, and run the project.
Angular CLI
Some remarks about Angular CLI: Wijmo can be integrated there in the same simple way as to WebPack as explained above. But the trouble here is that Wijmo-minified files has a min.js extension, while module names don’t naturally include “min” in their names.
In all the loader/bundler tools, this problem—that of mapping module names to files with “min.js” extension—can be resolved by means of trivial settings, but we didn’t find any way to achieve this in Angular CLI.
At the same time, we think (OK, still think!) that adding the “min” suffix to minified file names is the right way to go, so we suppose that this is a temporary limitation that will be resolved in Angular CLI in the near future. For the time being, you need to rename “.min.js” to just “.js” before installing them to your project.
True NPM Registry
Right now, we don’t provide a possibility to perform “npm install” using “wijmo” npm registry because we have the following problem: We have two types of Wijmo builds: evaluation (with Wijmo
MESCIUS inc.