Add documentation for component conventions and principles #14
Conversation
fofr
commented
Aug 3, 2017
|
* Output from GOV.UK Publishing Frontend team workshop
| A lead-paragraph component would be included in a template like this: | ||
|
|
||
| ```erb | ||
| <%= render 'components/lead-paragraph', { text: "A description is one or two leading sentences." } %> |
andysellick
Aug 7, 2017
Contributor
Are the curly braces needed?
Are the curly braces needed?
nickcolley
Aug 7, 2017
Contributor
Might be worth always having them, since the guide also does this.
Might be worth always having them, since the guide also does this.
fofr
Aug 7, 2017
Author
Contributor
Removed.
Removed.
| | -- | -- | | ||
| | `.app-c-` | Component lives within the frontend application | | ||
| | `.pub-c-` | Component is shared between publishing frontends and lives in static | | ||
| | `.govuk-c-` | Component originates from [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend) | |
andysellick
Aug 7, 2017
Contributor
This whole opening section relates to styles, so I'd start with the 'Structure' section and move this into the 'Styles' section. Then the link to the GOV.UK frontend doc with their BEM convention is more usefully placed (https://github.com/alphagov/govuk-frontend/blob/master/docs/coding-standards/css.md)
This whole opening section relates to styles, so I'd start with the 'Structure' section and move this into the 'Styles' section. Then the link to the GOV.UK frontend doc with their BEM convention is more usefully placed (https://github.com/alphagov/govuk-frontend/blob/master/docs/coding-standards/css.md)
fofr
Aug 7, 2017
Author
Contributor
I discussed this with @nickcolley. I've put it first as I think it's the most important thing. It mirrors he GOV.UK Frontend docs and structure follows closely behind.
I discussed this with @nickcolley. I've put it first as I think it's the most important thing. It mirrors he GOV.UK Frontend docs and structure follows closely behind.
nickcolley
Aug 7, 2017
Contributor
I'm on the fence with this one, I think it's the most important for the GOV.UK Frontend project but not for us?
I thought the same as Andy, I was unsure why I was seeing classes and what they related to. Maybe it'd make more sense with the context of the structure first.
I'm on the fence with this one, I think it's the most important for the GOV.UK Frontend project but not for us?
I thought the same as Andy, I was unsure why I was seeing classes and what they related to. Maybe it'd make more sense with the context of the structure first.
andysellick
Aug 7, 2017
Contributor
I think the confusing thing is that styles are discussed twice. I think all the style stuff should be together.
I think the confusing thing is that styles are discussed twice. I think all the style stuff should be together.
fofr
Aug 7, 2017
Author
Contributor
I could add the heading "Namespacing"?
I could add the heading "Namespacing"?
fofr
Aug 7, 2017
Author
Contributor
Added the Namespacing heading. I think that clarifies things a little.
Added the Namespacing heading. I think that clarifies things a little.
|
|
||
| | Property | Required | Description | | ||
| | -- | -- | -- | | ||
| | filename | Required | Filename of `.yml` file must match component partial name | |
andysellick
Aug 7, 2017
Contributor
Would an example of a filename be helpful?
Would an example of a filename be helpful?
fofr
Aug 7, 2017
Author
Contributor
Added in paragraph above.
Added in paragraph above.
| The link must: | ||
| * be keyboard focuasable |
andysellick
Aug 7, 2017
Contributor
focuasable
focuasable
fofr
Aug 7, 2017
Author
Contributor
Fixed.
Fixed.
| fixtures: | ||
| default: | ||
| some_parameter: 'The parameter value' | ||
| ``` |
andysellick
Aug 7, 2017
Contributor
Fixtures could perhaps use some more explaining. Maybe link to an example?
Fixtures could perhaps use some more explaining. Maybe link to an example?
fofr
Aug 7, 2017
Author
Contributor
I agree. We have a placeholder story for that:
https://trello.com/c/fgKpFA3n/152-rename-fixtures-to-examples-and-add-documentation
I agree. We have a placeholder story for that:
https://trello.com/c/fgKpFA3n/152-rename-fixtures-to-examples-and-add-documentation
| * defines a convention for components to follow | ||
| * lints components for consistent coding style | ||
| * makes it easy to build, move or delete components | ||
| * makes it easy to arrange or compose components without glue code |
andysellick
Aug 7, 2017
Contributor
Worth a brief definition of 'glue code'?
Worth a brief definition of 'glue code'?
fofr
Aug 7, 2017
Author
Contributor
Updated wording.
Updated wording.
| * [follows convention](component_conventions.md) | ||
| * is isolated | ||
| * is tested | ||
| * can be translated |
andysellick
Aug 7, 2017
Contributor
We've not talked about this much since starting this component work. Is there something we can link to here to give a bit more detail about how translations should be handled in applications?
We've not talked about this much since starting this component work. Is there something we can link to here to give a bit more detail about how translations should be handled in applications?
fofr
Aug 7, 2017
Author
Contributor
Not yet. You're right that it needs expansion. Maybe add an issue?
Not yet. You're right that it needs expansion. Maybe add an issue?
andysellick
Aug 7, 2017
Contributor
Added.
Added.
| * makes it easy to build, move or delete components | ||
| * makes it easy to arrange or compose components without glue code | ||
| * makes components discoverable | ||
| * hides the internal implementation of a component from applications |
andysellick
Aug 7, 2017
Contributor
I wonder if this needs further definition - I know I benefitted greatly once the understanding of why passing a class into a component for it to use was a bad idea.
I wonder if this needs further definition - I know I benefitted greatly once the understanding of why passing a class into a component for it to use was a bad idea.
nickcolley
Aug 7, 2017
Contributor
Seems like this and the 'glue code' example could benefit from the real world examples we've come across?
Seems like this and the 'glue code' example could benefit from the real world examples we've come across?
fofr
Aug 7, 2017
Author
Contributor
Good point. I've added it to this story:
https://trello.com/c/Lr4NFB7f/146-docs-on-how-to-build-good-component-api-and-pass-data
Good point. I've added it to this story:
https://trello.com/c/Lr4NFB7f/146-docs-on-how-to-build-good-component-api-and-pass-data
|
|
||
| ## Write components in your application | ||
|
|
||
| Components are packages of template, style, behaviour and documentation that live in your application. |
andysellick
Aug 7, 2017
Contributor
This is nit-picking, I know, but can we really describe a set of files in different directories as a package? Perhaps an 'associated group of files'?
This is nit-picking, I know, but can we really describe a set of files in different directories as a package? Perhaps an 'associated group of files'?
fofr
Aug 7, 2017
Author
Contributor
Package is fine I think, and terser than 'associated group of files'. If the component files aren't grouped well enough then the problem isn't a naming one.
Package is fine I think, and terser than 'associated group of files'. If the component files aren't grouped well enough then the problem isn't a naming one.
| * [meet the component principles](docs/component_principles.md) | ||
| * [follow component conventions](docs/component_conventions.md) | ||
|
|
||
| A lead-paragraph component would be included in a template like this: |
andysellick
Aug 7, 2017
Contributor
No need for hyphen in 'lead paragraph'.
No need for hyphen in 'lead paragraph'.
fofr
Aug 7, 2017
Author
Contributor
Fixed 🎩
Fixed
* Link to GOV.UK frontend where appropriate * Explain namespacing * Clarify component structure and documentation
* Move component details to the top, but link out to the important parts for reference * Group set up and configuration under “Set up a component guide”
