README.md

GOV.UK Form Builder for Ruby on Rails

This library provides an easy-to-use form builder for the GOV.UK Design System.

It is intended to make creating forms quick, easy and familiar for Ruby on Rails developers.

Documentation

The gem comes with a full guide that covers most aspects of day-to-day use, along with code and output examples. The examples in the guide are generated from the builder itself so it will always be up to date.

What’s included

• 100% compatibility with the GOV.UK Design System
• Full control of labels, legends, hints, captions and fieldsets
• No overwriting of Rails’ default form helpers
• Automatic ARIA associations between hints, errors and inputs
• Most helpers take blocks for arbitrary content
• Additional params for programmatically adding hints to check box and radio button collections
• Full I18n support
• Automatic handling of ActiveRecord validation error messages
• No external dependencies
• An exhaustive test suite
• Extensive technical documentation

Installation

You can install the form builder gem by running the gem install govuk_design_system_formbuilder or by adding the following line to your Gemfile:

gem 'govuk_design_system_formbuilder'

To make full use of this tool, you will need a Rails application with the latest GOV.UK Frontend assets installed and configured.

To get up and running quickly and easily try kickstarting your project with a pre-configured template:

• DfE Rails Template
• DEFRA Ruby Template

Setup

To use the form builder in an ad hoc basis you can specify it as an argument to form_for or form_with. These examples are written in Slim but other templating languages like ERB and Haml work just as well.

= form_for @some_object, builder: GOVUKDesignSystemFormBuilder::FormBuilder do |f|
  ...

To set it globally, just add this line to your ApplicationController:

class ApplicationController < ActionController::Base
  default_form_builder GOVUKDesignSystemFormBuilder::FormBuilder
end

Now we can get started!

= form_for @person do |f|

  = f.govuk_text_field :full_name, label: { text: "Your full name" }

  = f.govuk_number_field :age, label: { text: "Age" }

  = f.govuk_collection_select :department_id,
    @departments,
    :id,
    :name,
    :description,
    label: { text: "Which department do you work for?" },
    hint: { text: "If you don’t know ask your manager" }

  = f.govuk_submit 'Away we go!'

Developing and running the tests

The form builder is tested with RSpec. To run all the tests first ensure that the development and testing prerequisite gems are installed. At the root of a freshly-cloned repo run:

bundle

Now, if everything was successful, run RSpec:

bundle exec rspec

Contributing

Bug reports and feature requests are most welcome, please raise an issue or submit a pull request.

Currently we’re using GOVUK Lint to ensure code meets the GOV.UK guidelines. Please ensure that any PRs also adhere to this standard.

To help keep the logs clean and tidy, please configure git to use your full name:

git config --global user.name "Julius Hibbert"

Services using this library

Approximately 100 services use this library, here are a few from the DfE, MoJ, and BEIS.

• Apply for teacher training
• Teaching Vacancies
• Manage children's vaccinations
• Claim for crown court defence
• Appeal to the tax tribunal
• Apply to court about child arrangements
• Trade Tariff duty calculator
• Report your official development assistance

Form building services using this library

• MoJ Forms
• GOV.UK Forms

Thanks

This project was inspired by Ministry of Justice’s GovukElementsFormBuilder, but is leaner, more modular and written in a more idiomatic style.