Merge pull request #219 from alphagov/javascript-api-reference

Add documentation for configuration and internationalisation

Author: 36degrees

source/configure-components-with-javascript/index.html.md.erb

@@ -0,0 +1,94 @@
+---
+title: Configure components with JavaScript
+weight: 76
+---
+
+# Configure components with JavaScript
+
+You can configure some of the components in GOV.UK Frontend to customise their behaviour or to [localise their JavaScript to use a language other than English](/localise-govuk-frontend/).
+
+You can configure a component by:
+
+- setting Nunjucks macro options
+- using data attributes in the HTML
+- passing a JavaScript object when creating an instance of a component
+- using the `initAll` function
+
+## Setting Nunjucks macro options
+
+If you're using the Nunjucks macros, you will find all of the configuration options for a component published on the GOV.UK Design System website.
+
+You can find the Nunjucks macro options by selecting the Nunjucks tab in the example box and selecting the Nunjucks macro options.
+
+## Passing configuration using data attributes in HTML
+
+If you're using HTML, you can pass configuration by adding data attributes to the component's outermost element (the element that has the `data-module` attribute). This is how our Nunjucks macros forward the configuration to the JavaScript components in the browser. Data attributes use kebab-case.
+
+Some configuration options are grouped under a namespace to keep related options together. For example, [the localisation options](/localise-govuk-frontend/) are grouped under the `i18n` namespace. When using these options, include the namespace as a prefix followed by a period as part of the attribute name.
+
+For options accepting object values, you'll need to set one attribute for each key of that object. Suffix the attribute name (including any namespace) with a period and the name of the key in the object.
+
+This example shows the opening tag of a character count component with some configuration options including:
+
+- a specific number of characters (non-namespaced configuration)
+- a new message for when users reach the specified number of characters (namespaced configuration)
+- two plural forms for when users are under the specified limit of characters (namespaced configuration + object value)
+
+```html
+<div data-module="govuk-character-count"
+  data-maxlength="500"
+  data-i18n.characters-at-limit="No characters left"
+  data-i18n.characters-under-limit.other="%{count} characters to go"
+  data-i18n.characters-under-limit.one="%{count} character to go">
+```
+
+If your configuration contains [quotes or other reserved HTML characters](https://developer.mozilla.org/en-US/docs/Glossary/Entity#reserved_characters), you'll need to escape those characters.
+
+Configuration is read from data attributes when the component is initialised. Changes to the data attributes made after the component has been initialised will have no effect on the behaviour of the component.
+
+Read the [JavaScript API Reference](/javascript-api-reference/) for the configuration accepted by each component. You'll need to convert the configuration names into kebab-case.
+
+## Passing configuration to a new instance of a component in JavaScript
+
+You can pass a configuration object to the constructor when creating an instance of a component in JavaScript.
+
+Component constructors accept two arguments:
+
+1. The HTML element that represents the component.
+2. An optional configuration object.
+
+The object should include key-value pairs. The keys should be written in camelCase.
+
+Components will merge the configuration provided at initialisation with those provided as data-attributes. If the same option is defined in both, the one provided by data-attributes will take precedence.
+
+Some configuration options might accept object values or be grouped under a namespace to keep related things together. For example, [the localisation options](/localise-govuk-frontend/) are grouped under the `i18n` namespace. When using these options, use nested objects. For example:
+
+```javascript
+new CharacterCount($element, {
+  maxlength: 500, // Non namespaced
+  i18n: { // i18n namespace
+    charactersAtLimit: "No characters left",
+    charactersUnderLimit: { // Object value
+      other: "%{count} characters to go",
+      one: "%{count} character to go"
+    }
+  }
+}).init()
+```
+
+Read the [JavaScript API Reference](/javascript-api-reference/) to see what configuration each component accepts.
+
+## Passing configuration using the initAll function
+
+You can pass configuration for components when initialising GOV.UK Frontend using the `initAll` function. You can do this by including key-value pairs of camel-cased component names and configuration objects. This is the same method you would use to pass them when creating an instance of the component. For example:
+
+```javascript
+window.GOVUKFrontend.initAll({
+  characterCount: {
+    maxlength: 500, // Non namespaced
+    i18n: { // i18n namespace
+      charactersAtLimit: "No characters left"
+    }
+  },
+})
+```