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'

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • value (Boolean, String, Symbol, Integer) —

    The value of the checkbox when it is checked

  • hint_text (String) (defaults to: nil) —

    the contents of the hint

  • link_errors (Boolean) (defaults to: false) —

    controls whether this radio button should be linked to

  • multiple (Boolean) (defaults to: true) —

    controls whether the check box is part of a collection or represents a single attribute

  • block (Block) —

    any HTML passed in will form the contents of the fieldset

  • label (Hash) (defaults to: {}) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


549
550
551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 549

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, classes: nil, &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' }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: {}) —

    The content of the fieldset hint. No hint will be injected if left nil

  • small (Boolean) (defaults to: false) —

    controls whether small check boxes are used instead of regular-sized ones

  • legend (Hash) (defaults to: {}) —

    options for configuring the legend

  • classes (String) (defaults to: nil) —

    Classes to add to the checkbox container.

  • block (Block) —

    a block of HTML that will be used to populate the fieldset

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

  • hidden (Boolean) —

    control the visibility of the legend. Hidden legends will still be read by screenreaders

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 514

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

#govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, classes: nil, &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,
  classes: 'app-overflow-scroll',

A collection of check boxes for types of bread

= f.govuk_collection_radio_buttons :bread,
  @variety,
  :id,
  :name do

    p.govuk-inset-text
      | Only Hearty Italian is available with the meal deal menu

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • collection (Enumerable<Object>) —

    Options to be added to the select element

  • value_method (Symbol) —

    The method called against each member of the collection to provide the value

  • text_method (Symbol) —

    The method called against each member of the collection to provide the label text

  • hint_method (Symbol, Proc) (defaults to: nil) —

    The method called against each member of the collection to provide the hint text. When a Proc is provided it must take a single argument that is a single member of the collection

  • hint_text (String) (defaults to: nil) —

    The content of the fieldset hint. No hint will be injected if left nil

  • small (Boolean) (defaults to: false) —

    controls whether small check boxes are used instead of regular-sized ones

  • classes (String) (defaults to: nil) —

    Classes to add to the checkbox container.

  • legend (Hash) (defaults to: {}) —

    options for configuring the legend

  • block (Block) —

    any HTML passed in will be injected into the fieldset, after the hint and before the checkboxes

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

  • hidden (Boolean) —

    control the visibility of the legend. Hidden legends will still be read by screenreaders

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 477

def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, classes: nil, &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,
    classes: classes,
    &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, classes: nil, &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, labels capitalised via a proc


@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,
  ->(option) { option.name.upcase },
  :description,
  legend: { text: 'Pick your favourite colour', size: 'm' },
  hint_text: 'If you cannot find the exact match choose something close',
  inline: false

A collection of radio buttons for grades with injected content

= f.govuk_collection_radio_buttons :favourite_colour,
  @grades,
  :id,
  :name do

    p.govuk-inset-text
      | If you took the test more than once enter your highest grade

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • collection (Enumerable<Object>) —

    Options to be added to the select element

  • value_method (Symbol, Proc) —

    The method called against each member of the collection to provide the value. When a Proc is provided it must take a single argument that is a single member of the collection

  • text_method (Symbol, Proc, nil) —

    The method called against each member of the collection to provide the label text. When a Proc is provided it must take a single argument that is a single member of the collection. When a nil value is provided the label text will be retrieved from the locale.

  • hint_method (Symbol, Proc, nil) (defaults to: nil) —

    The method called against each member of the collection to provide the hint text. When a Proc is provided it must take a single argument that is a single member of the collection. When a nil value is provided the hint text will be retrieved from the locale. This is the default and param can be omitted.

  • hint_text (String) (defaults to: nil) —

    The content of the fieldset hint. No hint will be injected if left nil

  • legend (Hash) (defaults to: {}) —

    options for configuring the legend

  • inline (Boolean) (defaults to: false) —

    controls whether the radio buttons are displayed inline or not

  • small (Boolean) (defaults to: false) —

    controls whether small radio buttons are used instead of regular-sized ones

  • bold_labels (Boolean) (defaults to: false) —

    controls whether the radio button labels are bold

  • classes (String) (defaults to: nil) —

    Classes to add to the radio button container.

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

  • hidden (Boolean) —

    control the visibility of the legend. Hidden legends will still be read by screenreaders

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 347

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, classes: nil, &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,
    classes: classes,
    &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

Examples:

A select box with hint

= f.govuk_number_field :grade,
  @grades,
  :id,
  :name,
  hint_text: "If you took the test more than once enter your highest grade"

A select box with injected content

= f.govuk_number_field :favourite_colour,
  @colours,
  :id,
  :name do

    p.govuk-inset-text
      | Select the closest match

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • collection (Enumerable<Object>) —

    Options to be added to the select element

  • value_method (Symbol) —

    The method called against each member of the collection to provide the value

  • text_method (Symbol) —

    The method called against each member of the collection to provide the text

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • label (Hash) (defaults to: {}) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 276

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, hint and injected content

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

    p.govuk-inset-text
      | If you don't fill this in you won't be eligable for a refund

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    the contents of the hint

  • legend (Hash) (defaults to: {}) —

    options for configuring the legend

  • omit_day (Boolean) (defaults to: false) —

    do not render a day input, only capture month and year

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input group

  • date_of_birth (Boolean) (defaults to: false) —

    if true birth date auto completion attributes will be added to the inputs

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

  • hidden (Boolean) —

    control the visibility of the legend. Hidden legends will still be read by screenreaders

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


622
623
624
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 622

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]'

A email field with injected content

= f.govuk_phone_field :email_address,
  label: { text: 'Email address' } do

  p.govuk-inset-text
    | Use your work address

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • width (Integer, String) (defaults to: nil) —

    sets the width of the input, can be 2, 3 4, 5, 10 or 20 characters or one-quarter, one-third, one-half, two-thirds or full width of the container

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


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

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 = config.default_error_summary_title) ⇒ 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'

Parameters:

  • title (String) (defaults to: config.default_error_summary_title) —

    the error summary heading

See Also:


641
642
643
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 641

def govuk_error_summary(title = config.default_error_summary_title)
  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

Parameters:

  • legend (Hash) (defaults to: { text: 'Fieldset heading' }) —

    options for configuring the legend

  • described_by (Array<String>) (defaults to: nil) —

    the ids of the elements that describe this fieldset, usually hints and errors

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

  • hidden (Boolean) —

    control the visibility of the legend. Hidden legends will still be read by screenreaders

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


662
663
664
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 662

def govuk_fieldset(legend: { text: 'Fieldset heading' }, described_by: nil, &block)
  Containers::Fieldset.new(self, legend: legend, described_by: described_by, &block).html
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 and injected content

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

  p.govuk-inset-text
    | Explicit images will result in account termination

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • label (Hash) (defaults to: {}) —

    a customizable set of options

  • args (Hash) —

    a customizable set of options

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:


689
690
691
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 689

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

A number field with injected content

= f.govuk_number_field :height_in_cm,
  label: { text: 'Height in centimetres' } do

    p.govuk-inset-text
      | If you haven't measured your height in the last 6 months
        do it now

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • width (Integer, String) (defaults to: nil) —

    sets the width of the input, can be 2, 3 4, 5, 10 or 20 characters or one-quarter, one-third, one-half, two-thirds or full width of the container

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


204
205
206
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 204

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_password_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type password

Examples:

A password field

= f.govuk_password_field :password,
  label: { text: 'Enter your password' }

A password field with injected content

= f.govuk_password_field :password,
  label: { text: 'Password' } do

  p.govuk-inset-text
    | Ensure your password is at least 16 characters long

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • width (Integer, String) (defaults to: nil) —

    sets the width of the input, can be 2, 3 4, 5, 10 or 20 characters or one-quarter, one-third, one-half, two-thirds or full width of the container

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


135
136
137
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 135

def govuk_password_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
  Elements::Inputs::Password.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'

A phone field with injected content

= f.govuk_phone_field :fax_number,
  label: { text: 'Fax number' } do

  p.govuk-inset-text
    | Yes, fax machines are still a thing

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • width (Integer, String) (defaults to: nil) —

    sets the width of the input, can be 2, 3 4, 5, 10 or 20 characters or one-quarter, one-third, one-half, two-thirds or full width of the container

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


70
71
72
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 70

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' }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    the contents of the hint

  • block (Block) —

    Any supplied HTML will be wrapped in a conditional container and only revealed when the radio button is picked

  • link_errors (Boolean) (defaults to: false) —

    controls whether this radio button should be linked to from the error summary. Should only be set to true for the first radio button in a fieldset

  • legend (Hash) —

    a customizable set of options

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


417
418
419
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 417

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, classes: nil, &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' }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the fieldset hint. No hint will be injected if left nil

  • legend (Hash) (defaults to: {}) —

    options for configuring the legend

  • inline (Boolean) (defaults to: false) —

    controls whether the radio buttons are displayed inline or not

  • small (Boolean) (defaults to: false) —

    controls whether small radio buttons are used instead of regular-sized ones

  • block (Block) —

    a block of HTML that will be used to populate the fieldset

  • classes (String) (defaults to: nil) —

    Classes to add to the radio button container.

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

  • hidden (Boolean) —

    control the visibility of the legend. Hidden legends will still be read by screenreaders

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


392
393
394
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 392

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

#govuk_radio_divider(text = config.default_radio_divider_text) ⇒ 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'

Parameters:

  • text (String) (defaults to: config.default_radio_divider_text) —

    The divider text

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


429
430
431
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 429

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

#govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, classes: nil, 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'

Parameters:

  • text (String) (defaults to: config.default_submit_button_text) —

    the button text

  • warning (Boolean) (defaults to: false) —

    makes the button red (warning) when true

  • secondary (Boolean) (defaults to: false) —

    makes the button grey (secondary) when true

  • classes (String) (defaults to: nil) —

    Classes to add to the submit button

  • prevent_double_click (Boolean) (defaults to: true) —

    adds JavaScript to safeguard the form from being submitted more than once

  • validate (Boolean) (defaults to: false) —

    adds the formnovalidate to the submit button when true, this disables all client-side validation provided by the browser. This is to provide a more consistent and accessible user experience

  • block (Block) —

    Any supplied HTML will be inserted immediately after the submit button. It is intended for other buttons directly related to the form's operation, such as 'Cancel' or 'Safe draft'

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

Raises:

  • (ArgumentError) —

    raised if both warning and secondary are true

See Also:


590
591
592
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 590

def govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, classes: nil, prevent_double_click: true, validate: false, &block)
  Elements::Submit.new(self, text, warning: warning, secondary: secondary, classes: classes, 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

A text area with injected content

= f.govuk_number_field :description,
  label: { text: 'Where did the incident take place?' } do

  p.govuk-inset-text
    | If you don't know exactly leave this section blank

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • max_words (Integer) (defaults to: nil) —

    adds the GOV.UK max word count

  • max_chars (Integer) (defaults to: nil) —

    adds the GOV.UK max characters count

  • threshold (Integer) (defaults to: nil) —

    only show the max_words and max_chars warnings once a threshold (percentage) is reached

  • rows (Integer) (defaults to: 5) —

    sets the initial number of rows

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


243
244
245
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 243

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'

A text field with injected content

= f.govuk_text_field :pseudonym,
  label: { text: 'Pseudonym' } do

  p.govuk-inset-text
    | Ensure your stage name is unique

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • width (Integer, String) (defaults to: nil) —

    sets the width of the input, can be 2, 3 4, 5, 10 or 20 characters or one-quarter, one-third, one-half, two-thirds or full width of the container

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


35
36
37
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 35

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'

A url field with injected content

= f.govuk_url_field :personal_website,
  label: { text: 'Enter your website' } do

    p.govuk-inset-text
      | This will be visible on your profile

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint_text (String) (defaults to: nil) —

    The content of the hint. No hint will be injected if left nil

  • width (Integer, String) (defaults to: nil) —

    sets the width of the input, can be 2, 3 4, 5, 10 or 20 characters or one-quarter, one-third, one-half, two-thirds or full width of the container

  • label (Hash) (defaults to: {}) —

    configures the associated label

  • block (Block) —

    arbitrary HTML that will be rendered between the hint and the input

  • args (Hash) —

    a customizable set of options

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


168
169
170
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 168

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