Add component options (args) to YAML, add as JSON to `package` #998

hannalaakso · 2018-09-13T16:03:44Z

We want to expose the component options (arguments) to GOV.UK Design System. To do this, they need to be generated for inclusion in package.

This PR:

Adds all component options in the component YAML as params.
Introduces isComponent option (so that the options for that component can be linked to in the Design System).
Copies the component options as JSON files to package when gulp build:package --destination 'package' is run.
Amends the tests for checking contents of package to allow filenames with wildcards in additionalFilesNotInSrc
Adds a test to check all package/components have a macro-options.json that contains valid JSON with the expected attributes name, type, required, description

Created this as one PR so that the generated JSON files can be tested against alphagov/govuk-design-system#518

More on component options:

We now refer to these as “options” in client facing docs as calling them “arguments” is technically incorrect and “parameters” was felt to be less clear than “options”.
Regarding the "or" relationship between text and html attributes, we are continuing to explain this in the description of the attributes, ie. "If html is set, this is not required." There didn't seem to be a sensible way of trying to show this relationship in a simple table so using just text appeared to be the most accessible method.
This PR retains the convention of referring to them as “params” in component macro and template files - we might want to roll out renaming “params” to “options” in all component macros and templates as a separate PR that can be quickly merged in without causing too many conflicts with other PRs.

To test, run npm run build:package

https://trello.com/c/QN0imhXt/722-define-arguments-for-components-in-the-component-yaml-file
https://trello.com/c/00iDbQOU/1323-allow-argument-yamls-to-be-transformed-into-json-and-copied-to-package

kr8n3r · 2018-09-17T14:28:38Z

tasks/gulp/copy-to-destination.js

+
+      try {
+        let json = yaml.safeLoad(fs.readFileSync(componentPath), {encoding: 'utf8', json: true})
+        let paramsJson = {'params': json.params} // We only want the 'params' data from component yaml


should we stop the task if the yaml file doesn't contain the params data ?

This is in a try block so it will throw up an error if that happens and the tests will also fail. That's probably okay? This is in the middle of the copy-files task so if we exit here, there might already be files copied over to package and others deleted.

src/components/breadcrumbs/breadcrumbs.yaml

src/components/fieldset/fieldset.yaml

joelanman · 2018-09-18T17:09:10Z

src/components/fieldset/fieldset.yaml

+- name: caller
+  type: nunjucks-block
+  required: false
+  description: Not strictly a parameter but <a href="https://mozilla.github.io/nunjucks/templating.html#call">Nunjucks code convention</a>. Using a `call` block enables you to call a macro with all the text inside the tag. This is helpful if you want to pass a lot of content into a macro. To use it, you will need to wrap the entire fielset component in a `call` block. See <a href="https://github.com/alphagov/govuk-frontend/blob/master/src/components/checkboxes/template.njk#L86">checkboxes component</a> for an example.


We're using html here for the links. We're also using ` backticks for option names, which is a markdown convention. We don't have to do anything with the backticks, but it's probably best to run them through a renderer to get <code> blocks. In which case maybe we should just use markdown for the links too?

Good shout. I was avoiding markdown since I only needed to use HTML in this one place for the component options and we discovered we'll need to do some extra processing as part of the build in the Design System to render markdown from here. But since we've got the code blocks too then making it all markdown makes sense 🙂

joelanman · 2018-09-18T18:35:09Z

tasks/gulp/copy-to-destination.js

+        let paramsJson = json.params // We only want the 'params' data from component yaml
+        file.contents = Buffer.from(JSON.stringify(paramsJson, null, 4))
+      } catch (e) {
+        console.log('ENOENT: no such file or directory: ', file)


This should probably be console.error. Also the try section has 3 lines in it, so we don't know for sure that this is the error. I'd recommend trying to reduce the try to just opening the file.

I've split up the error messages more, have a look.

joelanman · 2018-09-18T18:37:12Z

tasks/gulp/copy-to-destination.js

+      let componentPath = path.join(configPaths.components, componentName, `${componentName}.yaml`)
+
+      try {
+        let json = yaml.safeLoad(fs.readFileSync(componentPath), {encoding: 'utf8', json: true})


the readFileSync could be pulled out into a line above to make it more readable and have fewer operations happening in a single line

joelanman · 2018-09-18T18:38:48Z

Do we still have a frontend test app? Maybe we can read the macro options json and write to a page in that, so we can see it works?

hannalaakso · 2018-09-19T15:41:56Z

@joelanman Thanks a lot for the review 🙌

We test if the file contains JSON and if the JSON contains attributes (name, type, required, description) that we would expect it to have. Do you there are specific advantages to testing it in the test app or anything in particular we should look out for?

NickColley

All the components have been reviewed by the team and given a 👍 so I think this is good to go.

NickColley

We need to add a CHANGELOG entry

Call files `macro-options.json` as only that data is copied over to package.

`additionalFilesInSrc` can now accept wildcards in filenames, allowing us to add new files to `package/components`. The test checks if all components have a `macro-options.json` and whether it contains JSON with expected attributes "name", "type", "required" and "description".

NickColley

This is a ton of work, thanks a lot Hanna 👍

As per changes made in #998 and alphagov/govuk-design-system#518 update contributor docs on component options

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 13, 2018 16:04 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 1668edf to 7fd6b03 Compare September 13, 2018 16:27

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 13, 2018 16:27 Inactive

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 15, 2018 17:48 Inactive

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 16, 2018 07:23 Inactive

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 17, 2018 11:33 Inactive

kr8n3r reviewed Sep 17, 2018

View reviewed changes

src/components/breadcrumbs/breadcrumbs.yaml Show resolved Hide resolved

hannalaakso force-pushed the add-args-as-yaml branch from a700c1f to 4cd3f81 Compare September 17, 2018 16:49

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 17, 2018 16:49 Inactive

NickColley reviewed Sep 17, 2018

View reviewed changes

src/components/fieldset/fieldset.yaml Show resolved Hide resolved

hannalaakso force-pushed the add-args-as-yaml branch from 4cd3f81 to dbdecba Compare September 18, 2018 12:30

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 18, 2018 12:30 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from dbdecba to d05f1f8 Compare September 18, 2018 13:09

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 18, 2018 13:09 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from d05f1f8 to 7e0ed3f Compare September 18, 2018 13:15

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 18, 2018 13:15 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 7e0ed3f to 5b6970a Compare September 18, 2018 13:19

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 18, 2018 13:19 Inactive

hannalaakso changed the title ~~WIP: Add component options (args) to YAML, add as JSON to package~~ Add component options (args) to YAML, add as JSON to package Sep 18, 2018

joelanman reviewed Sep 18, 2018

View reviewed changes

hannalaakso force-pushed the add-args-as-yaml branch from 5b6970a to 3bad6a4 Compare September 18, 2018 17:25

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 18, 2018 17:26 Inactive

joelanman suggested changes Sep 18, 2018

View reviewed changes

hannalaakso force-pushed the add-args-as-yaml branch from 3bad6a4 to a89abfe Compare September 19, 2018 15:32

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 19, 2018 15:32 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from a89abfe to d8b2b40 Compare September 19, 2018 15:38

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 19, 2018 15:38 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from f771693 to 38c8fdf Compare September 20, 2018 15:49

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 20, 2018 15:49 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 38c8fdf to 7881ccc Compare September 20, 2018 16:13

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 20, 2018 16:14 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 7881ccc to cbef971 Compare September 20, 2018 17:33

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 20, 2018 17:33 Inactive

NickColley approved these changes Sep 21, 2018

View reviewed changes

NickColley suggested changes Sep 21, 2018

View reviewed changes

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 21, 2018 14:17 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from beeb64a to 00135bf Compare September 21, 2018 14:18

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 21, 2018 14:18 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 00135bf to 535f17d Compare September 21, 2018 14:19

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 21, 2018 14:20 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 535f17d to 83ba92d Compare September 21, 2018 14:20

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 21, 2018 14:20 Inactive

hannalaakso force-pushed the add-args-as-yaml branch from 83ba92d to 624c997 Compare September 21, 2018 14:21

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-998 September 21, 2018 14:21 Inactive

hannalaakso and others added 4 commits September 21, 2018 15:45

Define options for components in component YAML

8ff50b6

Transform component params into JSON and copy to package

e3bf0d0

Call files `macro-options.json` as only that data is copied over to package.

Update Changelog

643ae80

hannalaakso force-pushed the add-args-as-yaml branch from 624c997 to 643ae80 Compare September 21, 2018 14:47

govuk-design-system-ci deployed to govuk-frontend-review-pr-998 September 21, 2018 14:47 View deployment

NickColley approved these changes Sep 21, 2018

View reviewed changes

hannalaakso merged commit 3150e00 into master Sep 21, 2018

hannalaakso deleted the add-args-as-yaml branch September 21, 2018 15:17

kr8n3r mentioned this pull request Sep 26, 2018

Release v2.1.0 #1011

Merged

hannalaakso added a commit that referenced this pull request Oct 8, 2018

Update docs on component options

e065a55

As per changes made in #998 and alphagov/govuk-design-system#518 update contributor docs on component options

hannalaakso mentioned this pull request Oct 8, 2018

Update docs on component options #1025

Merged

colinrotherham mentioned this pull request Sep 29, 2023

Remove unnecessary duplicated use of govuk-font #4267

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add component options (args) to YAML, add as JSON to `package` #998

Add component options (args) to YAML, add as JSON to `package` #998

hannalaakso commented Sep 13, 2018 •

edited

Loading

kr8n3r Sep 17, 2018 •

edited

Loading

hannalaakso Sep 17, 2018

joelanman Sep 18, 2018 •

edited

Loading

hannalaakso Sep 18, 2018

joelanman Sep 18, 2018

hannalaakso Sep 19, 2018

joelanman Sep 18, 2018

hannalaakso Sep 19, 2018

joelanman commented Sep 18, 2018

hannalaakso commented Sep 19, 2018 •

edited

Loading

NickColley left a comment

NickColley left a comment

NickColley left a comment

Add component options (args) to YAML, add as JSON to package #998

Add component options (args) to YAML, add as JSON to package #998

Conversation

hannalaakso commented Sep 13, 2018 • edited Loading

kr8n3r Sep 17, 2018 • edited Loading

Choose a reason for hiding this comment

hannalaakso Sep 17, 2018

Choose a reason for hiding this comment

joelanman Sep 18, 2018 • edited Loading

Choose a reason for hiding this comment

hannalaakso Sep 18, 2018

Choose a reason for hiding this comment

joelanman Sep 18, 2018

Choose a reason for hiding this comment

hannalaakso Sep 19, 2018

Choose a reason for hiding this comment

joelanman Sep 18, 2018

Choose a reason for hiding this comment

hannalaakso Sep 19, 2018

Choose a reason for hiding this comment

joelanman commented Sep 18, 2018

hannalaakso commented Sep 19, 2018 • edited Loading

NickColley left a comment

Choose a reason for hiding this comment

NickColley left a comment

Choose a reason for hiding this comment

NickColley left a comment

Choose a reason for hiding this comment

Add component options (args) to YAML, add as JSON to `package` #998

Add component options (args) to YAML, add as JSON to `package` #998

hannalaakso commented Sep 13, 2018 •

edited

Loading

kr8n3r Sep 17, 2018 •

edited

Loading

joelanman Sep 18, 2018 •

edited

Loading

hannalaakso commented Sep 19, 2018 •

edited

Loading