Merge pull request #76 from DFE-Digital/version-1.1.0

.travis.yml

@@ -1,19 +1,20 @@
 language: ruby
 
-cache: bundler
+# cache: bundler
 
 rvm:
-  - 2.5.6
-  - 2.6.4
+  - 2.5.7
+  - 2.6.5
+  - 2.7.0
 
 script:
   - make ruby-lint
   - make rspec
   - make nanoc-check-all
 
 env:
-  - RAILS_VERSION=5.2.3
-  - RAILS_VERSION=6.0.0
+  - RAILS_VERSION=5.2.4
+  - RAILS_VERSION=6.0.2
 
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter

Makefile

@@ -16,12 +16,16 @@ nanoc-check-internal:
 	${guide_dir} ${prefix} nanoc check ${nanoc_internal_checks}
 nanoc-check-external:
 	${guide_dir} ${prefix} nanoc check ${nanoc_external_checks}
-nanoc-check-all: build_guide
+nanoc-check-all: build-guide
 	${guide_dir} ${prefix} nanoc check ${nanoc_internal_checks} ${nanoc_external_checks}
 build:
 	${prefix} gem build govuk_design_system_formbuilder.gemspec
-build_guide: npm-install
+build-guide: npm-install
 	${guide_dir} ${prefix} nanoc
+watch-guide: npm-install
+	${guide_dir} ${prefix} nanoc view --live-reload --port 3006 --color
+keep-building-guide:
+	${guide_dir} fd -e rb -eslim -esass -ejs -p guide | entr nanoc
 docs-server:
 	yard server --reload
 code-climate:

govuk_design_system_formbuilder.gemspec

@@ -43,6 +43,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency("htmlbeautifier", "~> 1.3.1")
   s.add_development_dependency("nanoc", "~> 4.11")
   s.add_development_dependency("rouge", "~> 3.13.0")
+  s.add_development_dependency("rubypants", "~> 0.7.0")
   s.add_development_dependency("sassc", "~> 2.2.1")
   s.add_development_dependency("sass")
   s.add_development_dependency("slim", "~> 4.0.1")

guide/Rules

@@ -7,6 +7,7 @@ end
 compile '/**/*.slim' do
   filter :slim
   filter :colorize_syntax, default_colorizer: :rouge
+  filter :rubypants
   layout '/default.*'
   write item.identifier.without_ext + '/index.html'
 end

guide/content/building-blocks/localisation.slim

@@ -0,0 +1,76 @@
+---
+title: Localisation
+---
+
+h1.govuk-heading-xl Localisation
+
+p.govuk-body
+  | The simplest way of adding textual information like labels and hints to
+    forms is to provide strings as arguments to the form helpers.
+
+.code-sample
+  pre
+    code.highlight.language-ruby
+      | = f.govuk_text_field :name, label: { text: "Your full name" }
+
+p.govuk-body
+  | On larger, more-complex projects, copy is spread throughout the application
+    and often duplicated, making it difficult for content designers to make
+    changes.
+
+p.govuk-body
+  | Many teams approach this problem by making use of
+    #{link_to("Rails' excellent localisation functionality", rails_localisation_link).html_safe},
+    allowing text to be stored in locale dictionaries. This allows editors to
+    make changes without the risk of breaking templates and having to learn
+    templating languages and hunt down content.
+
+section
+
+  == render('/partials/example-fig.*',
+    caption: "Populating label and hint text from the localisation data",
+    localisation: favourite_kind_of_hat_locale,
+    code: favourite_kind_of_hat) do
+
+    p.govuk-body
+      | Note that despite the <code>text</code> attribute being omitted from
+        the label options hash, the other display and formatting parameters
+        can be supplied and work in the normal manner.
+
+  == render('/partials/example-fig.*',
+    caption: "Customising locale structure",
+    localisation: custom_locale,
+    code: role_name,
+    custom_config: custom_locale_config,
+    raw_config: custom_locale_config_raw,
+    hide_html_output: true) do
+
+    p.govuk-body
+      | There are many approaches to organising localisation data and while the default
+        will work for most projects, sometimes a different approach can be beneficial. This
+        is especially true when working with external localisation agencies or when dealing
+        with large volumes of copy.
+
+    p.govuk-body
+      | To customise the location of our localisation strings, we can
+        #{link_to('configure', '/introduction/configuration').html_safe} the schema as
+        part of the application's initialisation process.
+
+    h4.govuk-heading-s Contexts
+
+    p.govuk-body
+      | There are three contexts supported by the form builder: <em>label</em>,
+        <em>legend</em> and <em>hint</em>. Custom locale schemas are
+        configured using an array of symbols that match your locale structure.
+
+    p.govuk-body
+      | The special value <code>__context__</code> is used to represent the
+        current translation context. It will automatically be replaced with
+        either <em>label</em>, <em>legend</em> or <em>hint</em> when the
+        translation key is generated.
+
+    p.govuk-body
+      | When retrieving a localised string the builder first checks whether
+        a contextual schema has been set for the context. If there hasn't,
+        the <code>localisation_schema_fallback</code> key will be used. <strong>It is
+        the only one set by default</strong>.

guide/content/css/_colours.sass

@@ -11,3 +11,4 @@ $green: #00703c
 $light-grey: #f3f2f1
 $light-pink: lighten(#f499be, 20%)
 $red: #d4351c
+$dark-green: #365e07

guide/content/css/rouge.sass

@@ -4,14 +4,25 @@ pre > code
   &.highlight
     color: $text
 
-    .s,.s1,.s2,.vi
+    .s,.s1,.s2,.vi,.sx
       color: $pink
 
-    .nt,.nf,.nc,.no
+    .nt,.nf,.nc
       color: $orange
 
     .n,.p,.k,.mi,.n,.o,.na,.ss
       color: $dark-blue
 
+    .k
+      font-weight: 600
+
+    .no
+      color: #0e5e5e
+
     .kp
       color: $green
+
+    // comments
+    .c1
+      color: $dark-green
+      font-style: italic

guide/content/form-elements/radios.slim

@@ -92,4 +92,23 @@ section
         Any content passed into <code>#govuk_radio_button</code> as a block will
         be revealed when the radio button is selected.
 
+  == render('/partials/example-fig.*',
+    caption: "Populating values, labels and hints with procs",
+    localisation: radio_field_with_proc_labels_and_hints_locale,
+    code: radio_field_with_proc_labels_and_hints,
+    sample_data: laptops_data_raw,
+    display_data: true,
+    hide_html_output: true) do
+
+    p.govuk-body
+      | It's often convenient to hold label and hint text in locale or
+        configuration files. This approach allows content changes to be made in
+        the repository rather than modifying via data migrations.
+
+    p.govuk-body
+      | To support this behaviour the form builder allows #{link_to('Ruby Procs', ruby_proc_link).html_safe}
+        to be supplied for the <code>:value_method</code>, <code>:text_method</code> and
+        <code>:hint_method</code> parameters. They each take a single argument, <code>item</code>,
+        which is object representing the radio button.
+
 == render('/partials/related-info.*', links: radios_info)

guide/content/introduction/configuration.slim

@@ -0,0 +1,41 @@
+---
+title: Configuration
+---
+
+h1.govuk-heading-xl Configuration
+
+p.govuk-body
+  | The form builder's defaults follow the guidance specified in the
+    GOV.UK Design System documentation, but every project is different
+    and having to repeatedly override settings would soon become annoying.
+
+p.govuk-body
+  | To configure the builder for your project, just create an initialiser
+    in <code>config/initializers/govuk_design_system_formbuilder.rb</code>.
+
+.code-sample
+  pre
+    code.highlight.language-ruby
+      | GOVUKDesignSystemFormBuilder.configure do |conf|
+          conf.default_submit_button_text   = 'Apply'                       # Continue
+          conf.default_error_summary_title  = 'Uh-oh, spaghettios'          # There is a problem
+          conf.default_legend_tag           = 'h3'                          # h1
+          conf.default_legend_size          = 'l'                           # m
+          conf.default_radio_divider_text   = 'how about'                   # or
+
+          # localisation settings
+          conf.localisation_schema_fallback = %i(myapp helpers __context__)
+          conf.localisation_schema_label    = nil
+          conf.localisation_schema_hint     = %i(myapp descriptions __context__)
+          conf.localisation_schema_legend   = %i(myapp descriptions __context__)
+        end
+
+p.govuk-body
+  | For a full list and description of configuration options
+    #{link_to('check the documentation', config_documentation_link).html_safe}
+    and for more information on setting up localisations for your application, there's
+    a #{link_to('dedicated page in this guide', '/building-blocks/localisation').html_safe}.
+
+p.govuk-body
+  | If there are any settings you'd like to be able to set defaults for but
+    can't, #{link_to('raise an issue', project_new_issue_link).html_safe}.

guide/content/introduction/supported-versions.slim

@@ -25,10 +25,13 @@ dl.govuk-summary-list
       ul.govuk-list
         li
           span.govuk-tag.govuk-tag-red
-            | 2.5.6
+            | 2.5.7
         li
           span.govuk-tag.govuk-tag-red
-            | 2.6.4
+            | 2.6.5
+        li
+          span.govuk-tag.govuk-tag-red
+            | 2.7.0
 
   div.govuk-summary-list__row
     dt.govuk-summary-list__key
@@ -37,7 +40,7 @@ dl.govuk-summary-list
       ul.govuk-list
         li
           span.govuk-tag.govuk-tag-red
-            | 5.2.3
+            | 5.2.4
         li
           span.govuk-tag.govuk-tag-red
-            | 6.0.0
+            | 6.0.2

guide/layouts/partials/example-fig.slim

@@ -1,3 +1,6 @@
+- if defined?(custom_config)
+  - custom_config
+
 figure
   figcaption
     h3.govuk-heading-m.example-heading id=anchor_id(caption)
@@ -17,14 +20,35 @@ figure
         code.highlight.language-ruby
           | #{sample_data}
 
+  - if defined?(raw_config)
+    section
+      h4.govuk-heading-s.example-subheading.locale Configuration
+
+      div.govuk-inset-text
+        | Place your configuration in an
+          #{link_to('initializer', rails_initializer_link).html_safe} to ensure
+          it's loaded every time you start your Rails application.
+
+      pre.example-input
+        code.highlight.language-ruby
+          | #{raw_config}
+
+  - if defined?(localisation)
+    - I18n.backend.store_translations(:en, YAML.load(localisation))
+
+    section
+      h4.govuk-heading-s.example-subheading.locale Localisation data
+
+      pre.example-input
+        code.highlight.language-yaml
+          | #{localisation}
+
   section
     h4.govuk-heading-s.example-subheading.input Input
     pre.example-input
       code.highlight.language-slim
         | #{code}
 
-
-
   section
     - display_errors = defined?(show_errors) && show_errors
 
@@ -40,3 +64,7 @@ figure
           - if defined?(sample_data)
             - eval(sample_data)
           = format_slim(code, f: builder(display_errors), **form_data)
+
+
+- if defined?(custom_config)
+  - reset_config

guide/layouts/partials/landing-page/links.slim

@@ -7,6 +7,7 @@ section#links.govuk-width-container
 
       ul.govuk-list
         li== link_to 'Getting started', '/introduction/getting-started'
+        li== link_to 'Configuration', '/introduction/configuration'
         li== link_to 'Supported versions', '/introduction/supported-versions'
         li== link_to 'Labels, hints and legends', '/introduction/labels-hints-and-legends'
         li== link_to 'Error handling', '/introduction/error-handling'
@@ -16,6 +17,7 @@ section#links.govuk-width-container
       ul.govuk-list
         li== link_to 'Injecting content', '/building-blocks/injecting-content'
         li== link_to 'Fieldsets', '/building-blocks/fieldsets'
+        li== link_to 'Localisation', '/building-blocks/localisation'
 
     .govuk-grid-column-one-third
       h2.govuk-heading-m Form elements

guide/lib/examples/localisation.rb

@@ -0,0 +1,53 @@
+module Examples
+  module Localisation
+    def favourite_kind_of_hat_locale
+      <<~LOCALE
+        helpers:
+          label:
+            person:
+              favourite_kind_of_hat: Which style of hat do you prefer?
+          hint:
+            person:
+              favourite_kind_of_hat: |-
+                Trilby, Stetson, Deerstalker, Fez, Top and Beret are
+                the most-fashionable
+      LOCALE
+    end
+
+    def favourite_kind_of_hat
+      <<~SNIPPET
+        = f.govuk_text_field :favourite_kind_of_hat, label: { size: 'm' }
+      SNIPPET
+    end
+
+    def role_name
+      <<~SNIPPET
+        = f.govuk_text_field :role, label: { size: 'm' }
+      SNIPPET
+    end
+
+    def custom_locale
+      <<~LOCALE
+        helpers:
+          label:
+            person:
+              role: What role do you play?
+
+        copy:
+          descriptions:
+            hint:
+              subdivision:
+                person:
+                  role: |-
+                    Roles may be achieved or ascribed or they can be accidental
+                    in different situations. An achieved role is a position
+                    that a person assumes voluntarily which reflects personal
+                    skills, abilities, and effort.
+      LOCALE
+    end
+
+    def reset_config
+      GOVUKDesignSystemFormBuilder.reset!
+    end
+  end
+end