From 43e59d1064f30fe24aac54cf4c9cdd6556e03be7 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Mon, 18 Nov 2024 14:53:56 +0000 Subject: [PATCH 1/2] Update components coding standards Include introduction to building JavaScript components. Push support option to bottom of doc to encourage teams to build themselves. --- docs/contributing/coding-standards/components.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/contributing/coding-standards/components.md b/docs/contributing/coding-standards/components.md index 7b24dc5ff8..a05fe05588 100644 --- a/docs/contributing/coding-standards/components.md +++ b/docs/contributing/coding-standards/components.md @@ -26,6 +26,8 @@ If your component uses JavaScript, you must also create the following files in t ## Building your components -If you need help building a component, [contact the Design System team](https://design-system.service.gov.uk/get-in-touch/) and we'll support you. +To help you build and initialise your own JavaScript components, GOV.UK Frontend provides some of its internal features for you to reuse. Follow our guidance on [building JavaScript components](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#building-your-own-javascript-components) to use these features. Learn more about styling components in our [CSS style guide](./css.md). Our [JavaScript style guide](./js.md) has more information on coding components. + +If you need help building a component, [contact the Design System team](https://design-system.service.gov.uk/get-in-touch/) and we'll support you. From f3e4031a4d3e17a9b8f3bda579cf5866eb6137e2 Mon Sep 17 00:00:00 2001 From: Brett Kyle Date: Tue, 19 Nov 2024 13:58:24 +0000 Subject: [PATCH 2/2] Move most guidance to Frontend Docs site --- .../coding-standards/component-options.md | 229 +++--------------- 1 file changed, 33 insertions(+), 196 deletions(-) diff --git a/docs/contributing/coding-standards/component-options.md b/docs/contributing/coding-standards/component-options.md index 9fadeca1d8..1437136308 100644 --- a/docs/contributing/coding-standards/component-options.md +++ b/docs/contributing/coding-standards/component-options.md @@ -4,191 +4,29 @@ Configuration options allow developers to pass additional information into a com Configuration options can be configured using Nunjucks, HTML or JavaScript, but only JavaScript will use the options. -## Preparing the component's JavaScript - -First, make sure the component class has a constructor parameter for passing in a configuration object. - -```mjs -export class Accordion { - constructor($root, config = {}) { - // ... - } -} -``` - -Within the entry class, you'll then create an object with the default configuration for the component. These are the options the component will use if no other options are provided. - -```mjs -export class Accordion { - static defaults = Object.freeze({ - rememberExpanded: true - }) -} -``` - -Next, use the `mergeConfigs` helper to combine the default config and the configuration object. The result of the merge is assigned globally (using `this`) so that it's accessible anywhere within the component's JavaScript. - -The order in which variables are written defines their priority, with objects passed sooner being overwritten by those passed later. As we want the user's configuration to take precedence over our defaults, we list our default configuration object first. - -There is no guarantee `config` will have any value at all, so we set the default to an empty object (`{}`) in the constructor parameters. - -```mjs -import { mergeConfigs } from '../../common/configuration.mjs' - -export class Accordion { - constructor($root, config = {}) { - this.config = mergeConfigs( - Accordion.defaults, - config - ) - } -} -``` - -We can now reference the configuration option anywhere we need to in the component's JavaScript: - -```js -this.config.rememberExpanded -// => true -``` - -It's now possible to individually initialise the component with configuration options. - -```html - -``` - -## Allowing options to be passed through the `initAll` function - -Often, teams will not be individually initialising components. Instead, GOV.UK Frontend ships with an `initAll` function, which searches the page for instances of components and automatically initialises them. - -In `packages/govuk-frontend/src/govuk/init.mjs`, update the component's `new` class to pass through a nested configuration object. The nested object should use the component's name converted to camelCase (for example, the 'Character Count' component becomes `characterCount`). - -```js -new Accordion($accordion, config.accordion) -``` - -It's now possible to pass configuration options for your component, as well as multiple other components, using the `initAll` function. - -```html - -``` - -## Adding support for HTML `data-*` attributes +For more information, see our [guidance on building configurable components](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#building-configurable-components). -For convenience, we also allow for configuration options to be passed through HTML `data-*` attributes. - -You can find `data-*` attributes in JavaScript by looking at an element's `dataset` property. Browsers will convert the attribute names from HTML's kebab-case to more JavaScript-friendly camelCase when working with `dataset`. - -See ['Naming configuration options'](#naming-configuration-options) for exceptions to how names are transformed. - -As we expect configuration-related `data-*` attributes to always be on the component's root element (the same element with the `data-module` attribute), we can access them all using `this.$root.dataset`. - -Using the `mergeConfigs` call discussed earlier in this document, update it to include `this.$root.dataset` as the highest priority after calling the constuctor of `GOVUKFrontendComponent` with `super()`. - -```mjs -import { mergeConfigs, normaliseDataset } from '../../common/configuration.mjs' -import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs' - -export class Accordion extends GOVUKFrontendComponent{ - constructor($root, config = {}) { - super($root) - - this.config = mergeConfigs( - Accordion.defaults, - config, - normaliseDataset(Accordion, this.$root.dataset) - ) - } -} -``` - -Here, we pass the value of `this.$root.dataset` through our `normaliseDataset` function. This is because attribute values in dataset are always interpreted as strings. `normaliseDataset` looks at the component's configuration schema and converts values into numbers or booleans where needed. - -Now, in our HTML, we could pass configuration options by using the kebab-case version of the option's name. - -```html -
- ... -
-``` - -However, this only works for developers who are writing raw HTML. We include Nunjucks macros for each component with GOV.UK Frontend to make development easier and faster, but this also makes it harder for developers to manually alter the raw HTML. We'll add a new parameter to Nunjucks to help them out. +## Preparing the component's JavaScript -### Adding a configuration schema +If a component class needs configuration, [extend the `ConfigurableComponent` class](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/) that GOV.UK Frontend provides. This class accepts configuration from the following sources: -Components that accept configuration using `data-*` attributes also require a schema. This schema documents what parameters a configuration object may contain and what types of value they're expected to be. +- [defaults defined as a `defaults` static property](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#setting-a-default-configuration-for-your-component) on the component’s class +- [configuration passed as second argument](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#receiving-configuration-during-initialisation) to the component’s constructor or [`createAll`](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#using-createall-with-your-components) +- [data attributes on the root element](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#receiving-configuration-from-data-attributes) of the component -Having a schema is required for the `normaliseDataset` function to work. A schema is also needed to use the `validateConfig` and `extractConfigByNamespace` functions we'll cover later on. +Configuration options from these sources are merged into a single configuration object by the `ConfigurableComponent` class. Note that: -```mjs -export class Accordion { - static schema = Object.freeze({ - properties: { - i18n: { type: 'object' }, - rememberExpanded: { type: 'boolean' } - } - }) -} -``` +- configuration options passed to the constructor will override any defaults +- data attribute values have highest precedence and will override any configuration set elsewhere -### Validating a provided configuration against the schema +Your component will then be able to: -You can use the `validateConfig` function to ensure that a configuration object matches the schema format. - -If it doesn't, you can return a `ConfigError`. - -```mjs -import { mergeConfigs, validateConfig, normaliseDataset } from '../../common/configuration.mjs' -import { ConfigError } from '../../errors/index.mjs' -import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs' - -export class Accordion extends GOVUKFrontendComponent { - constructor($root, config = {}) { - super($root) - - this.config = mergeConfigs( - Accordion.defaults, - config, - normaliseDataset(Accordion, this.$root.dataset) - ) - - // Check that the configuration provided is valid - const errors = validateConfig(Accordion.schema, this.config) - if (errors[0]) { - throw new ConfigError(formatErrorMessage(CharacterCount, errors[0])) - } - } -} -``` +[access the merged configuration](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#accessing-the-component-s-configuration) using `this.config` +use [the`Component` class](https://frontend.design-system.service.gov.uk/building-your-own-javascript-components/#using-the-component-class) features ## Adding a Nunjucks parameter -Most, but not all, components support adding arbitrary attributes and values through the `attributes` parameter. This method is also more verbose compared to having a dedicated Nunjucks parameter. - -Using the previous bit of HTML, update it to make the `data-*` attribute changeable. +Most, but not all, components support adding arbitrary attributes and values through the `attributes` parameter. This method is also more verbose compared to having a dedicated Nunjucks parameter to set data attributes on the root element. For example, this is how the Accordion does it for its `rememberExpanded` option: ```nunjucks