Version 2.0.0

[peteryates]

This is the first big revision to the form builder that contains some breaking changes. The plan is to release it when the next version (3.9.0) of govuk-frontend lands.

The first beta is pencilled in for late August so there will be plenty of time for the changes to be tested.

Rationale

Some decisions were made early on that didn't allow for much flexibility. These were added to more recently and there was a gulf between customisable and non-customisable parts of the component. For example, label can be a custom size, weight and have a custom tag, or be totally overwritten with content provided via a proc but hint can't be customised at all.

With these changes hint and form_group will act more like label, legend and caption. Any 'extra' arguments (**kwargs) will be added as HTML attributes and text will be set using the hint: { text: 'something' } format rather than hint_text: 'something'.

In the case of hints, when a proc is passed in the hint element will be a div instead of a span to ensure the generated HTML is valid.

Change log

• Replace the form_group_classes argument with form_group and allow it to take either a Hash or Proc Customise form group attributes #173
• Replace hint_text with hint and allow it to take either a Hash or Proc Make hint arguments follow convention set by label, legend, etc #174
• Add support for input prefixes and suffixes Add prefix and suffix support #159
• Display a default legend if one hasn't been specified (can be omitted with nil) Set legend text by default #185
• Add extra arguments passed to hint, label, caption and legend hashes as HTML attributes on the relevant element Allow custom HTML attributes to be set on labels captions and legends #190
• Improve govuk_check_boxes_fieldset behaviour with regard to hidden fields:
  • add a hidden field by default when rendering a check boxes fieldset Fix bug where checkbox hidden field isn't rendered #192
  • allow the hidden field to be suppressed using the multiple flag Add multiple flag to govuk_collection_check_boxes #196
• Show ERB examples in the guide in addition to Slim ones Test out the generation of ERB input examples #181

Remaining tasks

• Release some betas so the changes can be properly evaluated before the proper release
• Create an upgrade guide page. Not sure if it warrants a page in the actual guide or a Github ticket
• Investigate creating a quick sed script to make the changes. It's probably going to be a pain because Ruby has about 50 ways to declare a string 😓
• Do some testing with real projects, DFE-Digital/apply-for-teacher-training is a good place to start

---

Upgrade Guide

This is draft content for an actual upgrade guide which will be part of the v2.0.0 release notes.

This is a manual process. Due to Ruby's flexibility when it comes to declaring strings automating this process will probably take longer than just doing it.

These changes apply to the keyword arguments for all of the form helpers.

hint_text ➡ hint

Old syntax	New syntax
hint_text: "your hint goes here"	hint: { text: "your hint goes here" }

Hints that stretch across multiple lines must be tackled differently. Here's an example of replacing a multiline hint using a partial.

-          <%= f.govuk_radio_button :service, :apply, label: { text: 'Yes, I want to apply using the new service', size: 's' }, link_errors: true, hint_text:
-            "<p class=\"govuk-body govuk-!-margin-top-2\">Choose this option if:</p>
-            <ul class=\"govuk-list govuk-list--bullet\">
-              <li>all your chosen providers are available on the new service</li>
-              <li>you want to try a streamlined service with personalised support</li>
-            </ul>".html_safe %>
+          <%= f.govuk_radio_button :service,
+            :apply,
+            label: { text: 'Yes, I want to apply using the new service', size: 's' },
+            hint: -> { render(partial: 'apply_using_new_service_hint') },
+            link_errors: true
+          %>

Another approach, this time inline, should work too:

<%= f.govuk_radio_button :service,
  :apply,
  label: { text: 'Yes, I want to apply using the new service', size: 's' },
  link_errors: true,
  hint: -> do %>
   <ul class="govuk-list govuk-list--bullet">
      <li>all your chosen providers are available on the new service</li>
      <li>you want to try a streamlined service with personalised support</li>
   </ul>
<% end %>

form_group_classes ➡ form_group

form_group_classes: %w(polka-dots) becomes form_group: { classes: %w(polka-dots) }

Finding offending code

The following command finds all instances of hint_text in app/views, app/components and app/helpers with ag. The same approach can be used for form_group_classes.

ag "hint_text\:" app/{views,components,helpers}

Legends are now set by default

This shouldn't affect most projects who'll already have set their legend text via params or localisation, but legends behaviour has been made more consistent with labels. To omit a legend from a fieldset associated with a field (those generated with #govuk_fieldset remain unaffected) the legend now needs to be set via legend: nil. If the legend keyword argument isn't provided the legend will default to the name of the attribute.

For example, the legend for this field would be Project_start:

Note. the underscore being left is intended behaviour, it's meant to prompt the developer to override it accordingly

= form.govuk_date_field(:project_start)

Automatic addition of hidden fields required for checkbox deselection

Previously it was up to the developer to add a #hidden_field to a #govuk_check_boxes_fieldset to allow all selections to be deselected. This behaviour is now included by default. To prevent one from being added to single fields (ie boolean toggles or confirmations) multiple: false can be passed to #govuk_check_boxes_fieldset to suppress the hidden field.

[aliuk2012]

As its a breaking change is there any chance we could try align more with GOV.UK Frontend’s public API?
I understand the syntax format/style cannot be matched but at least the functionality/features should be.

[peteryates]

If there are extra arguments that the Nunjucks macros take that the form builder doesn't, that offer more customisation and can be cleanly integrated, I'm all for it. If there's anything you think is missing please raise a ticket (or PR) and I'll definitely have a closer look.

I'm against the idea of passing in complex JSON and raw HTML though; I think the current approach with procs is much cleaner and the API still bears a strong resemblance with Rails' built in form builder.

The intention from the start was to have something that anyone familiar with Rails would be able to grasp in fifteen minutes.

Not that it's entirely related but did you see the proof of concept I made that allows the Nunjucks macros to be called from Ruby? Perhaps V3 could have swappable backends!

[edwardhorsford]

I think there should be a target that the full set of options available in GOV.UK Frontend should be supported. Full feature parity.

The actual api could possibly differ - but it's 'cleaner' for us if the capability is the same.

Note: this was one of our principles on the BEIS Rails design system port.

[peteryates]

I'm pretty sure that all of the functionality shown in the GOV.UK Design System Components section is implemented.

If there are features that the Nunjucks macros offer that are missing here I'll gladly look into adding them, perhaps someone familiar with both could create a list of discrepancies. Of course, PRs are always welcome.

[peteryates]

I did a quick test with Apply's test sutie and having made a few substitutions (with vimnastics 🤸) all the tests pass.

As a bonus some of the previously-invalid HTML is now valid 🎉

[codeclimate]

Code Climate has analyzed commit b11396b and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (50% is the threshold).

This pull request will bring the total coverage in the repository to 99.8% (0.0% change).

View more on Code Climate.

[peteryates]

Beta 4 is up. Hopefully it's the final one.