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