Merge pull request #759 from alphagov/avoid-auto-initialising-components

Avoid auto initialising initAll and export Components

CHANGELOG.md

@@ -6,6 +6,33 @@ Note: We're not following semantic versioning yet, we are going to talk about th
 
 💥 Breaking changes:
 
+- The default build of the GOV.UK Frontend JavaScript now does not initialize all components automatically.
+
+  This allows you to initialize only the components you need, and gives you finer control over when the JavaScript for GOV.UK Frontend runs.
+
+  To migrate your project you need to change
+  ```html
+    <script src="{path-to-govuk-frontend}/all.js"></script>
+  ```
+  to
+  ```html
+    <script src="{path-to-govuk-frontend}/all.js"></script>
+    <script>window.GOVUKFrontend.initAll()</script>
+  ```
+
+  Now, if you only want to initialize a specific component you can now do so by:
+  ```html
+    <script src="{path-to-govuk-frontend}/all.js"></script>
+    <script>
+      var Button = window.GOVUKFrontend.Button
+      new Button(document).init()
+    </script>
+  ```
+
+  Note: If you are importing JavaScript with a bundler, this is not likely to change anything for you.
+  ([PR #759](https://github.com/alphagov/govuk-frontend/pull/759))
+
+
 - All sass-mq settings have now been made private. We are now exposing new
   settings to allow you to customise breakpoints and responsive behaviour:
 
@@ -20,13 +47,12 @@ Note: We're not following semantic versioning yet, we are going to talk about th
   ([PR #748](https://github.com/alphagov/govuk-frontend/pull/748))
 
 - Font settings have been renamed:
-  
+
   - `$govuk-font-stack` has been renamed to `$govuk-font-family`
   - `$govuk-font-stack-tabular` has been renamed to `$govuk-font-family-tabular`
   - `$govuk-font-stack-print` has been renamed to `$govuk-font-family-print`
 
   ([PR #748](https://github.com/alphagov/govuk-frontend/pull/748))
-
 🔧 Fixes:
 
 - The `<label>` element will now be omitted for form controls where no label
@@ -52,6 +78,16 @@ Note: We're not following semantic versioning yet, we are going to talk about th
 
 🆕 New features:
 
+- Components are now available to use from the `GOVUKFrontend` global.
+You can now initialize individual components like so:
+```html
+  <script>
+    var Radios = window.GOVUKFrontend.Radios
+    new Radios(document).init()
+  </script>
+```
+([PR #759](https://github.com/alphagov/govuk-frontend/pull/759))
+
 - Add `beforeContent` block to the template, for content that does not belong inside `<main>` element.
   For example: Back links.
   ([PR #742](https://github.com/alphagov/govuk-frontend/pull/742))

README.md

@@ -292,6 +292,7 @@ Add the CSS and JavaScript code to your HTML template (this assumes you've copie
     <!-- Copy and paste component HTML-->
     <button class="govuk-button">This is a button component</button>
     <script src="assets/govuk-frontend-[latest version].min.js"></script>
+    <script>window.GOVUKFrontend.initAll()</script>
   </body>
 </html>
 ```

app/views/layouts/_generic.njk

@@ -28,6 +28,7 @@
 
 {% block bodyEnd %}
   <script src="/public/all.js"></script>
+  <script>window.GOVUKFrontend.initAll()</script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/iframe-resizer/3.5.15/iframeResizer.min.js"></script>
   <!--[if lte IE 8]>
     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/iframe-resizer/3.5.15/ie8.polyfils.min.js"></script>

src/all.js

@@ -6,7 +6,7 @@ import ErrorSummary from './components/error-summary/error-summary'
 import Header from './components/header/header'
 import Radios from './components/radios/radios'
 
-export function initAll () {
+function initAll () {
   new Button().init()
   new Details().init()
 
@@ -29,4 +29,12 @@ export function initAll () {
   })
 }
 
-(initAll())
+export {
+  initAll,
+  Button,
+  Details,
+  Checkboxes,
+  ErrorSummary,
+  Header,
+  Radios
+}

src/all.test.js

@@ -22,6 +22,14 @@ let baseUrl = 'http://localhost:' + PORT
 beforeAll(async (done) => {
   browser = global.__BROWSER__
   page = await browser.newPage()
+
+  // Capture JavaScript errors.
+  page.on('pageerror', error => {
+    // If the stack trace includes 'all.js' then we want to fail these tests.
+    if (error.stack.includes('all.js')) {
+      throw error
+    }
+  })
   done()
 })
 
@@ -39,6 +47,46 @@ describe('GOV.UK Frontend', () => {
 
       expect(typeof GOVUKFrontendGlobal).toBe('object')
     })
+    it('exports `initAll` function', async () => {
+      await page.goto(baseUrl + '/', { waitUntil: 'load' })
+
+      const typeofInitAll = await page.evaluate(() => typeof window.GOVUKFrontend.initAll)
+
+      expect(typeofInitAll).toEqual('function')
+    })
+    it('exports Components', async () => {
+      await page.goto(baseUrl + '/', { waitUntil: 'load' })
+
+      const GOVUKFrontendGlobal = await page.evaluate(() => window.GOVUKFrontend)
+
+      var components = Object.keys(GOVUKFrontendGlobal).filter(method => method !== 'initAll')
+
+      // Ensure GOV.UK Frontend exports the expected components
+      expect(components).toEqual([
+        'Button',
+        'Details',
+        'Checkboxes',
+        'ErrorSummary',
+        'Header',
+        'Radios'
+      ])
+    })
+    it('exported Components can be initialised', async () => {
+      await page.goto(baseUrl + '/', { waitUntil: 'load' })
+
+      const GOVUKFrontendGlobal = await page.evaluate(() => window.GOVUKFrontend)
+
+      var components = Object.keys(GOVUKFrontendGlobal).filter(method => method !== 'initAll')
+
+      // Check that all the components on the GOV.UK Frontend global can be initialised
+      components.forEach(component => {
+        page.evaluate(component => {
+          const Component = window.GOVUKFrontend[component]
+          const $module = document
+          new Component($module).init()
+        }, component)
+      })
+    })
   })
   describe('global styles', async() => {
     it('are disabled by default', async () => {