Add tools for integrating 3rd party libraries

Make two new commands for adding and deleting 3rd party libraries. - npm run ng-add-3rd-party - npm run ng-delete-3rd-party Update README.md to explain the steps needed.

Author: toni-rmc

README.md

@@ -24,7 +24,7 @@ Than install JavaScript dependencies with **npm**.
 npm install
 ```
 
-Initialize Agular and compile and publish code with these two commands. 
+Initialize Angular and compile and publish code with these two commands. 
 
 ```
 npm run ng-init
@@ -121,7 +121,8 @@ In that case you don't have to delete `public/Ng` directory, running this comman
 * **`npm run ng-compile-prod`** - *same as the above but produces minified HTML and CSS files, also compiled JS files from the TS, are minified. 
 Note that original JS files in your `angular_apps` directory (the ones that were not TS) will not be minified by this command. That is because I can't find decent,stable and reliable Gulp plugin that supports minifing ES6, if you know of one let me know.* 
 
-* **`npm run ng-bootstrap`** - *this command is combination of `npm run ng-init` and `npm run ng-compile`, that is it installs Angular and compiles your apps in one go.* 
+* **`npm run ng-bootstrap`** - *this command is combination of `npm run ng-init`, `npm run ng-add-3rd-party` and `npm run ng-compile`, it installs Angular, installs 3rd party libraries and compiles your apps in one go. 
+It is useful when you join existing project. Whith just this command you can build working application on your machine and start working on it.* 
 
 * **`npm run ng-watch`** - *starts watch mode, starts browser and puts your browser in sync, actually all the browsers tabs that have wached URL open. 
 When you change, add, move, delete or rename HTML, JS, CSS and TS files in `angular_apps` it will distribute them in real time to `public`. TS files will be compiled to JS first than distributed. 
@@ -151,6 +152,37 @@ So if you have, for example, two files in `public/somedir`:*
  *First file `public/somedir/apples.js` would be deleted, second one `public/somedir/oranges.js` would be left. 
  Empty directories in distribution (`public`) directory and all nested empty directories will also be deleted if there is any.* 
 
+* **`npm run ng-add-3rd-party`** - *sometimes you have to use third-party libraries in your project. `npm run ng-init` initializes Angular and other standard libraries like `rxjs` but what if you need other libraries as well in your project? 
+Best way to explain is by example, so let's say you want to use a third-party library in your project e.g. **angular2-multiselect-dropdown**. 
+First install it of course using `npm install angular2-multiselect-dropdown --save`. 
+Than open `resources/assets/js/ng-vendor.js` and add library name to the return array of the `vendor_libraries` callback* 
+
+ ```JavaScript
+ exports.vendor_libraries = function() {
+ return [
+ 'angular2-multiselect-dropdown',
+ ];
+ }
+ ```
+
+ *After that run this command `npm run ng-add-3rd-party`. 
+Next step is to tell SystemJS where from to load new library. Open `angular_apps/config/<app_name>.config.js` and as a last entry in `map` object add this mapping:* 
+
+ ```JavaScript
+ map: {
+ ...
+ // other libraries
+ ...
+ 'angular2-multiselect-dropdown/angular2-multiselect-dropdown': 'npm:angular2-multiselect-dropdown/angular2-multiselect-dropdown.umd.js'
+ },
+ ```
+
+ *Last step is to run `npm run ng-compile`. 
+Than you can use external library in your application. 
+File `ng-vendor.js` is located outside of the Angular build directory (`angular_apps`), because it does not need to be published to distribution directory (`public`).* 
+
+* **`npm run ng-delete-3rd-party`** - *opposite of `npm run ng-add-3rd-party`. It will only remove 3rd party libraries from `public/Ng`, it does not remove them from `node_modules`.* 
+
 * **`npm run ng-remove-empty-dirs`** - *removes empty directories and all empty sub-directories from both buld (`angular_apps`) directory and distribution (`public`) directory. 
 Unlike `npm run ng-clean`, it does touch `angular_apps` directory and only removes empty directories, thats all it does. 
 You can pass `--build` switch to only remove empty directories and sub-directories from `angular_apps` directory or `--dist` switch to remove them only from `public` directory.* 
@@ -200,6 +232,8 @@ So for example, **not** ~~`php -S localhost:8080`~~, but `php -S 127.0.0.1:8080`
 
 Details on how you integrate your own Angular app from start to finish: 
 
+> Directory in which this new app will be is gonna be called `NewApp`, in production you should use more descriptive name of what your app does e.g. `Store` or `StockManagement`. That way if you have more Angular applications you can see right away what each one is designated to do soon as you look into `angular-apps` directory. 
+
 If you already haven't done so trough composer or manually, run these commands. 
 
 ```

angular_apps/config/app2.config.js

@@ -31,7 +31,8 @@
 
  // other libraries
  'rxjs': 'npm:rxjs',
- 'angular-in-memory-web-api': 'npm:angular-in-memory-web-api/bundles/in-memory-web-api.umd.js'
+ 'angular-in-memory-web-api': 'npm:angular-in-memory-web-api/bundles/in-memory-web-api.umd.js',
+ // 'angular2-multiselect-dropdown/angular2-multiselect-dropdown': 'npm:angular2-multiselect-dropdown/angular2-multiselect-dropdown.umd.js'
  },
  // packages tells the System loader how to load when no filename and/or no extension
  packages: {

gulpfile.js

@@ -41,8 +41,14 @@ gulp.task('compile', ['publish'], actions.compileTS());
 // Initialize entire Angular environment.
 gulp.task('initNg', actions.initializeAngular());
 
-// Initialize Angular environment and compile and distribute Angular apps.
-gulp.task('bootstrapNg', ['initNg', 'compile']);
+// Publish 3rd party packages Angular applications will use.
+gulp.task('publish-packages', actions.publishPackages());
+
+// Delete published 3rd party packages from Angular directory.
+gulp.task('delete-packages', actions.deletePackages());
+
+// Initialize Angular environment, publish packages and compile and distribute Angular apps.
+gulp.task('bootstrapNg', ['initNg', 'publish-packages', 'compile']);
 
 // Assembles files and directories to be cleaned from distribution directory.
 gulp.task('assemble-for-clean', actions.assembleForCleaning());
@@ -472,6 +478,49 @@ function Actions()
  }
  };
 
+ /**
+ * Create function that publishes 3rd party libraries Angular apps may need.
+ * Read libraries from array and copy them from "node_modules" to the Angular directory.
+ *
+ * @access public
+ * @return function
+ */
+ this.publishPackages = function ()
+ {
+ var angular_directory = angular_dir;
+
+ const external = require('./resources/assets/js/ng-vendor');
+ let e = external.vendor_libraries();
+
+ let _3rd_party_libs = e.map(function (el) {return 'node_modules/' + el + '/**/*'; });
+
+ return function ()
+ {
+ return gulp.src(
+ _3rd_party_libs, { "base" : "node_modules" }).pipe(gulp.dest(angular_directory));
+ }
+ };
+
+ /**
+ * Create function that deletes 3rd party libraries.
+ * Read libraries from array and delete them from the Angular directory.
+ *
+ * @access public
+ * @return function
+ */
+ this.deletePackages = function ()
+ {
+ const external = require('./resources/assets/js/ng-vendor');
+ let e = external.vendor_libraries();
+
+ let _3rd_party_libs = e.map(function (el) {return angular_dir + '/' + el + '/**'; });
+
+ return function ()
+ {
+ return del.sync(_3rd_party_libs);
+ }
+ };
+
  /**
  * Create function that removes empty directories from
  * build and distribution directories.

package.json

@@ -16,7 +16,9 @@
  "ng-watch": "gulp watch --sync",
  "ng-watch-nosync": "gulp watch",
  "ng-clean": "gulp clean",
-"ng-remove-empty-dirs": "gulp remove-empty-dirs"
+ "ng-remove-empty-dirs": "gulp remove-empty-dirs",
+ "ng-add-3rd-party": "gulp publish-packages",
+ "ng-delete-3rd-party": "gulp delete-packages"
  },
  "dependencies": {
  "@angular/animations": "~4.3.1",

resources/assets/js/ng-vendor.js

@@ -0,0 +1,36 @@
+/*
+ |--------------------------------------------------------------------------
+ | External Angular Libraries
+ |--------------------------------------------------------------------------
+ |
+ | This file is where you may define all of your external Angular libraries.
+ |
+ | Follow these steps to get your external library working:
+ |
+ | - install library with "npm install <package_name> --save"
+ | - put library name in the array bellow
+ | - run "npm run ng-add-3rd-party" command
+ |
+ | After steps above tell SystemJS where from to load new library.
+ | Open "angular_apps/config/<app_name>.config.js" and add new mapping at the end of the "map" property object.
+ | For example entry for 'angular2-multiselect-dropdown' library would be:
+ |
+ | map :{
+ | ...
+ | 'angular2-multiselect-dropdown/angular2-multiselect-dropdown': 'npm:angular2-multiselect-dropdown/angular2-multiselect-dropdown.umd.js'
+ | },
+ |
+ | than run "npm run ng-compile" command.
+ | Now you can use external library in your Angular app.
+ */
+
+exports.vendor_libraries = function() {
+ return [
+ // Add names of the 3rd party packages here that you want your Angular app to have access to.
+ // If for example you have used "npm install angular2-multiselect-dropdown --save" command, add the
+ // package name in this array like in the example bellow.
+
+ // 'angular2-multiselect-dropdown',
+
+ ];
+}