Module: GOVUKDesignSystemFormBuilder::Builder

Included in:
FormBuilder
Defined in:
lib/govuk_design_system_formbuilder/builder.rb

Instance Method Summary collapse

Instance Method Details

#govuk_check_box(attribute_name, value, hint_text: nil, label: {}, link_errors: false, multiple: true, &block) ⇒ ActiveSupport::SafeBuffer

Generates a single fieldset, intended for use within a #govuk_check_boxes_fieldset

Examples:

A single check box for terms and conditions

= f.govuk_check_box :terms_agreed,
  true,
  multiple: false,
  link_errors: true,
  label: { text: 'Do you agree with our terms and conditions?' },
  hint_text: 'You will not be able to proceed unless you do'

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders


413
414
415
416
417
418
419
420
421
422
423
424
425
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 413

def govuk_check_box(attribute_name, value, hint_text: nil, label: {}, link_errors: false, multiple: true, &block)
  Elements::CheckBoxes::FieldsetCheckBox.new(
    self,
    object_name,
    attribute_name,
    value,
    hint_text: hint_text,
    label: label,
    link_errors: link_errors,
    multiple: multiple,
    &block
  ).html
end

#govuk_check_boxes_fieldset(attribute_name, legend: {}, hint_text: {}, small: false, &block) ⇒ ActiveSupport::SafeBuffer

Generate a fieldset intended to conatain one or more #govuk_check_box

Examples:

A collection of check boxes for sandwich fillings


= f.govuk_check_boxes_fieldset :desired_filling,
  = f.govuk_check_box :desired_filling, :cheese, label: { text: 'Cheese' }, link_errors: true
  = f.govuk_check_box :desired_filling, :tomato, label: { text: 'Tomato' }

Options Hash (legend:):

  • text (String)

    the fieldset legend's text content

  • size (String)

    the size of the fieldset legend font, can be xl, l, m or s

  • tag (Symbol, String)

    the tag used for the fieldset's header, defaults to h1


379
380
381
382
383
384
385
386
387
388
389
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 379

def govuk_check_boxes_fieldset(attribute_name, legend: {}, hint_text: {}, small: false, &block)
  Containers::CheckBoxesFieldset.new(
    self,
    object_name,
    attribute_name,
    hint_text: hint_text,
    legend: legend,
    small: small,
    &block
  ).html
end

#govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, &block) ⇒ ActiveSupport::SafeBuffer

Generate a list of check boxes from a collection

Examples:

A collection of check boxes for sandwich fillings


@fillings = [
  OpenStruct.new(id: 'pastrami', name: 'Pastrami', description: 'Brined, smoked, steamed and seasoned'),
  OpenStruct.new(id: 'cheddar', name: 'Cheddar', description: 'A sharp, off-white natural cheese')
]

= f.govuk_collection_check_boxes :desired_filling,
  @fillings,
  :id,
  :name,
  :description,
  legend: { text: 'What do you want in your sandwich?', size: 'm' },
  hint_text: "If it isn't listed here, tough luck",
  inline: false

Options Hash (legend:):

  • text (String)

    the fieldset legend's text content

  • size (String)

    the size of the fieldset legend font, can be xl, l, m or s

  • tag (Symbol, String)

    the tag used for the fieldset's header, defaults to h1


345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 345

def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, &block)
  Elements::CheckBoxes::Collection.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method: value_method,
    text_method: text_method,
    hint_method: hint_method,
    hint_text: hint_text,
    legend: legend,
    small: small,
    &block
  ).html
end

#govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, inline: false, small: false, bold_labels: false, &block) ⇒ ActiveSupport::SafeBuffer

Note:

Unlike the Rails #collection_radio_buttons helper, this version can also insert hints per item in the collection by supplying a :hint_method

Note:

:bold_labels, while false by default, is set to true when a :hint_method is provided. This is done to make the label stand out more from the hint.

Generates a radio button for each item in the supplied collection

Examples:

A collection of radio buttons for favourite colours


@colours = [
  OpenStruct.new(id: 'red', name: 'Red', description: 'Roses are red'),
  OpenStruct.new(id: 'blue', name: 'Blue', description: 'Violets are... purple?')
]

= f.govuk_collection_radio_buttons :favourite_colour,
  @colours,
  :id,
  :name,
  :description,
  legend: { text: 'Pick your favourite colour', size: 'm' },
  hint_text: 'If you cannot find the exact match choose something close',
  inline: false

Options Hash (legend:):

  • text (String)

    the fieldset legend's text content

  • size (String)

    the size of the fieldset legend font, can be xl, l, m or s

  • tag (Symbol, String)

    the tag used for the fieldset's header, defaults to h1, defaults to h1


232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 232

def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, inline: false, small: false, bold_labels: false, &block)
  Elements::Radios::Collection.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method: value_method,
    text_method: text_method,
    hint_method: hint_method,
    hint_text: hint_text,
    legend: legend,
    inline: inline,
    small: small,
    bold_labels: bold_labels,
    &block
  ).html
end

#govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, &block) ⇒ ActiveSupport::SafeBuffer

Generates a select element containing option for each member in the provided collection

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders


177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 177

def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, &block)
  Elements::Select.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method: value_method,
    text_method: text_method,
    hint_text: hint_text,
    label: label,
    options: options,
    html_options: html_options,
    &block
  ).html
end

#govuk_date_field(attribute_name, hint_text: nil, legend: {}, date_of_birth: false, omit_day: false, &block) ⇒ ActiveSupport::SafeBuffer

Note:

When using this input be aware that Rails's multiparam time and date handling falls foul of this bug, so incorrect dates like 2019-09-31 will be 'rounded' up to 2019-10-01.

Generates three inputs for the day, month and year components of a date

Examples:

A regular date input with a legend and hint

= f.govuk_date_field :starts_on,
  legend: { 'When does your event start?' },
  hint_text: 'Leave this field blank if you don't know exactly' }

Options Hash (legend:):

  • text (String)

    the fieldset legend's text content

  • size (String)

    the size of the fieldset legend font, can be xl, l, m or s

  • tag (Symbol, String)

    the tag used for the fieldset's header, defaults to h1

See Also:


480
481
482
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 480

def govuk_date_field(attribute_name, hint_text: nil, legend: {}, date_of_birth: false, omit_day: false, &block)
  Elements::Date.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, date_of_birth: date_of_birth, omit_day: omit_day, &block).html
end

#govuk_email_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type email

Examples:

An email address field with a placeholder

= f.govuk_email_field :email_address,
  label: { text: 'Enter your email address' },
  placeholder: '[email protected]'

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to input element

See Also:


77
78
79
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 77

def govuk_email_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
  Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
end

#govuk_error_summary(title = 'There is a problem') ⇒ Object

TODO:

Currently the summary anchors link to the inline error messages themselves rather to the accompanying input. More work is required to improve this and it needs to be handled in a less-generic manner. For example, we can't link to a specific radio button if one hasn't been chosen but we should link to a #govuk_text_field if one has been left blank

Generates a summary of errors in the form, each linking to the corresponding part of the form that contains the error

Examples:

An error summary with a custom title

= f.govuk_error_summary 'Uh-oh, spaghettios'

See Also:


499
500
501
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 499

def govuk_error_summary(title = 'There is a problem')
  Elements::ErrorSummary.new(self, object_name, title).html
end

#govuk_fieldset(legend: { text: 'Fieldset heading' }, described_by: nil, &block) ⇒ ActiveSupport::SafeBuffer

Generates a fieldset containing the contents of the block

Examples:

A fieldset containing address fields

= f.govuk_fieldset legend: { text: 'Address' }
  = f.govuk_text_field :street
  = f.govuk_text_field :town
  = f.govuk_text_field :city

Options Hash (legend:):

  • text (String)

    the fieldset legend's text content

  • size (String)

    the size of the fieldset legend font, can be xl, l, m or s

  • tag (Symbol, String)

    the tag used for the fieldset's header, defaults to h1

See Also:


519
520
521
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 519

def govuk_fieldset(legend: { text: 'Fieldset heading' }, described_by: nil, &block)
  Containers::Fieldset.new(self, legend: legend, described_by: described_by).html(&block)
end

#govuk_file_field(attribute_name, label: {}, hint_text: nil, **args, &block) ⇒ Object

Note:

Remember to set multipart: true when creating a form with file uploads, see the Rails documentation for more information

Generates an input of type file

Examples:

A photo upload field with file type specifier

= f.govuk_file_field :photo, label: { text: 'Upload your photo' }, accept: 'image/*'

Options Hash (label:):

  • text (String)

    the label text

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to input element

See Also:


543
544
545
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 543

def govuk_file_field(attribute_name, label: {}, hint_text: nil, **args, &block)
  Elements::File.new(self, object_name, attribute_name, label: label, hint_text: hint_text, **args, &block).html
end

#govuk_number_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type number

Examples:

A number field with placeholder, min, max and step

= f.govuk_number_field :iq,
  label: { text: 'What is your IQ?' },
  placeholder: 100,
  min: 80,
  max: 150,
  step: 5

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to the input element

See Also:


129
130
131
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 129

def govuk_number_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
  Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
end

#govuk_phone_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type tel

Examples:

A required phone number field with a placeholder

= f.govuk_phone_field :phone_number,
  label: { text: 'UK telephone number' },
  hint_text: 'Include the dialling code',
  required: true,
  placeholder: '0123 456 789'

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to input element

See Also:


52
53
54
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 52

def govuk_phone_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
  Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
end

#govuk_radio_button(attribute_name, value, hint_text: nil, label: {}, link_errors: false, &block) ⇒ ActiveSupport::SafeBuffer

Note:

This should only be used from within a #govuk_radio_buttons_fieldset

Generates a radio button

Examples:

A collection of radio buttons for favourite colours with a divider


= f.govuk_collection_radio_buttons :favourite_colour, inline: false do
  = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' } do

See Also:


298
299
300
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 298

def govuk_radio_button(attribute_name, value, hint_text: nil, label: {}, link_errors: false, &block)
  Elements::Radios::FieldsetRadioButton.new(self, object_name, attribute_name, value, hint_text: hint_text, label: label, link_errors: link_errors, &block).html
end

#govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, inline: false, small: false, &block) ⇒ ActiveSupport::SafeBuffer

Note:

The intention is to use #govuk_radio_button and #govuk_radio_divider within the passed-in block

Generates a radio button fieldset container and injects the supplied block contents

Examples:

A collection of radio buttons for favourite colours with a divider


= f.govuk_collection_radio_buttons :favourite_colour, inline: false do
  = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
  = f.govuk_radio_button :favourite_colour, :green, label: { text: 'Green' }
  = f.govuk_radio_divider
  = f.govuk_radio_button :favourite_colour, :yellow, label: { text: 'Yellow' }

Options Hash (legend:):

  • text (String)

    the fieldset legend's text content

  • size (String)

    the size of the fieldset legend font, can be xl, l, m or s

  • tag (Symbol, String)

    the tag used for the fieldset's header, defaults to h1

See Also:


274
275
276
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 274

def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, inline: false, small: false, &block)
  Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, inline: inline, small: small, &block).html
end

#govuk_radio_divider(text = 'or') ⇒ ActiveSupport::SafeBuffer

Note:

This should only be used from within a #govuk_radio_buttons_fieldset

Inserts a text divider into a list of radio buttons

Examples:

A custom divider

= govuk_radio_divider 'Alternatively'

See Also:


310
311
312
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 310

def govuk_radio_divider(text = 'or')
  tag.div(text, class: %w(govuk-radios__divider))
end

#govuk_submit(text = 'Continue', warning: false, secondary: false, prevent_double_click: true, validate: false, &block) ⇒ ActiveSupport::SafeBuffer

TODO:

The GOV.UK design system also supports disabled buttons, they should probably be supported too

Note:

Only the first additional button or link (passed in via a block) will be given the correct left margin, subsequent buttons will need to be manually accounted for

Generates a submit button, green by default

Examples:

A submit button with custom text, double click protection and an inline cancel link

= f.govuk_submit "Proceed", prevent_double_click: true do
  = link_to 'Cancel', some_other_path, class: 'govuk-button__secondary'

Raises:

  • (ArgumentError)

    raised if both warning and secondary are true

See Also:


453
454
455
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 453

def govuk_submit(text = 'Continue', warning: false, secondary: false, prevent_double_click: true, validate: false, &block)
  Elements::Submit.new(self, text, warning: warning, secondary: secondary, prevent_double_click: prevent_double_click, validate: validate, &block).html
end

#govuk_text_area(attribute_name, hint_text: nil, label: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Note:

Setting max_chars or max_words will add a caption beneath the textarea with a live count of words or characters

Generates a textarea element with a label, optional hint. Also offers the ability to add the GOV.UK character and word counting components automatically

Examples:

A text area with a custom number of rows and a word limit

= f.govuk_number_field :cv,
  label: { text: 'Tell us about your work history' },
  rows: 8,
  max_words: 300

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to the textarea element

See Also:


160
161
162
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 160

def govuk_text_area(attribute_name, hint_text: nil, label: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, **args, &block)
  Elements::TextArea.new(self, object_name, attribute_name, hint_text: hint_text, label: label, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, **args, &block).html
end

#govuk_text_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type text

Examples:

A required full name field with a placeholder

= f.govuk_text_field :name,
  label: { text: 'Full name' },
  hint_text: 'It says it on your birth certificate',
  required: true,
  placeholder: 'Ralph Wiggum'

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to input element

See Also:


25
26
27
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 25

def govuk_text_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
  Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
end

#govuk_url_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type url

Examples:

A url field with autocomplete

= f.govuk_url_field :favourite_website,
  label: { text: 'Enter your favourite website' },
  placeholder: 'https://www.gov.uk',
  autocomplete: 'url'

Options Hash (label:):

  • text (String)

    the label text

  • size (String)

    the size of the label font, can be xl, l, m, s or nil

  • tag (Symbol, String)

    the label's wrapper tag, intended to allow labels to act as page headings

  • hidden (Boolean)

    control the visability of the label. Hidden labels will stil be read by screenreaders

Options Hash (**args):

  • args (Hash)

    additional arguments are applied as attributes to input element

See Also:


102
103
104
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 102

def govuk_url_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
  Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
end