Thursday, 9 June 2016

Bootstrap Plugins in XPages Part XIV - Using Node.js, Bower, Git and SourceTree to install Bootstrap Plugins (6) - bower-installer

In the previous blog post we examined the imported files in the XPages application when using Bower to install Packages (Bootstrap Plugins). We noticed that Bower installs entire repositories and not just the files that we need. In this blog post a first introduction to bower-installer for installing Packages in an XPages application. bower-installer is a tool for installing bower dependencies that won't include entire repos. Although Bower works great as a light-weight tool to quickly install browser dependencies, it currently does not provide much functionality for installing specific "built" components for the client. As mentioned before Bower installs entire repositories and that is not what we want!
If bower install is run on a configuration file (bower.json), the entire repository will be pulled down and copied into a specific directory (.bowerrc). This repository is often quite large, when probably only a built js and css file are needed.
In this blog post I will describe the first basic usage of bower-installer and the first steps to get only the files we need in the On-Disk Project and, after sync with the NSF, in the XPages application.

Bootstrap Plugins in XPages
Part I : Bootstrap-select - A jQuery plugin that utilizes Bootstrap's dropdown.js
Part II : Bootstrap FileStyle - Customization of input file for Bootstrap
Part III : Dialog Boxes using Bootbox
Part IV : Awesome Bootstrap Checkbox
Part V : jQuery and JavaScript AMD (Asynchronous Module Definition) Fixes
Part VI : jQuery and JavaScript AMD (Asynchronous Module Definition) Fixes (2)
Part VII : MagicSuggest A Multiple Selection Combobox
Part VIII : Bootstrap Maxlength
Part IX : Using Node.js, Bower, Git and SourceTree to install Bootstrap Plugins (1)
Part X : Using Node.js, Bower, Git and SourceTree to install Bootstrap Plugins (2)
Part XIII - Using Node.js, Bower, Git and SourceTree to install Bootstrap Plugins (5)

Using bower-installer
First, we need to install the bower-installer package. For the installation we use Node and npm to install bower-installer globally. Open the Node command prompt and enter: npm install -g bower-installer. After installing, the simplest way to use bower-installer is to specify the path you would like to use. bower-installer will try to grab the relevant, main, files, but if it can’t because the main files aren’t defined, then there is always a possibility to override with the specific files you want.

Bower.json file
The second step is to create a bower.json file. Bower installer provides an easy way for the main files to be installed or moved to one or more locations. Simply add to the bower.json an install key and path attribute. In the example below I use Select2 as only dependency in the bower.json file (for demonstration purpose only). The bower.json file should look similar to the following example below. Furthermore no .bowerrc file is used in order to prevent that the entire repository will be installed in the On-Disk Project.

{
  "name": "Bower4Xpages",
   "description": "Bower",
  "private": true,
  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
   "test",
    "tests"
  ],
  "install" : {
  "path" : "bowertestodp/webcontent"
  },
  "dependencies": {
  "select2": "latest"
    }
}

Run bower-installer
From the Node command prompt, in the same directory as the bower.json file, enter: bower-installer


After installation, two directories have been created in the SourceControl directory where the On-Disk Project directory is included.
First a new bower_components directory has been created outside the On-Disk Project directory. This directory contains the entire repository of Select2 including a Select2 bower.json file which contains the main files which have been installed in the On-Disk Project directory. 



So based on the bower.json file in the Select2 repository in the bower_components directory ONLY the Select2 main files have been installed in the On-Disk Project in the directory WebContent/Select2 based on the created bower.json file in step 2 (install path).


The Select2 bower.json file includes the following installation information for bower-installer. The files select2.js and core.scss are the main Select2 files in the Select2 bower.json file.

{
  "name": "select2",
  "description": "Select2 is a jQuery based replacement for select boxes. It supports searching, remote   data sets, and     infinite scrolling of results.",
  "main": [
  "dist/js/select2.js",
  "src/scss/core.scss"
  ],
  "repository": {
  "type": "git",
   url": "git@github.com:select2/select2.git"
  },
  "homepage": "https://github.com/ivaynberg/select2",
  "version": "4.0.3",
  "_release": "4.0.3",
   "_resolution": {
   "type": "version",
   "tag": "4.0.3",
   "commit": "566c7846fbf8c3b7674346f26d0ee872c0a77629"
  },
  "_source": "https://github.com/ivaynberg/select2.git",
  "_target": "*",
  "_originalSource": "select2"
}

The final result after sync the On-Disk Project with the NSF in Domino Designer (DDE). Only the main files are installed in the XPages application.


This is a significant step forward and already works a lot better than the standard Bower installation but we still don't have all the files we need to make Select2 work in an XPages application. Problem is also that a lot of registered components (packages) for Bower do not include a bower.json configuration. Therefore, Bower does not know about any "main files" and therefore, by default bower-installer doesn't know about them either. Finally we have a problem with the bower_components directory. This directory is included in the git repository and also in SourceTree and will be synced with the NSF. So for now the bower_components directory should be removed after running bower-installer in Node and before syncing with the NSF. It will be recreated when running bower-installer again in Node.
But there is a solution for these problems. bower-installer can override an existing main file path or provide a non-existant one. In the next blog post a closer look at overriding the main files and installing multiple main files using bower-installer.

No comments:

Post a Comment