docs: document jQuery requirement

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.
ministryofjustice · Jun 25, 2021 · 1e59e62 · 1e59e62
1 parent bb3e0c1
commit 1e59e62
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 73 deletions.
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 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/installation/installing-with-npm.md b/docs/installation/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.
-
-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';
-```
+## Importing JavaScript
 
-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,14 @@ 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.
+
+## Using JavaScript