fix(prototype): better support for GOV.UK Prototype Kit (#466)

Allow the Pattern Library to automatically be available in the Prototype Kit when installed.

This requires producing a file with jQuery bundled (`all.jquery.min.js`) and an init file
(`init.js`). When loaded into the Prototype Kit they automatically initialise all the components.

Update the documentation to explain that no further steps are necessary.

Fixes #465

docs/get-started/prototyping.md

@@ -14,16 +14,31 @@ This template comes with the MOJ Pattern Library pre-installed so you don't need
 
 ## Manual installation
 
-Alternatively, you can install the GOV.UK Prototype Kit and MOJ Pattern Library manually. You must follow the [GOV.UK Design System prototype setup guide](https://design-system.service.gov.uk/get-started/prototyping/) first. Once you've done that, continue below.
+You can also install the GOV.UK Prototype Kit and MOJ Pattern Library manually. You must follow the [GOV.UK Design System prototype setup guide](https://design-system.service.gov.uk/get-started/prototyping/) first.
 
-### Installing MOJ Frontend
+You then need to install the NPM package for the MOJ Pattern Library:
 
-The MOJ Pattern Library uses MOJ Frontend. To install it, run these steps:
+1. Open a command prompt application (e.g. Terminal on MacOS)
+2. Change the directory to your prototype's directory. For example, `cd path/to/prototype`
+3. Run `npm install @ministryofjustice/frontend --save`
 
-1. open Terminal
-2. change the directory to your prototype. For example, `cd path/to/prototype`
-3. run `npm install @ministryofjustice/frontend --save`
-4. add `window.MOJFrontend.initAll()` to `app/assets/javascripts/application.js` below the line doing the same for `GOVUKFrontend`
+If you're using version 13 or later of the GOV.UK Prototype Kit, the components of the MOJ Pattern Library will now be available to you.
+
+<details class="govuk-details">
+  <summary class="govuk-details__summary">
+    <span class="govuk-details__summary-text">
+      For older versions of the GOV.UK Prototype Kit
+    </span>
+  </summary>
+  <div class="govuk-details__text">
+
+If you're using a version of the GOV.UK Prototype Kit before 13, you need to take additional steps to use the MOJ Pattern Library in your prototype:
+
+1. Open `app/assets/javascripts/application.js`
+2. Add `window.MOJFrontend.initAll()` below the line that does the same for `GOVUKFrontend`
+
+  </div>
+</details>
 
 ## Updating MOJ Frontend
 
@@ -33,9 +48,9 @@ You can check which version your prototype is running by opening `package.json`
 
 To update your prototype to the latest version of MOJ Frontend:
 
-1. open `package.json` in the root folder of your prototype in a text editor
+1. Open `package.json` in the root folder of your prototype in a text editor
 2. Under `dependencies`, update the reference to MOJ Frontend to `"@ministryofjustice/frontend": "{% version %}",`
-3. save `package.json`
-4. open Terminal/command line
-5. change the directory to your prototype's directory. For example, `cd path/to/prototype`
-6. run `npm install`
+3. Save `package.json`
+4. Open a command prompt application (e.g. Terminal on MacOS)
+5. Change the directory to your prototype's directory. For example, `cd path/to/prototype`
+6. Run `npm install`

gulp/build-javascript.js

@@ -1,4 +1,5 @@
 const gulp = require('gulp');
+const uglify = require("gulp-uglify");
 var concat = require('gulp-concat');
 var umd = require('gulp-umd');
 
@@ -20,3 +21,29 @@ gulp.task('build:javascript', () => {
     }))
     .pipe(gulp.dest('package/moj/'));
 });
+
+gulp.task('build:javascript-with-jquery', () => {
+  return gulp.src([
+      'node_modules/jquery/dist/jquery.js',
+      'gulp/jquery/scope.js',
+      'src/moj/namespace.js',
+      'src/moj/helpers.js',
+      'src/moj/all.js',
+      'src/moj/components/**/*.js',
+    ])
+    .pipe(concat('all.jquery.min.js'))
+    .pipe(umd({
+      exports: function() {
+        return 'MOJFrontend';
+      },
+      namespace: function() {
+        return 'MOJFrontend';
+      }
+    }))
+    .pipe(
+      uglify({
+        ie8: true,
+      })
+    )
+    .pipe(gulp.dest('package/moj/'));
+});

gulp/jquery/scope.js

@@ -0,0 +1,2 @@
+// Local-scope jQuery so it doens't overwrite or squat on window properties
+var $ = jQuery.noConflict(true);

gulpfile.js

@@ -1,16 +1,15 @@
 const gulp = require("gulp");
 const requireDir = require("require-dir");
 
-requireDir("./gulp", {
-  recurse: true,
-});
+requireDir("./gulp");
 
 gulp.task(
   "build:package",
   gulp.series(
     "build:clean",
     "build:copy-files",
     "build:javascript",
+    "build:javascript-with-jquery",
     "build:compress-images",
   )
 );

package/README.md

@@ -1,6 +1,10 @@
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
-[![moj-frontend](https://circleci.com/gh/ministryofjustice/moj-frontend.svg?style=shield)](https://circleci.com/gh/ministryofjustice/moj-frontend)
+![NPM License](https://img.shields.io/npm/l/@ministryofjustice/frontend)
+
+![GitHub Workflow Status](https://img.shields.io/github/workflow/status/ministryofjustice/moj-frontend/Build%20and%20deploy%20docs)
+![NPM Downloads](https://img.shields.io/npm/v/@ministryofjustice/frontend)
+![NPM Downloads](https://img.shields.io/npm/dw/@ministryofjustice/frontend)
 
 # Ministry of Justice Frontend
 

package/govuk-prototype-kit.config.json

@@ -3,7 +3,8 @@
     "/moj/filters/prototype-kit-13-filters.js"
   ],
   "scripts": [
-    "/moj/all.js"
+    "/moj/all.jquery.min.js",
+    "/moj/init.js"
   ],
   "assets": [
     "/moj/assets"

src/moj/init.js

@@ -0,0 +1,5 @@
+if (window.GOVUKPrototypeKit && window.GOVUKPrototypeKit.documentReady) {
+  window.GOVUKPrototypeKit.documentReady(function () {
+    window.MOJFrontend.initAll();
+  });
+}