Create a component guide based on components in an application #1

fofr · 2017-07-19T16:20:24Z

Part of:
https://trello.com/c/SD6M3IUF/12-3-create-a-component-guide-that-can-document-components-in-apps

Not all components should be in static. If they are used only in one application it is preferable to keep them close to the point of use.

Initial release:

Allow applications to create components
Components follow the same file structure as static components
Component guide is generated from docs and partials living in app/views/components/docs and app/views/components
An example of how to use this gem: https://github.com/alphagov/government-frontend/compare/components-gem
Component guide logic, templates and styles ported from https://github.com/alphagov/govuk-component-guide and http://govuk-component-guide.herokuapp.com/
Includes basic integration tests

See README.md for further details.

Still to do but can be separate PRs:

Syntax highlighting
Component guide styles should be components themselves
Further documentation on components and principles
Component previews that render just the component (ie no GOV.UK frame around it)

* Add wrapper ID to allow slimmer to run insertion correctly * Add sass, toolkit and slimmer dependencies * Create index route, controller and view

Use models, logic and styles from https://github.com/alphagov/govuk-component-guide. Docs structure will be identical. * Render a list of components based on docs in the `app/views/components/docs` directory of the host app * Display a component with a set of test fixtures based on those docs * Include those partials in the view path * Use breadcrumbs component for navigating the guide * Use a less verbose component call for using a partial

* Use same configuration pattern as govuk_admin_template

Add webmock dependency and require webmock as it does not come with Slimmer. Issue raised here: alphagov/slimmer#201

* It ought to work with the version a host app uses * Require in engine

* Confirm that the component guide index loads

* Lint Ruby and Sass * Fix linting errors

Default both to rails convention, “application”

* Give each page a unique title based on guide name, component and fixture * Give each page a breadcrumb that matches the guide name * Use the guide name as the h1 on the index

tijmenb · 2017-07-20T10:47:12Z

Gemfile.lock

@@ -2,7 +2,10 @@ PATH
  remote: .


The Gemfile.lock shouldn't be committed for gems.

Thanks, removed in 32895dd

andysellick

As requested, I've focussed on the documentation for this review.

andysellick · 2017-07-20T12:16:01Z

README.md

+* a unit test in `/test/components` - testing the component renders correctly based on parameters passed in
+
+The component guide will include your application’s styles and scripts. It will include `application.scss` and `application.js` by default but this is [configurable](#configuration).
+


Should there be a line or two in here about how to call/use a component? I guess it's already going to be in the component guide though.

I think it's worth adding one or two lines.

andysellick · 2017-07-20T12:16:01Z

README.md


-## Installation
-Add this line to your application's Gemfile:
+Add this line to your application's Gemfile in the development and test groups:


As someone new to this, I don't know what the "development and test groups" are, so I'd be stuck on this step.

andysellick · 2017-07-20T12:16:01Z

README.md

+unless Rails.env.production?
+  mount GovukPublishingComponents::Engine, at: "/component-guide"
+end
+```


Is this a change that once done is okay to commit to that application? If so, presumably over time eventually all apps will have this already. Some clarification/expansion needed here?

andysellick · 2017-07-20T12:16:01Z

README.md

+
+`govuk_publishing_components` expects the following components structure in your application:
+
+* a Partial View in `app/views/components` eg `_component-name.html.erb` - The template logic and markup, also defines the arguments expected


Having an example file name here is helpful - can example file names also be added for the following items as well?

vanitabarrett · 2017-07-20T12:22:06Z

README.md

+* Documentation in `/app/views/components/docs` - a `.yml` per component, describing the component and containing fixture data.
+* a SCSS module in `app/assets/stylesheets/components` - The styling of the component
+* a Javascript module in `app/assets/javascripts/components` - JS behaviour of the component
+* a unit test in `/test/components` - testing the component renders correctly based on parameters passed in


Is it worth pointing people towards an example component somewhere, so they can see exactly what you mean by the above points? Things like 'defines the arguments expected' - it may not be immediately obvious to everyone exactly how this is done?

Also, even though we're not giving people a comprehensive guide on how to write a component here, it might still be worth linking to our component principles?

Yes, definitely. Holding off doing this until we have one to link to.

andysellick · 2017-07-20T12:31:08Z

README.md

@@ -16,13 +15,63 @@ And then execute:
 $ bundle
 ```


Where should these commands be executed?

These are the standard Rails "How to install gem" instructions.

andysellick · 2017-07-20T13:21:46Z

README.md

+
+### Configuration
+
+You can configure the gem with a config block in an initializer:


Remove 'you can'.

* Allow use of standard Jenkinsfile by passing `assets:clean` and `assets:precompile` through to dummy application.

fofr · 2017-07-20T14:14:27Z

README updated in b929dd2

alecgibson · 2017-07-20T16:55:31Z

README.md

+#### Example documentation
+
+```yaml
+name: Withdrawal notice


(Just a thought, but it might be nice with all of these examples to demonstrate a single component? Then you can see the process all the way through for one thing. Above for your <%= render example, you use descriptions; for the path examples you use a print link; here you're using a withdrawal notice)

Good point. When we've written some I'll link directly to the files in other apps.

alecgibson · 2017-07-20T16:55:31Z

README.md

+The `.yml` file must have:
+* a name
+* a description
+* a default fixture (this can be `{}` if the component takes no parameters)


It might be nice to expand on what a "default" fixture is? And what a fixture that isn't default is?

I agree. My intention is to fix this, so a component without any fixtures does not take parameters. And an "empty parameter" option can be easily illustrated. Was going to do this as a separate PR.

alecgibson · 2017-07-20T16:55:31Z

README.md

+```ruby
+# config/initializers/govuk_publishing_components.rb
+GovukPublishingComponents.configure do |c|
+  c.component_guide_title = "My component guide"


What's the use case for being able to configure this?

Unique titles for component guides in different apps.

See: https://github.com/alphagov/government-frontend/pull/403/files#diff-bb6adab3eaf25dfc303b4f34455f5be9R2

I understand what it does, but why would we want to do this?

Because each guide will be different. Each guide will have different components.

alecgibson · 2017-07-20T16:55:31Z

app/controllers/govuk_publishing_components/component_guide_controller.rb

+    def fixture
+      @component_doc = ComponentDoc.get(params[:component])
+      @component_fixture = @component_doc.fixtures.find { |f| f.id == params[:fixture] }
+      @guide_breadcrumbs = [


It might be nice to break these breadcrumbs out into their own little method.

Added in 84537ad

alecgibson · 2017-07-20T16:55:31Z

app/models/govuk_publishing_components/component_doc.rb

@@ -0,0 +1,34 @@
+module GovukPublishingComponents
+  ComponentDoc = Struct.new(:id, :name, :description, :body, :fixtures) do


This class has a lot of collection-level functionality, which feels like it should belong in another separate singleton class that has the ability to memoize things properly, and deliver things from hashes rather than performing find operations.

This logic has largely been ported from https://github.com/alphagov/govuk-component-guide/

https://github.com/alphagov/govuk-component-guide/blob/master/app/models/component.rb

I've avoided significant refactoring to keep the two guides similar for now.

alecgibson · 2017-07-20T16:55:31Z

app/models/govuk_publishing_components/component_doc.rb

+      fixtures.slice(1..-1)
+    end
+
+    def self.fetch_component_doc


fetch_component_docs (plural)?

Fixed in d723a47

alecgibson · 2017-07-20T16:55:31Z

app/models/govuk_publishing_components/component_fixture.rb

+    end
+
+    def pretty_data
+      JSON.pretty_generate(data).gsub('\\n', "\n    ").gsub(/"(\w*)":/, '\1:').strip


When performing this sort of gsub wizardry, it's often nice to break it out into a one-line mutating method with a nice name so that people can understand what's going on, eg:

def pretty_data prettified = JSON.pretty_generate(data) prepend_new_lines_with_whitespace!(prettified) unquote_properties!(prettified) prettified end

On that note, just why are we doing these things? To make a Ruby-looking hash? In that case maybe we should be using a gem? Or at least rename this method to something like data_as_pretty_printed_ruby_hash?

Another ported model from here:
https://github.com/alphagov/govuk-component-guide/blob/master/app/models/fixture.rb#L7

It creates a hash that can be put into a <pre> block with correct formatting. I agree the naming should be better.

alecgibson · 2017-07-20T16:55:31Z

app/models/govuk_publishing_components/component_doc.rb

+    end
+
+    def fixture
+      fixtures.first


This doesn't necessarily grab the "default" fixture - is that what we want?

This relies on convention, you’re right. I think this is ok for now. The convention of putting default first in the fixtures hasn't been an issue with static components.

The alternative would be to lookup via the default ID – if this was left out what should the guide page do? At the moment it'd fallback to the next fixture.

I think when there's a component generator this convention will be natural too.

alecgibson · 2017-07-20T16:55:31Z

app/views/govuk_publishing_components/component_guide/show.html.erb

+
+<div class="component-show">
+  <div class="component-doc">
+    <h3>How to call this component</h3>


(This view and the fixture view share a bit of code in common. I don't know if it's possible to commonise through a partial?)

* DRYup breadcrumbs in component guide

* There are many documents and components

binaryberry

Nothing to add to existing comments - fine by me once they have been addressed

fofr · 2017-07-21T10:29:11Z

Plan regarding logic and review comments is to:

Integrate this gem into the govuk-component-guide and remove duplicate logic: https://trello.com/c/GtIEFBfC/
Then refactor

fofr added 15 commits Jul 5, 2017

Stub a component index

a1d9319

* Add wrapper ID to allow slimmer to run insertion correctly * Add sass, toolkit and slimmer dependencies * Create index route, controller and view

Let applications declare their app title

bf8a162

* Use same configuration pattern as govuk_admin_template

Add capybara for integration testing

9d0515b

Load slimmer test helpers

752ee4d

Add webmock dependency and require webmock as it does not come with Slimmer. Issue raised here: alphagov/slimmer#201

Loosen dependency on govuk_frontend_toolkit

c373a39

* It ought to work with the version a host app uses * Require in engine

Add integration test for component guide

344123a

* Confirm that the component guide index loads

Add component integration test

d17b2c4

Add component with params integration test

bfda529

Test component guide includes app assets and own

d503539

Add test for component fixture pages

b74bb2c

Add govuk-lint

d776e0b

* Lint Ruby and Sass * Fix linting errors

Make :spec the default rake task

93ba2fe

Allow application stylesheet and script to be customised

d5ba161

Default both to rails convention, “application”

Unique titles and breadcrumbs

d8bf5ca

* Give each page a unique title based on guide name, component and fixture * Give each page a breadcrumb that matches the guide name * Use the guide name as the h1 on the index

fofr force-pushed the living-style-guide branch from 43611f5 to dd857ee Jul 19, 2017

fofr changed the title ~~Create a component guide based on components in application~~ Create a component guide based on components in an application Jul 19, 2017

tijmenb reviewed Jul 20, 2017

View changes

andysellick reviewed Jul 20, 2017

View changes

vanitabarrett reviewed Jul 20, 2017

View changes

andysellick reviewed Jul 20, 2017

View changes

README.md Outdated

### Configuration

You can configure the gem with a config block in an initializer:

This comment has been minimized.

Sign in to view

andysellick Jul 20, 2017
Contributor

Remove 'you can'.

fofr added 4 commits Jul 19, 2017

Add readme and changelog

b929dd2

Remove unused active_record references

a2594f7

Test precompiling assets through dummy application

22a25ad

* Allow use of standard Jenkinsfile by passing `assets:clean` and `assets:precompile` through to dummy application.

Don't include Gemfile.lock with gem

Loading status checks…

eaca410

fofr force-pushed the living-style-guide branch from 32895dd to eaca410 Jul 20, 2017

fofr requested review from binaryberry and alecgibson Jul 20, 2017

alecgibson reviewed Jul 20, 2017

View changes

fofr added 2 commits Jul 21, 2017

Separate breadcrumb logic into methods

Loading status checks…

84537ad

* DRYup breadcrumbs in component guide

Pluralise component docs method

Loading status checks…

d723a47

* There are many documents and components

binaryberry approved these changes Jul 21, 2017

View changes

fofr merged commit fb044bd into master Jul 21, 2017
1 check passed

1 check passed

continuous-integration/jenkins/branch This commit looks good
Details

fofr deleted the living-style-guide branch Jul 21, 2017

fofr mentioned this pull request Aug 17, 2017

Split ComponentDoc into ComponentDoc and ComponentDocResolver #34

Merged

		* a unit test in `/test/components` - testing the component renders correctly based on parameters passed in

		The component guide will include your application’s styles and scripts. It will include `application.scss` and `application.js` by default but this is [configurable](#configuration).


		`govuk_publishing_components` expects the following components structure in your application:

		* a Partial View in `app/views/components` eg `_component-name.html.erb` - The template logic and markup, also defines the arguments expected


		### Configuration

		You can configure the gem with a config block in an initializer:

		@@ -0,0 +1,34 @@
		module GovukPublishingComponents
		ComponentDoc = Struct.new(:id, :name, :description, :body, :fixtures) do

alphagov / govuk_publishing_components

Create a component guide based on components in an application #1

Create a component guide based on components in an application #1

Conversation

fofr commented Jul 19, 2017 • edited

This comment has been minimized.

tijmenb Jul 20, 2017 Contributor

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

andysellick left a comment

This comment has been minimized.

andysellick Jul 20, 2017 Contributor

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

This comment has been minimized.

andysellick Jul 20, 2017 Contributor

This comment has been minimized.

andysellick Jul 20, 2017 Contributor

This comment has been minimized.

andysellick Jul 20, 2017 Contributor

This comment has been minimized.

vanitabarrett Jul 20, 2017 Contributor

This comment has been minimized.

vanitabarrett Jul 20, 2017 Contributor

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

This comment has been minimized.

andysellick Jul 20, 2017 Contributor

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

This comment has been minimized.

andysellick Jul 20, 2017 Contributor

fofr commented Jul 20, 2017

This comment has been minimized.

This comment has been minimized.

fofr Jul 20, 2017 • edited Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

This comment has been minimized.

fofr Jul 21, 2017 Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 21, 2017 Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 21, 2017 Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 20, 2017 • edited Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 21, 2017 Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 20, 2017 Author Contributor

This comment has been minimized.

This comment has been minimized.

fofr Jul 21, 2017 Author Contributor

This comment has been minimized.

binaryberry left a comment

fofr commented Jul 21, 2017

fofr commented Jul 19, 2017 •

edited

tijmenb Jul 20, 2017
Contributor

fofr Jul 20, 2017
Author Contributor

andysellick Jul 20, 2017
Contributor

fofr Jul 20, 2017
Author Contributor

andysellick Jul 20, 2017
Contributor

andysellick Jul 20, 2017
Contributor

andysellick Jul 20, 2017
Contributor

vanitabarrett Jul 20, 2017
Contributor

vanitabarrett Jul 20, 2017
Contributor

fofr Jul 20, 2017
Author Contributor

andysellick Jul 20, 2017
Contributor

fofr Jul 20, 2017
Author Contributor

andysellick Jul 20, 2017
Contributor

fofr Jul 20, 2017 •

edited

Author Contributor

fofr Jul 20, 2017
Author Contributor

fofr Jul 20, 2017
Author Contributor

fofr Jul 21, 2017
Author Contributor

fofr Jul 21, 2017
Author Contributor

fofr Jul 21, 2017
Author Contributor

fofr Jul 20, 2017 •

edited

Author Contributor

fofr Jul 21, 2017
Author Contributor

fofr Jul 20, 2017
Author Contributor

fofr Jul 21, 2017
Author Contributor