docs: document jQuery requirement (#187)

As noted in #134, moj-frontend requires JavaScript but never mentions this in documentation. This change updates documentation to clarify that jQuery must be installed and included. Also moves the "Installing via NPM" and "Supporting IE8" into the main application
ministryofjustice · Jun 26, 2021 · d7f456c · d7f456c
1 parent bb3e0c1
commit d7f456c
Show file tree

Hide file tree

Showing 5 changed files with 54 additions and 102 deletions.
diff --git a/docs/installation/installing-with-npm.md → docs/get-started/installing-with-npm.md b/docs/installation/installing-with-npm.md → docs/get-started/installing-with-npm.md
@@ -1,4 +1,7 @@
-# Installing MOJ Frontend with NPM
+---
+layout: layouts/get-started.njk
+title: Installing MOJ Frontend with NPM
+---
 
 ## Requirements
 
@@ -10,7 +13,13 @@ To use MOJ Frontend with NPM you must:
 
 2. Create a [package.json file](https://docs.npmjs.com/files/package.json) if you don’t already have one. You can create a default `package.json` file by running `npm init` from the root of your application.
 
-3. If you want to use the MOJ Frontend Nunjucks macros, install Nunjucks - the minimum version required is 3.0.0.
+3. Install [jQuery](https://jquery.com/), which is required by the MOJ Frontend JavaScript
+
+```
+npm install jquery --save
+```
+
+1. If you want to use the MOJ Frontend Nunjucks macros, install Nunjucks - the minimum version required is 3.0.0.
 
 ```
 npm install nunjucks --save
@@ -83,6 +92,7 @@ For example, if your project uses [express.js](https://expressjs.com/), below is
 ```JS
 app.use('/assets', express.static(path.join(__dirname, '/node_modules/@ministryofjustice/frontend/moj/assets')))
 ```
+
 ### Alternative solution
 
 Manually copy the images and fonts from `/node_modules/@ministryofjustice/frontend/moj/assets` into a public facing directory in your project. Ideally copying the files to your project should be an automated task or part of your build pipeline to ensure that the MOJ Frontend assets stay up-to-date.
@@ -100,7 +110,7 @@ $moj-assets-path: ‘/application/assets’;
 @import “@ministryofjustice/frontend/moj/all”;
 ```
 
-  Example 2:
+Example 2:
 
 ```SCSS
 // Include images from /images/@ministryofjustice/frontend and fonts from /fonts
@@ -110,76 +120,9 @@ $moj-fonts-path: “/fonts/”;
 @import “@ministryofjustice/frontend/moj/all”;
 ```
 
-## Include CSS and JavaScript
-
-Add the CSS and JavaScript code to your HTML template:
-
-```html
-<!DOCTYPE html>
-  <head>
-    <title>Example</title>
-    <link rel="stylesheet" href="assets/application.css">
-  </head>
-  <body>
-    <!-- Copy and paste component HTML-->
-    <button class="govuk-button">This is a button component</button>
-    <script src="assets/application.js"></script>
-  </body>
-</html>
-```
-
-## Using JavaScript
-
-Some of the JavaScript included in MOJ Frontend improves the usability and accessibility of the components.
-
-You should include or import MOJ Frontend JavaScript, and then initialise the appropriate script in your application to ensure that all users can use it successfully.
+## Importing JavaScript
 
-Note that MOJ Frontend does not initialise any scripts by default; all scripts must be initialised in order for them to work.
-
-### Option 1: Include JavaScript
-
-Include the node_modules/ministryofjustice/moj-frontend/moj/all.js script on your page. You might wish to copy the file into your project or reference it from node_modules.
-
-JavaScript in MOJ Frontend requires HTML to be parsed first by the browser before it is initialised. Because of this, make sure you include the script before the closing `</body>` tag. Including the script elsewhere will stop components from functioning or displaying correctly.
-
-```html
-    <script src="path-to-assets/moj-frontend/moj/all.js"></script>
-  </body>
-</html>
-```
-
-MOJ Frontend components with JavaScript behaviour are initialised manually.
-
-To initialise the button menu on a page you can do this:
-
-```js
-  new MOJFrontend.ButtonMenu({
-    container: $('.button-menu-1'),
-    mq: '(min-width: 45em)',
-    buttonText: 'Actions'
-  });
-```
-
-### Option 2: Import JavaScript
-
-If you're using a bundler such as Webpack, use the import syntax to import all components:
-
-```js
-import MOJFrontend from 'path/to/all.js';
-```
-
-If you're using a bundler such as Webpack, use the import syntax to import a component:
-
-```js
-import { ButtonMenu } from 'path/to/all.js';
-```
-
-If you're using a bundler such as Browserify, you may need to use the CommonJS require:
-
-```js
-const MOJFrontend = require('moj-frontend');
-new MOJFrontend.ButtonMenu(...);
-```
+_See [Setting up JavaScript](../../get-started/setting-up-javascript) for information on how to install, configure and use JavaScript_
 
 ## Include CSS and JavaScript
 
@@ -192,9 +135,12 @@ Add the CSS and JavaScript code to your HTML template:
     <link rel="stylesheet" href="assets/application.css">
   </head>
   <body>
+    <!-- Copy and paste component HTML-->
+    <button class="govuk-button">This is a button component</button>
+    <script src="assets/jquery.js"></script>
     <script src="assets/application.js"></script>
   </body>
 </html>
 ```
 
-If your service supports Internet Explorer 8, you will need to [generate and include a separate stylesheet](supporting-internet-explorer-8.md) as well.
+If your service supports Internet Explorer 8, you will need to [generate and include a separate stylesheet](../supporting-internet-explorer-8) as well.
diff --git a/docs/get-started/production.md b/docs/get-started/production.md
@@ -14,7 +14,7 @@ First you must have followed the [GOV.UK Design System production setup guide](h
 
 To start using MOJ styles, components and patterns contained here, you’ll need to include MOJ Frontend in your project.
 
-We recommend [installing MOJ Frontend using npm](https://github.com/ministryofjustice/moj-frontend/blob/main/docs/installation/installing-with-npm.md). Using this option, you will be able to:
+We recommend [installing MOJ Frontend using npm](../installing-with-npm). Using this option, you will be able to:
 
 - selectively include the CSS or JavaScript for individual components
 - build your own styles or components based on the palette or typography and spacing mixins

diff --git a/docs/get-started/setting-up-javascript.md b/docs/get-started/setting-up-javascript.md
@@ -18,11 +18,14 @@ To include the code directly in a template, first either:
 - set up your routing so that requests for the JavaScript file are served from `node_modules/@ministryofjustice/frontend/moj/all.js`
 - copy the `node_modules/@ministryofjustice/frontend/moj/all.js` file into your application
 
+You will also need to install and serve [jQuery](https://jquery.com/).
+
 Then import the JavaScript file before the closing `</body>` tag of your HTML page or page template, and run the `initAll` function to initialise the components.
 
 ```html
 <body>
 ...
+  <script src="<YOUR-APP>/jquery.js"></script>
   <script src="<YOUR-APP>/<YOUR-JS-FILE>.js"></script>
   <script>
     window.MOJFrontend.initAll()
@@ -34,10 +37,13 @@ Then import the JavaScript file before the closing `</body>` tag of your HTML pa
 
 ## Import using a bundler
 
-If you decide to import using a bundler, use `import` to import all of design systems’s components, then run the `initAll` function to initialise them:
+If you decide to import using a bundler, use `import` to import jQuery and all of the design systems’s components, then run the `initAll` function to initialise them:
 
 ```javascript
+import $ from 'jquery'
 import { initAll } from '@ministryofjustice/frontend'
+
+window.$ = $
 initAll()
 ```
 

diff --git a/docs/get-started/supporting-internet-explorer-8.md b/docs/get-started/supporting-internet-explorer-8.md
@@ -0,0 +1,27 @@
+---
+layout: layouts/get-started.njk
+title: Supporting Internet Explorer 8
+---
+
+If you are including MOJ Frontend as part of your application's stylesheets then you'll need to do some additional work to support Internet Explorer 8 (IE8).
+
+The first thing you need to do is follow [GOV.UK Frontend's setup instructions](https://frontend.design-system.service.gov.uk/supporting-ie8/) for supporting Internet Explorer 8.
+
+When [generating your IE8-specific stylesheet](https://frontend.design-system.service.gov.uk/supporting-ie8/#2-generate-an-ie8-specific-stylesheet), your `application.scss` will also include the MOJ Frontend import:
+
+```scss
+// application.scss
+
+@import "govuk-frontend/frontend/all";
+@import "@ministryofjustice/frontend/all";
+
+.example {
+  // example application style
+}
+
+// application-ie8.scss
+
+$govuk-is-ie8: true;
+
+@import "application";
+```
diff --git a/docs/installation/supporting-internet-explorer-8.md b/docs/installation/supporting-internet-explorer-8.md