Merge branch 'GPII-2380'

* GPII-2380: GPII-2153: Replaced express-handlebars with our own view engine component. Added initial GitLab CI configuration GPII-2380: Updated to "root safe dedupe" versions of infusion and kettle, including in dependencies. GPII-2380: Updated `gpii-express` dependency to pick up "root safe dedupe" version of kettle. NOJIRA: Update to forward-facing version for next release. GPII-2380: Updated documentation regarding running tests in Vagrant. GPII-2380: Updated to "root safe dedupe" version of infusion, and converted Vagrant tests to use Windows VM. GPII-2361: Updated dependencies to address security vulnerabilities detected by snyk.io, and added auto-patching for dependencies that cannot be upgraded.
fluid-project · May 4, 2017 · 2c867b8 · 2c867b8
2 parents c4088e3 + 33dc87b
commit 2c867b8
Show file tree

Hide file tree

Showing 13 changed files with 552 additions and 466 deletions.
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -0,0 +1,43 @@
+# The standard configuration file to run our Vagrant tests in QI
+#
+# See https://github.com/avtar/qi-development-environments
+---
+# Cache directories such as 'node_modules' in between stages.
+cache:
+  key: "$CI_BUILD_REF_NAME"
+  untracked: true
+  paths:
+    - node_modules/
+
+# Run the following stages sequentially.
+stages:
+  - vagrant_up
+  - vagrant_tests
+  - vagrant_destroy
+
+# Move the '.vagrant' directory to a location so that it won't be removed by the CI runner when it
+# cleans the workspace.
+before_script:
+  - "mkdir -p ../.vagrant-$CI_BUILD_REF_NAME"
+  - rm -fr .vagrant
+  - "ln -s ../.vagrant-$CI_BUILD_REF_NAME .vagrant"
+
+# "when: always" ensures the 'vagrant up' (and later 'vagrant destroy -f') command is run always,
+# so failures in other stages won't interfere with the execution of these critical stages.
+vagrant_up:
+  stage: vagrant_up
+  script:
+    - vagrant up
+  when: always
+
+vagrant_tests:
+  stage: vagrant_tests
+  script:
+    - vagrant ci test
+
+vagrant_destroy:
+  stage: vagrant_destroy
+  script:
+    - vagrant destroy -f
+    - "rm -fr ../.vagrant-$CI_BUILD_REF_NAME"
+  when: always
diff --git a/.qi.yml b/.qi.yml
diff --git a/.vagrant.yml b/.vagrant.yml
@@ -0,0 +1,34 @@
+# QI Configuration file, see: https://github.com/amatas/vagrant-gpii-ci
+---
+
+env:
+  vms:
+    windows10:
+      cpu: 2                   # number of cpus
+      memory: 2048             # amount of RAM memory (in Mb)
+      clone: true              # use the linked_clone Vagrant feature
+      autostart: true
+      box: inclusivedesign/windows10-eval-x64-Apps
+
+stages:                # Stages to perform when 'ci test' command is invoked
+  - setup              # Install our system-level dependencies, etc.
+  - mount              # Mount our network share as a top-level drive.
+  - test               # Run the actual tests
+
+setup_job:
+  stage: setup
+  script:
+    - choco install nodejs.install --version 6.9.1 --forcex86 -y
+    - choco install chromedriver -y
+    - do.ps1 -c "npm install -g node-inspector"
+
+mount_job:
+  stage: mount
+  script:
+    - "net use v: \\\\vboxsrv\\vagrant  /yes"
+    - "do.ps1 -c 'net use v: \\\\VBOXSVR\\vagrant /yes'"
+
+test_job:
+  stage: test          # name of the stage
+  script:              # One line per command to execute
+    - "do.ps1 -c 'v: && npm install && npm test'"
diff --git a/README.md b/README.md
@@ -6,9 +6,8 @@ This package provides components to assist in rendering handlebars templates bot
 
 ## Handlebars Middleware
 
-This package provides middleware that adds Handlebars rendering support to a `gpii.express` instance.  For more details,
-see the [handlebars middleware documentation](docs/handlebars.md).
-
+This package provides a custom view engine that adds Handlebars rendering support to a `gpii.express` instance.
+For more details, see the [handlebars view engine documentation](docs/handlebars.md).
 
 ## Dispatcher Middleware
 
@@ -46,7 +45,25 @@ For more details on the `initBlock` helper,  see [its documentation](docs/initBl
 
 # Testing This Module
 
-Building and testing this module should be as simple as running the following commands in order:
+## In a Virtual Machine
+
+The preferred way to run the tests is to create a virtual machine and run the tests in that supported and
+pre-configured environment.  To run the tests in a virtual machine, you will need to have VirtualBox, Vagrant, and the
+Vagrant CI Plugin installed.  See the [QI development environment requirements](https://github.com/GPII/qi-development-environments/#requirements) for more details.
+
+Once you have satisfied the requirements, you can run the tests using the following commands from the root of the
+repository:
+
+1. `vagrant up`
+2. `vagrant ci test`
+
+If you would like to remove the VM, use the command `vagrant destroy` from the root of the repository.
+
+## On a Local Machine
+
+In order to run the tests locally, you must have [Chrome](https://www.google.com/chrome/) and
+[ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/) installed.  You should then be able to run the
+following commands in order:
 
 1. `npm install`
 2. `npm test`
diff --git a/Vagrantfile b/Vagrantfile
diff --git a/docs/handlebars.md b/docs/handlebars.md
@@ -1,14 +1,10 @@
 # `gpii.express.hb`
 
-Middleware that adds [Handlebars](http://handlebarsjs.com/) rendering support to a `gpii.express` instance.  It is a
-wrapper around [`express-handlebars`](https://github.com/ericf/express-handlebars).  Like that package, it provides a
-renderer that can be used with the Express `Response` object.  That renderer expects to start with a layout, and to
-replace the `{{body}}` variable in that layout with the contents of a template (`foo.handlebars` in our example).
-Templates can reference other templates called "partials", using notation like `{{>partial}}` or `{{>partial variable}}`.
-These references are replaced with the context of the partial, rendered using either a supplied variable or the current
-context.
+This component adds [Handlebars](http://handlebarsjs.com/) rendering support to a `gpii.express` instance. As with
+any [custom Express view engine](http://expressjs.com/en/advanced/developing-template-engines.html), this component
+provides a renderer that can be used with the Express `Response` object's [`render` method](http://expressjs.com/en/4x/api.html#res.render).
 
-To add this to your `gpii.express` instance, you would use options like the following:
+This component is meant to be a direct child of a `gpii.express` instance, as shown here:
 
 ```
 fluid.defaults("my.grade.name", {
@@ -35,18 +31,5 @@ my.grade.name();
 | `templateDirs` | `Array | String` | A list of template directories that contain handlebars layouts, pages, and partials.  These can either be full paths or (better) paths relative to a particular package, as in `%gpii-handlebars/src/templates`. |
 
 To use this middleware, you need to make it aware of one or more directories that contain templates (typically via the
-`options.config.express.views` option in your `gpii.express` configuration.  Each of these view directories can have the
-following subdirectories:
-
-1. `layouts`
-2. `pages`
-3. `partials`
-
-The handlebars middleware supports inheritance between multiple view directories.  Layouts, pages and partials will be
-rendered from the first matching view directory.
-
-# Adding block helpers
-
-Child components of this grade that extend the [`gpii.express.helper`](helper.md) grade are made available as block
-helpers that can be used when rendering content.  By default, this grade includes all of the helpers provided by this
-package.  See the [helpers documentation](helpers.md) for details.
+`options.config.express.views` option in your `gpii.express` configuration.  These options are passed to the underlying
+[renderer component](standaloneRenderer.md), see those docs for details.
diff --git a/docs/standaloneRenderer.md b/docs/standaloneRenderer.md
@@ -1,20 +1,74 @@
 # `gpii.handlebars.standaloneRenderer`
 
-A standalone handlebars renderer designed for use outside of express, for example when rendering mail templates.
+The core renderer designed both for use as [an Express view engine](http://expressjs.com/en/advanced/developing-template-engines.html),
+and in node contexts outside of Express, for example, when rendering mail templates.
 
-Although this does not itself require express, it can work with any helper functions that extend the
-`gpii.express.helper` grade, but which do not themselves require express.  All of the helpers included with this
-package will work with the standalone renderer.
+# Component Options
 
-The directory conventions used with express are partially supported, as follows:
+| Option                | Type             | Description |
+| --------------------- | ---------------- | ----------- |
+| `defaultLayout`       | `String`         | The layout to use when none is specified (see the `renderWithLayout` invoker below).  Defaults to `main`. |
+| `handlebarsExtension` | `String`         | The extension used for all our templates.  Defaults to `handlebars`. |
+| `templateDirs`        | `Array | String` | A list of template directories that contain handlebars layouts, pages, and partials.  These can either be full paths or (better) paths relative to a particular package, as in `%gpii-handlebars/src/templates`.   Please note, if multiple directories contain layouts, pages, or partials with the same name, the right-most directory takes precedence. |
 
-1. Any templates in the `partials` subdirectory relative to `options.templateDirs` will be registered as partials for use in `{{>partial}}` statements.
-2. All other templates are expected to be stored in a `pages` subdirectory relative to `options.templateDirs`.
+## Template Directory Layout
 
-The most important configuration option is `options.templateDirs`, which can either be a string or an array of strings
-representing the location of one or more template directories.  As with the `gpii.express` `views` option, the
-string values will usually be unresolved references to a directory within a package, as in:
+When Express provided its own view engines, it followed a particular convention that we also honor.  Within each directory
+specified in `options.templateDirs` (see above), there is expected to be one or more of the following subdirectories:
 
-`%package-name/path/within/package`
+1. `pages`: Contains "pages", which represent the "body" of a document when used with `renderWithLayout`, or the entire document when used with `render`.  See below for details.
+2. `layouts`: Contains "layouts", templates that generate the markup surrounding the "body".  Used with `renderWithLayout`.
+3. `partials`: Contains "[partials](http://handlebarsjs.com/partials.html)", templates that can be used within "pages" or "layouts" using notation like `{{>my-partial-name}}`.
 
-Note that the package must have registered its content directory using a call like `fluid.module.registerModule("package-name", path)`.
+# Component Invokers
+
+## `{that}.render(templateName, context)`
+* `templateName {String}` A full path to the template to use, or a "key", which is the filename (minus extension) relative to the "pages" subdirectory in one of the view directories specified in `options.templateDirs` (see above).
+* `context {Object}` The "context" to expose to handlebars when rendering content.  See below.
+* Returns: Nothing.
+
+This function renders the variable content specified in `context` using the given `templateKey`.  Let's assume we have
+a very simple template called `myPageTemplate.handlebars`, stored in the "pages" subdirectory of one of our `templateDirs`:
+
+```
+From that point on, she was known simply as the woman with no {{name}}.
+```
+
+Let's assume that we call the renderer using a code snippet like the following:
+
+```
+var renderedContent = renderer.render("myPageTemplate", { name: "Patience" });
+// "From that point on, she was known simply as the woman with no Patience."
+```
+
+For more details about partials, iterative and conditional blocks, see the [Handlebars documentation](http://handlebarsjs.com/).
+
+## `{that}.renderWithLayout(templateName, context)`
+
+* `templateName {String}` See above.
+* `context {Object}` See above for general details, and see below for details about passing layout hints as part of the context.
+* Returns: Nothing.
+
+A long-running convention of early versions of Express and various view engines is to provide a separate "layout"
+template, and to render an individual "page" as the "body" of the "layout".  This function provides comparable support.
+
+Continuing the above example, let's assume we have a `main.handlebars` layout stored in one of our `templateDirs`, which
+looks like this:
+
+ ```
+ <html><head><title>The Story of {{name}}</title><body>{{body}}</body></html>
+ ```
+
+Calling `renderer.renderWithLayout("myPageTemplate", { name: "Patience"})` will generate a simple HTML document whose
+body is the same as the previous output.  As suggested in the example, our implementation allows the same context
+variables passed to the page to be used in the layout as well.
+
+The layout defaults to `options.defaultLayout`, you can change this on the fly by passing a layout key as part of your
+`context`, as in `renderer.renderWithLayout("myPageTemplate", { name: "Patience",  layout: "otherLayout"})`
+
+# Adding block helpers
+
+Child components of this grade that extend the [`gpii.handlebars.helper`](helper.md) grade are made available as block
+helpers that can be used when rendering content.  By default, this grade includes all of the helpers provided by this
+package, with the exception of the `initBlock` helper used within the view engine..  See the
+[helpers documentation](helpers.md) for details.
diff --git a/package.json b/package.json
@@ -1,35 +1,36 @@
 {
   "name": "gpii-handlebars",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "license": "BSD-3-Clause",
   "repository": "https://github.com/GPII/gpii-handlebars",
   "scripts": {
+    "pretest": "node node_modules/rimraf/bin.js coverage/* reports/*",
     "test": "node node_modules/istanbul/lib/cli.js cover tests/all-tests.js"
   },
   "dependencies": {
-    "express-handlebars": "1.2.2",
-    "gpii-binder": "1.0.0-dev.20170127T144054Z.54a5ef2",
-    "gpii-express": "1.0.2",
+    "gpii-binder": "1.0.2",
+    "gpii-express": "1.0.7",
     "handlebars": "4.0.6",
-    "infusion": "3.0.0-dev.20170127T130413Z.103de6e",
+    "infusion": "3.0.0-dev.20170322T234120Z.278de35",
     "marked": "0.3.6",
     "pagedown": "1.1.0",
     "underscore-node": "0.1.2"
   },
   "devDependencies": {
-    "eslint": "3.15.0",
+    "eslint": "3.19.0",
     "eslint-config-fluid": "1.1.0",
     "fluid-grunt-eslint": "18.1.2",
-    "foundation-sites": "6.3.0",
-    "gpii-webdriver": "1.0.0-dev.20170127T135806Z.aa30519",
+    "foundation-sites": "6.3.1",
+    "gpii-webdriver": "1.0.1",
     "grunt": "1.0.1",
     "grunt-jsonlint": "1.1.0",
     "istanbul": "0.4.5",
-    "jsdom": "9.10.0",
-    "kettle": "1.3.2",
+    "jsdom": "9.12.0",
+    "kettle": "1.5.0",
     "node-jqunit": "1.1.4",
-    "request": "2.79.0",
+    "request": "2.81.0",
+    "rimraf": "2.6.1",
     "tough-cookie": "2.3.2"
   }
 }