From 46e4a4a7960e8292f73bfb5ccdd9cb401935ab82 Mon Sep 17 00:00:00 2001 From: David Singleton Date: Thu, 21 Aug 2014 16:20:48 +0000 Subject: [PATCH 1/5] Add documentation on GOV.UK Components Static is the authorative source for components, including documentation, so should be included here. - As this grows it might want to be split into a README in a components specific directory, tho a good one doesn't exist yet - It might be worth creating a generator to do the creation, just docing for now --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/README.md b/README.md index ff1968bfe..0b1407a6a 100644 --- a/README.md +++ b/README.md @@ -28,3 +28,52 @@ To run this app locally, and have it point at its own assets, run it like this: ``` PLEK_SERVICE_STATIC_URI=0.0.0.0:3013 ./startup.sh ``` + +## GOV.UK components + +Shared partials that encapsulate the HTML/CSS/JS for a common UI component. +The component files are centrally hosted on static and exposed to applicatins via [alphagov/slimmer](https://github.com/alphagov/slimmer). +The partial is exposed over the network, and the CSS/JS are included by the shared templated layout. + +The available compoents and their documentation are exposed by an API at `/templates/govuk_component/docs`, which is consumed by +[alphagov/govuk_component_guide](https://github.com/alphagov/govuk_component_guide) to generate a living styleguide for components. + + +* a [Partial View](app/views/govuk_component) - The template logic and markup, also defines the arguements expected +* a [SCSS module](app/assets/stylesheets/govuk-component) - The styling of the component +* a Javascript module - no examples yet. +* Documentation - currenly in a [static/central file](app/views/govuk_component/docs.json), this will generated dynamically in the future (something like) + +### Creating a new component + +First pick a name. Components should be lowercase and hyphenated, eg `your-compontent-name`. + +When referenced from an application as a partial they'll be prefixed with `govuk-`, eg `govuk-your-compontent-name`. To match rails view convention the partial itself should use an underscore, rather than a hyphen. + +1) Create a new partial at `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class that's the same as a prefixed component name, eg +``` +
+

things

+
+``` + +2) Create a new SCSS module at `app/stylesheets/govuk-component/_your-compontent-name.scss` - there should be a single root class, the same class on the root of the partial, eg +``` +.govuk-your-compontent-name { + // CSS rules go here. + p { + // scoped rules + } +} +``` + +3) Include the new SCSS module in to `app/stylesheets/govuk-component/_component.scss` + +4) Add documentation to `app/views/govuk_component/docs.json` - this is in the form of an array of hashes: +* `id`: The underscore version of the compontent name +* `name`: The human name, eg, `Your Example Component` +* `description`: A longer form description of what the component does, when it should be used +* `fixtures`: TBD: For components that expect aguements this will be a hash of fixtured example arguments + +Adding it to the documentation will allow you to preview it in the `govuk_component_guide`, which can be pointed to any +version of startic, including your local one running a branch. Which you should probably do. From f50f57cc28f5c22c92c8366ecb77d9b5742e054a Mon Sep 17 00:00:00 2001 From: David Singleton Date: Thu, 21 Aug 2014 17:19:07 +0000 Subject: [PATCH 2/5] Add a rails generator for GOV.UK components Generates all the file scaffolding, in the right places, as the files are a bit spread throughout static at the moment. This will include all the files required to let the component be demo'd on govuk-component Appending to the json docs file is a bit shonky, but we're not planning on using that as a docs method long term. It'll likely be inline with template, or at least one doc file per component, which will make this simpler. --- lib/generators/govuk_component/USAGE | 5 ++++ .../govuk_component_generator.rb | 26 +++++++++++++++++++ .../govuk_component/templates/_component.scss | 3 +++ .../templates/component.html.erb | 3 +++ 4 files changed, 37 insertions(+) create mode 100644 lib/generators/govuk_component/USAGE create mode 100644 lib/generators/govuk_component/govuk_component_generator.rb create mode 100644 lib/generators/govuk_component/templates/_component.scss create mode 100644 lib/generators/govuk_component/templates/component.html.erb diff --git a/lib/generators/govuk_component/USAGE b/lib/generators/govuk_component/USAGE new file mode 100644 index 000000000..4aec0ffee --- /dev/null +++ b/lib/generators/govuk_component/USAGE @@ -0,0 +1,5 @@ +Description: + Generates a new GOV.UK component + +Example: + rails generate govuk_component [compontent_name] diff --git a/lib/generators/govuk_component/govuk_component_generator.rb b/lib/generators/govuk_component/govuk_component_generator.rb new file mode 100644 index 000000000..962b3e261 --- /dev/null +++ b/lib/generators/govuk_component/govuk_component_generator.rb @@ -0,0 +1,26 @@ +require 'json' + +class GovukComponentGenerator < Rails::Generators::NamedBase + source_root File.expand_path('../templates', __FILE__) + + def copy_component_files + @public_name = file_name.dasherize + + template 'component.html.erb', "app/views/govuk_component/#{file_name}.raw.html.erb" + template '_component.scss', "app/assets/stylesheets/govuk-component/_#{@public_name}.scss" + + append_to_file "app/assets/stylesheets/govuk-component/_component.scss", "@import \"#{@public_name}\";\n" + + docs_path = 'app/views/govuk_component/docs.json' + docs = JSON.parse(IO.read(docs_path)) + File.open(docs_path, 'w') do |file| + docs.push({ + "id" => file_name, + "name" => human_name, + "description" => "", + "fixtures" => {} + }) + file.write(JSON.pretty_generate(docs)) + end + end +end diff --git a/lib/generators/govuk_component/templates/_component.scss b/lib/generators/govuk_component/templates/_component.scss new file mode 100644 index 000000000..441744bc3 --- /dev/null +++ b/lib/generators/govuk_component/templates/_component.scss @@ -0,0 +1,3 @@ +.govuk-<%= @public_name %> { + +} diff --git a/lib/generators/govuk_component/templates/component.html.erb b/lib/generators/govuk_component/templates/component.html.erb new file mode 100644 index 000000000..18dc7f579 --- /dev/null +++ b/lib/generators/govuk_component/templates/component.html.erb @@ -0,0 +1,3 @@ +
+ <%= human_name %> +
From b722da65bda2f0104b102993b14414ab7ce01117 Mon Sep 17 00:00:00 2001 From: David Singleton Date: Thu, 28 Aug 2014 11:08:32 +0000 Subject: [PATCH 3/5] Make the GOV.UK component doc fixture structure clearer Fixtures are a hash of hashes, the parent hash is fixture_name => fixture The fixture is a hash of locals to be passed to the compontent view. --- app/views/govuk_component/docs.json | 5 ++++- lib/generators/govuk_component/govuk_component_generator.rb | 4 +++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/app/views/govuk_component/docs.json b/app/views/govuk_component/docs.json index b6bb19bfb..899bbc910 100644 --- a/app/views/govuk_component/docs.json +++ b/app/views/govuk_component/docs.json @@ -3,7 +3,10 @@ "id": "beta_label", "name": "Beta Banner", "description": "A banner than indicates content is in a beta phase", - "fixtures": {} + "fixtures": { + "default": { + } + } }, { "id": "metadata", diff --git a/lib/generators/govuk_component/govuk_component_generator.rb b/lib/generators/govuk_component/govuk_component_generator.rb index 962b3e261..7b830b1d8 100644 --- a/lib/generators/govuk_component/govuk_component_generator.rb +++ b/lib/generators/govuk_component/govuk_component_generator.rb @@ -18,7 +18,9 @@ def copy_component_files "id" => file_name, "name" => human_name, "description" => "", - "fixtures" => {} + "fixtures" => { + "default" => {} + } }) file.write(JSON.pretty_generate(docs)) end From 0df3225835fc6be0255c436568d7e02f28ae352f Mon Sep 17 00:00:00 2001 From: David Singleton Date: Thu, 28 Aug 2014 14:15:41 +0000 Subject: [PATCH 4/5] Update readme to include component generator --- README.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0b1407a6a..88d654bd8 100644 --- a/README.md +++ b/README.md @@ -38,26 +38,35 @@ The partial is exposed over the network, and the CSS/JS are included by the shar The available compoents and their documentation are exposed by an API at `/templates/govuk_component/docs`, which is consumed by [alphagov/govuk_component_guide](https://github.com/alphagov/govuk_component_guide) to generate a living styleguide for components. - * a [Partial View](app/views/govuk_component) - The template logic and markup, also defines the arguements expected * a [SCSS module](app/assets/stylesheets/govuk-component) - The styling of the component * a Javascript module - no examples yet. -* Documentation - currenly in a [static/central file](app/views/govuk_component/docs.json), this will generated dynamically in the future (something like) +* Documentation - currently in a [static/central file](app/views/govuk_component/docs.json), this will generated dynamically in the future ### Creating a new component -First pick a name. Components should be lowercase and hyphenated, eg `your-compontent-name`. +There's a rails generator you can use to create the basic compontent files, but it's recommended you read below to understand how it works as well. + +``` +bundle exec rails generate govuk_component [your-component-name] +``` + +### How components are structured + +Component names should be lowercase and hyphenated, eg `your-compontent-name`. + +When referenced from an application as a partial they'll be prefixed with `govuk-`, eg `govuk-your-compontent-name`. -When referenced from an application as a partial they'll be prefixed with `govuk-`, eg `govuk-your-compontent-name`. To match rails view convention the partial itself should use an underscore, rather than a hyphen. +To match rails view convention the partial itself should use an underscore, rather than a hyphen. -1) Create a new partial at `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class that's the same as a prefixed component name, eg +1) views live in `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class that's the same as a prefixed component name, eg ```

things

``` -2) Create a new SCSS module at `app/stylesheets/govuk-component/_your-compontent-name.scss` - there should be a single root class, the same class on the root of the partial, eg +2) There is a SCSS module at `app/stylesheets/govuk-component/_your-compontent-name.scss` - there should be a single root class, the same class on the root of the partial, eg ``` .govuk-your-compontent-name { // CSS rules go here. @@ -67,9 +76,9 @@ When referenced from an application as a partial they'll be prefixed with `govuk } ``` -3) Include the new SCSS module in to `app/stylesheets/govuk-component/_component.scss` +3) SCSS modules are included in `app/stylesheets/govuk-component/_component.scss` - which is used in the standard static layout SCSS files (application.scss, header_footer_only.scss) -4) Add documentation to `app/views/govuk_component/docs.json` - this is in the form of an array of hashes: +4) Documentation lives `app/views/govuk_component/docs.json` - this is in the form of an array of hashes: * `id`: The underscore version of the compontent name * `name`: The human name, eg, `Your Example Component` * `description`: A longer form description of what the component does, when it should be used From c9a56ef68bcb322038df489eced7de74d3f8021a Mon Sep 17 00:00:00 2001 From: Richard Boulton Date: Fri, 29 Aug 2014 17:32:44 +0100 Subject: [PATCH 5/5] Fix typos and confusing wording in README --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 88d654bd8..81e0acaab 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Other related repositories: * [alphagov/govuk_frontend_toolkit](https://github.com/alphagov/govuk_frontend_toolkit) - an SCSS toolkit for building responsive and cross-browser friendly web sites * [alphagov/slimmer](https://github.com/alphagov/slimmer) - Rack middleware for wrapping Rack applications in shared templated layouts -##Javascript unit tests +## Javascript unit tests To run the unit tests in batch use the jasmine:ci rake task, but it must be run in the test environment: `RAILS_ENV=test rake jasmine:ci`. @@ -32,20 +32,20 @@ PLEK_SERVICE_STATIC_URI=0.0.0.0:3013 ./startup.sh ## GOV.UK components Shared partials that encapsulate the HTML/CSS/JS for a common UI component. -The component files are centrally hosted on static and exposed to applicatins via [alphagov/slimmer](https://github.com/alphagov/slimmer). +The component files are centrally hosted on static and exposed to applications via [alphagov/slimmer](https://github.com/alphagov/slimmer). The partial is exposed over the network, and the CSS/JS are included by the shared templated layout. -The available compoents and their documentation are exposed by an API at `/templates/govuk_component/docs`, which is consumed by +The available components and their documentation are exposed by an API at `/templates/govuk_component/docs`, which is consumed by [alphagov/govuk_component_guide](https://github.com/alphagov/govuk_component_guide) to generate a living styleguide for components. -* a [Partial View](app/views/govuk_component) - The template logic and markup, also defines the arguements expected +* a [Partial View](app/views/govuk_component) - The template logic and markup, also defines the arguments expected * a [SCSS module](app/assets/stylesheets/govuk-component) - The styling of the component * a Javascript module - no examples yet. * Documentation - currently in a [static/central file](app/views/govuk_component/docs.json), this will generated dynamically in the future ### Creating a new component -There's a rails generator you can use to create the basic compontent files, but it's recommended you read below to understand how it works as well. +There's a rails generator you can use to create the basic component files, but it's recommended you read below to understand how it works as well. ``` bundle exec rails generate govuk_component [your-component-name] @@ -53,22 +53,22 @@ bundle exec rails generate govuk_component [your-component-name] ### How components are structured -Component names should be lowercase and hyphenated, eg `your-compontent-name`. +Component names should be lowercase and hyphenated. For example: `your-component-name`. -When referenced from an application as a partial they'll be prefixed with `govuk-`, eg `govuk-your-compontent-name`. +When referenced from an application as a partial they'll be prefixed with `govuk-`. For example: `govuk-your-component-name`. To match rails view convention the partial itself should use an underscore, rather than a hyphen. -1) views live in `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class that's the same as a prefixed component name, eg +1) views live in `app/views/govuk_component/your_compontent_name.raw.html.erb` - There should be a single root element, with a class name consisting of the prefixed component name. For example: ``` -
+

things

``` -2) There is a SCSS module at `app/stylesheets/govuk-component/_your-compontent-name.scss` - there should be a single root class, the same class on the root of the partial, eg +2) There is a SCSS module at `app/stylesheets/govuk-component/_your-component-name.scss` - there should be a single root class, the same class on the root of the partial. For example: ``` -.govuk-your-compontent-name { +.govuk-your-component-name { // CSS rules go here. p { // scoped rules @@ -79,10 +79,10 @@ To match rails view convention the partial itself should use an underscore, rath 3) SCSS modules are included in `app/stylesheets/govuk-component/_component.scss` - which is used in the standard static layout SCSS files (application.scss, header_footer_only.scss) 4) Documentation lives `app/views/govuk_component/docs.json` - this is in the form of an array of hashes: -* `id`: The underscore version of the compontent name -* `name`: The human name, eg, `Your Example Component` +* `id`: The underscore version of the component name +* `name`: The human name. eg, `Your Example Component` * `description`: A longer form description of what the component does, when it should be used -* `fixtures`: TBD: For components that expect aguements this will be a hash of fixtured example arguments +* `fixtures`: TBD: For components that expect arguments this will be a hash of fixtured example arguments Adding it to the documentation will allow you to preview it in the `govuk_component_guide`, which can be pointed to any -version of startic, including your local one running a branch. Which you should probably do. +version of static, including your local one running a branch. Which you should probably do.