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


451
452
453
454
455
456
457
458
459
460
461
462
463
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 451

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

Returns:

  • (ActiveSupport::SafeBuffer)

    HTML output


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

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

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

Returns:

  • (ActiveSupport::SafeBuffer)

    HTML output


380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 380

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

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)

    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

  • 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

  • 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, defaults to h1

Returns:

  • (ActiveSupport::SafeBuffer)

    HTML output


262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 262

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

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


203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 203

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

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

Returns:

  • (ActiveSupport::SafeBuffer)

    HTML output

See Also:


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

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

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:


79
80
81
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 79

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:


537
538
539
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 537

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

Returns:

  • (ActiveSupport::SafeBuffer)

    HTML output

See Also:


557
558
559
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 557

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/*'

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:


581
582
583
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 581

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

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:


155
156
157
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 155

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

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

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:


54
55
56
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 54

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

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:


330
331
332
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 330

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

Returns:

  • (ActiveSupport::SafeBuffer)

    HTML output

See Also:


306
307
308
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 306

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:


342
343
344
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 342

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, 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

  • 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:


491
492
493
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 491

def govuk_submit(text = config.default_submit_button_text, 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

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:


186
187
188
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 186

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'

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:


27
28
29
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 27

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'

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:


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

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