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, unchecked_value = false, hint: {}, label: {}, link_errors: false, multiple: true, exclusive: false, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Generates a single check box, 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

  • unchecked_value (Boolean, String, Symbol, Integer) (defaults to: false) —

    The value of the checkbox when it is unchecked

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    controls whether this radio button should be linked to from #govuk_error_summary

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

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

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

    sets the checkbox so that when checked none of its siblings can be too. Usually used for the ‘None of these apply to me’ option found beneath a #govuk_check_box_divider.

  • block (Block) —

    any HTML passed in will form the contents of the fieldset

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

    a customizable set of options

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 912

def govuk_check_box(attribute_name, value, unchecked_value = false, hint: {}, label: {}, link_errors: false, multiple: true, exclusive: false, **kwargs, &block)
  Elements::CheckBoxes::FieldsetCheckBox.new(
    self,
    object_name,
    attribute_name,
    value,
    unchecked_value,
    hint:,
    label:,
    link_errors:,
    multiple:,
    exclusive:,
    **kwargs,
    &block
  ).html
end

#govuk_check_box_divider(text = config.default_check_box_divider_text) ⇒ ActiveSupport::SafeBuffer

Note:

This should only be used from within a #govuk_check_boxes_fieldset

Inserts a text divider into a list of check boxes

Examples:

A custom divider

= govuk_check_box_divider 'On the other hand'

Parameters:

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

    The divider text

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



937
938
939
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 937

def govuk_check_box_divider(text = config.default_check_box_divider_text)
  tag.div(text, class: %w(govuk-checkboxes__divider))
end

#govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, form_group: {}, multiple: true, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Note:

To ensure the #govuk_error_summary link functions correctly ensure the first #govuk_check_box is set to link_errors: true

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, legend: { text: 'Which filling do you want?' },
  = f.govuk_check_box :desired_filling, :cheese, label: { text: 'Cheese' }, link_errors: true
  = f.govuk_check_box :desired_filling, :tomato, label: { text: 'Tomato' }

A collection of check boxes for drinks choices with legend as a proc

= f.govuk_check_boxes_fieldset :drink_id, legend: -> { tag.h3('Choose drinks to accompany your meal') },
  = f.govuk_check_box :desired_filling, :lemonade, label: { text: 'Lemonade' }, link_errors: true
  = f.govuk_check_box :desired_filling, :fizzy_orange, label: { text: 'Fizzy orange' }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

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

  • legend (NilClass, Hash, Proc) (defaults to: {}) —

    options for configuring the legend. Legend will be omitted if nil.

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

    configures or sets the caption content which is inserted above the legend

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

    configures the form group

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

    when true adds a [] suffix the name of the automatically-generated hidden field (ie. project[invoice_attributes][]). When false, no [] suffix is added (ie. project[accepted])

  • 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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the legend element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 866

def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, form_group: {}, multiple: true, **kwargs, &block)
  Containers::CheckBoxesFieldset.new(
    self,
    object_name,
    attribute_name,
    hint:,
    legend:,
    caption:,
    small:,
    form_group:,
    multiple:,
    **kwargs,
    &block
  ).html
end

#govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, small: false, form_group: {}, include_hidden: config.default_collection_check_boxes_include_hidden, **kwargs, &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,
  class: 'app-overflow-scroll',

A collection of check boxes for types of bread

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

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

A collection of check boxes with the legend supplied as a proc

= f.govuk_collection_check_boxes :sandwich_type,
  @breads,
  :id,
  :name,
  legend: -> { tag.h3('What kind of sandwich do you want?') }

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 (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

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

  • legend (NilClass, Hash, Proc) (defaults to: {}) —

    options for configuring the legend. Legend will be omitted if nil.

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

    configures or sets the caption content which is inserted above the legend

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

    configures the form group

  • include_hidden (Boolean) (defaults to: config.default_collection_check_boxes_include_hidden) —

    controls whether a hidden field is inserted to allow for empty submissions

  • block (Block) —

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

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 808

def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, small: false, form_group: {}, include_hidden: config.default_collection_check_boxes_include_hidden, **kwargs, &block)
  Elements::CheckBoxes::Collection.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method:,
    text_method:,
    hint_method:,
    hint:,
    legend:,
    caption:,
    small:,
    form_group:,
    include_hidden:,
    **kwargs,
    &block
  ).html
end

#govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method = nil, hint_method = nil, hint: {}, legend: {}, caption: {}, inline: false, small: false, bold_labels: nil, include_hidden: config.default_collection_radio_buttons_include_hidden, form_group: {}, **kwargs, &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, is nil (falsy) by default. When a :hint_method is provided it will become true to make the label stand out more from the hint. The choice can be overridden with true or false.

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 :grade,
  @grades,
  :id,
  :name do

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

A collection of radio buttons with the legend supplied as a proc

= f.govuk_collection_radio_buttons :category,
  @categories,
  :id,
  :name,
  legend: -> { tag.h3('Which category do you belong to?') }

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) (defaults to: 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 (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • legend (NilClass, Hash, Proc) (defaults to: {}) —

    options for configuring the legend. Legend will be omitted if nil.

  • 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: nil) —

    controls whether the radio button labels are bold

  • include_hidden (Boolean) (defaults to: config.default_collection_radio_buttons_include_hidden) —

    controls whether a hidden field is inserted to allow for empty submissions

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

    configures or sets the caption content which is inserted above the legend

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the legend element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 629

def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method = nil, hint_method = nil, hint: {}, legend: {}, caption: {}, inline: false, small: false, bold_labels: nil, include_hidden: config.default_collection_radio_buttons_include_hidden, form_group: {}, **kwargs, &block)
  Elements::Radios::Collection.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method:,
    text_method:,
    hint_method:,
    hint:,
    legend:,
    caption:,
    inline:,
    small:,
    bold_labels:,
    form_group:,
    include_hidden:,
    **kwargs,
    &block
  ).html
end

#govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, hint: {}, label: {}, caption: {}, form_group: {}, before_input: nil, after_input: nil, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

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

Examples:

A select box with hint

= f.govuk_collection_select :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_collection_select(:favourite_colour, @colours, :id, :name) do

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

A select box with the label supplied as a proc

= f.govuk_collection_select(:team, @teams, :id, :name) do
  label: -> { tag.h3("Which team did you represent?") }

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 (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    configures or sets the associated label content

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

    Options hash passed through to Rails’ collection_select helper

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

    configures the form group

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 501

def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, hint: {}, label: {}, caption: {}, form_group: {}, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::CollectionSelect.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method:,
    text_method:,
    hint:,
    label:,
    caption:,
    options:,
    form_group:,
    before_input:,
    after_input:,
    **kwargs,
    &block
  ).html
end

#govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, maxlength_enabled: false, segments: config.default_date_segments, segment_names: config.default_date_segment_names, before_inputs: nil, after_inputs: nil, form_group: {}, **kwargs, &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.

Note:

When using this input values will be retrieved from the attribute if it is a Date object or a multiparam date hash

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 eligible for a refund

A date input with legend supplied as a proc

= f.govuk_date_field :finishes_on,
  legend: -> { tag.h3('Which category do you belong to?') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • legend (NilClass, Hash, Proc) (defaults to: {}) —

    options for configuring the legend. Legend will be omitted if nil.

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

    configures or sets the caption content which is inserted above the legend

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

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

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

    adds maxlength attribute to day, month and year inputs (2, 2, and 4, respectively)

  • segments (Hash) (defaults to: config.default_date_segments) —

    allows Rails’ multiparameter attributes to be overridden on a field-by-field basis. Hash must contain day:, month: and year: keys. Defaults to the default value set in the default_date_segments setting in DEFAULTS

  • segment_names (Hash) (defaults to: config.default_date_segment_names) —

    allows the day, month and year labels to be overridden. Hash must contain day:, month: and year: keys. Defaults to the default value set in the default_date_segment_names setting in DEFAULTS

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

    configures the form group

  • before_inputs (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_inputs (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • 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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the legend element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



1026
1027
1028
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1026

def govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, maxlength_enabled: false, segments: config.default_date_segments, segment_names: config.default_date_segment_names, before_inputs: nil, after_inputs: nil, form_group: {}, **kwargs, &block)
  Elements::Date.new(self, object_name, attribute_name, hint:, legend:, caption:, date_of_birth:, omit_day:, maxlength_enabled:, segments:, segment_names:, form_group:, before_inputs:, after_inputs:, **kwargs, &block).html
end

#govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &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: 'ralph.wiggum@springfield.edu'

An email field with injected content

= f.govuk_phone_field :work_email,
  label: { text: 'Work email address' } do

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

A email field with the label supplied as a proc

= f.govuk_email_field :personal_email,
  label: -> { tag.h3('Personal email address') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • 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

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

    when true adds space between characters to increase the readability of sequences of letters and numbers. Defaults to false.

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the label

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

    configures the form group

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

    the text placed before the input. No prefix will be added if left nil

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

    the text placed after the input. No suffix will be added if left nil

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



181
182
183
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 181

def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::Inputs::Email.new(self, object_name, attribute_name, hint:, label:, caption:, width:, extra_letter_spacing:, form_group:, prefix_text:, suffix_text:, before_input:, after_input:, **kwargs, &block).html
end

#govuk_error_summary(title = config.default_error_summary_title, presenter: config.default_error_summary_presenter, link_base_errors_to: nil, order: nil, **kwargs, &block) ⇒ Object

Note:

Only the first error in the #errors array for each attribute will be included.

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

  • link_base_errors_to (Symbol, String) (defaults to: nil) —

    set the field that errors on :base are linked to, as there won’t be a field representing the object base.

  • order (Array<Symbol>) (defaults to: nil) —

    the attribute order in which error messages are displayed. Ordered attributes will appear first and unordered ones will be last, sorted in the default manner (in which they were defined on the model).

  • block (Block) —

    arbitrary HTML that will be rendered between title and error message list

  • presenter (Class, Object) (defaults to: config.default_error_summary_presenter) —

    the class or object that is responsible for formatting a list of error messages that will be rendered in the summary.

    • When a class is specified it will be instantiated with the object’s errors in the object.errors.messages format.

    • When an object is specified it will be used as-is.

    The object must implement #formatted_error_messages, see Presenters::ErrorSummaryPresenter for more details.

  • kwargs (Hash) —

    a customizable set of options

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the error summary div element

See Also:



1106
1107
1108
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1106

def govuk_error_summary(title = config.default_error_summary_title, presenter: config.default_error_summary_presenter, link_base_errors_to: nil, order: nil, **kwargs, &block)
  Elements::ErrorSummary.new(self, object_name, title, link_base_errors_to:, order:, presenter:, **kwargs, &block).html
end

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

Generates a fieldset containing the contents of the block

Examples:

A fieldset containing address fields

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

A fieldset with the legend as a proc

= f.govuk_fieldset legend: -> { tag.h3('Skills') } do
  = f.govuk_text_area :physical
  = f.govuk_text_area :mental

Parameters:

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

    options for configuring the legend. Legend will be omitted if nil.

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

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

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

    configures or sets the caption content which is inserted above the label

  • kwargs (Hash) —

    a customizable set of options

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the legend element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



1139
1140
1141
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1139

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

#govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, javascript: false, before_input: nil, after_input: nil, choose_files_button_text: nil, drop_instruction_text: nil, multiple_files_chosen_text: nil, no_file_chosen_text: nil, entered_drop_zone_text: nil, left_drop_zone_text: nil, **kwargs, &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

A CV upload field with label as a proc

= f.govuk_file_field :cv, label: -> { tag.h3('Upload your CV') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

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

    configures or sets the caption content which is inserted above the label

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    configures the form group

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

    Configures whether to add HTML for the javascript-enhanced version of the component

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

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

    The text of the button that opens the file picker. Default is “Choose file”. If javascript is not provided, this option will be ignored.

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

    The text informing users they can drop files. Default is “or drop file”. If javascript is not provided, this option will be ignored.

  • multiple_files_chosen_text (Hash) (defaults to: nil) —

    The text displayed when multiple files have been chosen by the user. The component will replace the %count placeholder with the number of files selected. This uses the govuk-frontend pluralisation rules. If javascript is not provided, this option will be ignored.

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

    The text displayed when no file has been chosen by the user. Default is “No file chosen”. If javascript is not provided, this option will be ignored.

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

    The text announced by assistive technology when user drags files and enters the drop zone. Default is “Entered drop zone”. If javascript is not provided, this option will be ignored.

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

    The text announced by assistive technology when user drags files and leaves the drop zone without dropping. Default is “Left drop zone”. If javascript is not provided, this option will be ignored.

  • block (Block) —

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

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

    a customizable set of options

  • kwargs (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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

See Also:



1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1189

def govuk_file_field(
  attribute_name,
  label: {},
  caption: {},
  hint: {},
  form_group: {},
  javascript: false,
  before_input: nil,
  after_input: nil,
  choose_files_button_text: nil,
  drop_instruction_text: nil,
  multiple_files_chosen_text: nil,
  no_file_chosen_text: nil,
  entered_drop_zone_text: nil,
  left_drop_zone_text: nil,
  **kwargs,
  &block
)
  Elements::File.new(
    self,
    object_name,
    attribute_name,
    label:,
    caption:,
    hint:,
    form_group:,
    javascript:,
    before_input:,
    after_input:,
    choose_files_button_text:,
    drop_instruction_text:,
    multiple_files_chosen_text:,
    no_file_chosen_text:,
    entered_drop_zone_text:,
    left_drop_zone_text:,
    **kwargs,
    &block
  ).html
end

#govuk_label(attribute_name, text: nil, size: nil, hidden: false, tag: nil, caption: nil, **kwargs) ⇒ Object

Generates a form label without a form group or input

Examples:

A standalone label for the name field

= f.govuk_label :name, text: 'Full name', size: 'l', caption: { text: 'It must match your driving licence' }

Parameters:

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

    the label text

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

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

  • tag (Symbol, String) (defaults to: nil) —

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

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

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element



15
16
17
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 15

def govuk_label(attribute_name, text: nil, size: nil, hidden: false, tag: nil, caption: nil, **kwargs)
  GOVUKDesignSystemFormBuilder::Elements::Label.new(self, object_name, attribute_name, text:, size:, hidden:, tag:, caption:, **kwargs).html
end

#govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &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

A number field with the label supplied as a proc

= f.govuk_url_field :personal_best_over_100m,
  label: -> { tag.h3("How many seconds does it take you to run 100m?") }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • 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

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

    when true adds space between characters to increase the readability of sequences of letters and numbers. Defaults to false.

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the label

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

    configures the form group

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

    the text placed before the input. No prefix will be added if left nil

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

    the text placed after the input. No suffix will be added if left nil

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



292
293
294
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 292

def govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::Inputs::Number.new(self, object_name, attribute_name, hint:, label:, caption:, width:, extra_letter_spacing:, form_group:, prefix_text:, suffix_text:, before_input:, after_input:, **kwargs, &block).html
end

#govuk_password_field(attribute_name, hint: {}, label: {}, caption: {}, form_group: {}, show_password_text: config.default_show_password_text, hide_password_text: config.default_hide_password_text, show_password_aria_label_text: config.default_show_password_aria_label_text, hide_password_aria_label_text: config.default_hide_password_aria_label_text, password_shown_announcement_text: config.default_password_shown_announcement_text, password_hidden_announcement_text: config.default_password_hidden_announcement_text, **kwargs, &block) ⇒ Object

Generates a password input

Examples:

A password field

= f.govuk_password_field :password

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the label

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

    configures the form group

  • show_password_text (String) (defaults to: config.default_show_password_text) —

    button text when the password is hidden. Defaults to “Show”

  • hide_password_text (String) (defaults to: config.default_hide_password_text) —

    button text when the password is shown. Defaults to “Hide”

  • show_password_aria_label_text (String) (defaults to: config.default_show_password_aria_label_text) —

    button text exposed to assistive technologies, like screen readers, when the password is hidden. Defaults to “Show password”

  • hide_password_aria_label_text (String) (defaults to: config.default_hide_password_aria_label_text) —

    button text exposed to assistive technologies, like screen readers, when the password is visible. Defaults to “Hide password”

  • password_shown_announcement_text (String) (defaults to: config.default_password_shown_announcement_text) —

    Announcement made to screen reader users when their password has become visible in plain text. Defaults to “Your password is visible”

  • password_hidden_announcement_text (String) (defaults to: config.default_password_hidden_announcement_text) —

    Announcement made to screen reader users when their password has been obscured and is not visible. Defaults to “Your password is hidden”

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 326

def govuk_password_field(
  attribute_name,
  hint: {},
  label: {},
  caption: {},
  form_group: {},
  show_password_text: config.default_show_password_text,
  hide_password_text: config.default_hide_password_text,
  show_password_aria_label_text: config.default_show_password_aria_label_text,
  hide_password_aria_label_text: config.default_hide_password_aria_label_text,
  password_shown_announcement_text: config.default_password_shown_announcement_text,
  password_hidden_announcement_text: config.default_password_hidden_announcement_text,
  **kwargs,
  &block
)
  Elements::Password.new(
    self,
    object_name,
    attribute_name,
    hint:,
    label:,
    caption:,
    form_group:,
    show_password_text:,
    hide_password_text:,
    show_password_aria_label_text:,
    hide_password_aria_label_text:,
    password_shown_announcement_text:,
    password_hidden_announcement_text:,
    **kwargs,
    &block
  ).html
end

#govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &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

A phone field with the label supplied as a proc

= f.govuk_phone_field :work_number,
  label: -> { tag.h3('Work number') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • 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

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

    when true adds space between characters to increase the readability of sequences of letters and numbers. Defaults to false.

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the label

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

    configures the form group

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

    the text placed before the input. No prefix will be added if left nil

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

    the text placed after the input. No suffix will be added if left nil

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



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

def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::Inputs::Phone.new(self, object_name, attribute_name, hint:, label:, caption:, width:, extra_letter_spacing:, form_group:, prefix_text:, suffix_text:, before_input:, after_input:, **kwargs, &block).html
end

#govuk_radio_button(attribute_name, value, hint: {}, label: {}, link_errors: false, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Note:

This should only be used from within a #govuk_radio_buttons_fieldset

Generates a radio button

Examples:

A single radio button for our new favourite colour


= f.govuk_radio_buttons_fieldset :favourite_colour do
  = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    configures or sets the associated label content

  • 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 #govuk_error_summary from the error summary. Should only be set to true for the first radio button in a fieldset

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



731
732
733
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 731

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

#govuk_radio_buttons_fieldset(attribute_name, hint: {}, legend: {}, caption: {}, inline: false, small: false, form_group: {}, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Note:

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

Note:

To ensure the #govuk_error_summary link functions correctly ensure the first #govuk_radio_button is set to link_errors: true

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

Examples:

A radio button fieldset for favourite colours with a divider


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

A radio button fieldset with the legend supplied as a proc

= f.govuk_radio_buttons_fieldset :burger_id do
  @burgers,
  :id,
  :name,
  legend: -> { tag.h3('Which hamburger do you want with your meal?') } do
    = f.govuk_radio_button :burger_id, :regular, label: { text: 'Hamburger' }, link_errors: true
    = f.govuk_radio_button :burger_id, :cheese, label: { text: 'Cheeseburger' }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • legend (NilClass, Hash, Proc) (defaults to: {}) —

    options for configuring the legend. Legend will be omitted if nil.

  • 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

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

    configures or sets the caption content which is inserted above the legend

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

    configures the form group

  • block (Block) —

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

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the legend element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



699
700
701
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 699

def govuk_radio_buttons_fieldset(attribute_name, hint: {}, legend: {}, caption: {}, inline: false, small: false, form_group: {}, **kwargs, &block)
  Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint:, legend:, caption:, inline:, small:, form_group:, **kwargs, &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:



743
744
745
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 743

def govuk_radio_divider(text = config.default_radio_divider_text)
  tag.div(text, class: %(#{config.brand}-radios__divider))
end

#govuk_select(attribute_name, choices = nil, options: {}, label: {}, hint: {}, form_group: {}, caption: {}, before_input: nil, after_input: nil, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Generates a select element containing an option for every choice provided

Examples:

A select box with custom data attributes


@colours = [
  ["PapayaWhip", "pw",  { data: { hex: "#ffefd5" } }],
  ["Chocolate", "choc", { data: { hex: "#d2691e" } }],
]

= f.govuk_select :hat_colour, options_for_select(@colours)

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • choices (Array, Hash) (defaults to: nil) —

    The option values, usually provided via the options_for_select or grouped_options_for_select helpers.

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

    Options hash passed through to Rails’ select helper

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    configures or sets the associated label content

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

    configures the form group

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

    build the contents of the select element manually for exact control

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



554
555
556
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 554

def govuk_select(attribute_name, choices = nil, options: {}, label: {}, hint: {}, form_group: {}, caption: {}, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::Select.new(self, object_name, attribute_name, choices, options:, label:, hint:, form_group:, caption:, before_input:, after_input:, **kwargs, &block).html
end

#govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, inverse: false, prevent_double_click: true, validate: config.default_submit_validate, disabled: false, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

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

Note:

This helper always renders an <button type=‘submit’> tag. Previous versions of this gem rendered a +‘<input type=’submit’>‘ tag instead, but there is a longstanding bug with this approach where the top few pixels don’t initiate a submission when clicked.

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, Proc) (defaults to: config.default_submit_button_text) —

    the button text. When a Proc is provided its contents will be rendered within the button element

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

    makes the button red (warning) when true

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

    makes the button grey (secondary) when true

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

    inverts the colours of the button. Note this isn’t yet part of the design system.

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

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

  • validate (Boolean) (defaults to: config.default_submit_validate) —

    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

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

    makes the button disabled when true

  • block (Block) —

    When content is passed in via a block the submit element and the block content will be wrapped in a <div class=“govuk-button-group”> which will space the buttons and links within evenly.

  • kwargs (Hash) —

    a customizable set of options

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the button element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

Raises:

  • (ArgumentError) —

    raised if both warning and secondary are true

See Also:



971
972
973
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 971

def govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, inverse: false, prevent_double_click: true, validate: config.default_submit_validate, disabled: false, **kwargs, &block)
  Elements::Submit.new(self, text, warning:, secondary:, inverse:, prevent_double_click:, validate:, disabled:, **kwargs, &block).html
end

#govuk_text_area(attribute_name, hint: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, description_other_text: nil, under_limit_other_text: nil, under_limit_one_text: nil, at_limit_text: nil, over_limit_one_text: nil, over_limit_other_text: nil, **kwargs, &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_text_area :cv,
  label: { text: 'Tell us about your work history' },
  rows: 8,
  max_words: 300

A text area with injected content

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

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

A text area with the label supplied as a proc

= f.govuk_text_area :instructions,
  label: -> { tag.h3("How do you set it up?") }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the 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

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

    configures the form group

  • block (Block) —

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

  • characters_under_limit_other_text (String) —

    Text that informs the user they have X word/characters remaining. Default is “%count characters to go”. If javascript is not provided, this option will be ignored.

  • characters_under_limit_one_text (String) —

    Text that informs the user they have 1 word/character remaining. Default is “%count character to go”. If javascript is not provided, this option will be ignored.

  • characters_at_limit_text (String) —

    The text that informs the user they’ve reached the character limit. Default is “No characters left”. If javascript is not provided, this option will be ignored.

  • characters_over_limit_other_text (String) —

    Text that informs the user they have added X words/characters too many. Default is “%count characters to go”. If javascript is not provided, this option will be ignored.

  • characters_over_limit_one_text (String) —

    Text that informs the user they have added 1 word/character too many. Default is “%count character to go”. If javascript is not provided, this option will be ignored.

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the textarea element

  • kwargs (Hash) —

    additional arguments are applied as attributes to the textarea element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 417

def govuk_text_area(
  attribute_name,
  hint: {},
  label: {},
  caption: {},
  max_words: nil,
  max_chars: nil,
  rows: 5,
  threshold: nil,
  form_group: {},
  description_other_text: nil,
  under_limit_other_text: nil,
  under_limit_one_text: nil,
  at_limit_text: nil,
  over_limit_one_text: nil,
  over_limit_other_text: nil,
  **kwargs,
  &block
)
  Elements::TextArea.new(
    self,
    object_name,
    attribute_name,
    hint:,
    label:,
    caption:,
    max_words:,
    max_chars:,
    rows:,
    threshold:,
    form_group:,
    description_other_text:,
    under_limit_other_text:,
    under_limit_one_text:,
    at_limit_text:,
    over_limit_one_text:,
    over_limit_other_text:,
    **kwargs,
    &block
  ).html
end

#govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &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

A text field with the label supplied as a proc

= f.govuk_text_field :callsign,
  label: -> { tag.h3('Call-sign') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • 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

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

    when true adds space between characters to increase the readability of sequences of letters and numbers. Defaults to false.

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the label

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

    configures the form group

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

    the text placed before the input. No prefix will be added if left nil

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

    the text placed after the input. No suffix will be added if left nil

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



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

def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::Inputs::Text.new(self, object_name, attribute_name, hint:, label:, caption:, width:, extra_letter_spacing:, form_group:, prefix_text:, suffix_text:, before_input:, after_input:, **kwargs, &block).html
end

#govuk_time_field(attribute_name, hint: {}, legend: {}, caption: {}, omit_second: false, maxlength_enabled: false, segments: config.default_time_segments, segment_names: config.default_time_segment_names, before_inputs: nil, after_inputs: nil, form_group: {}, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Note:

When using this input values will be retrieved from the attribute if it is a Time object or a multiparam date hash

Generates three inputs for the hour, minute and second components of a time

Examples:

A regular time input with a legend, hint and injected content

= f.govuk_time_field :starts_at,
  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, the event will be all day

A time input with legend supplied as a proc

= f.govuk_time_field :finishes_at,
  legend: -> { tag.h3('When does the event finish?') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • legend (NilClass, Hash, Proc) (defaults to: {}) —

    options for configuring the legend. Legend will be omitted if nil.

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

    configures or sets the caption content which is inserted above the legend

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

    do not render a second input, only capture hour and minute

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

    adds maxlength attribute to hour, minute and second inputs (2)

  • segments (Hash) (defaults to: config.default_time_segments) —

    allows Rails’ multiparameter attributes to be overridden on a field-by-field basis. Hash must contain hour:, minute: and second: keys. Defaults to the default value set in the default_time_segments setting in DEFAULTS

  • segment_names (Hash) (defaults to: config.default_time_segment_names) —

    allows the day, month and year labels to be overridden. Hash must contain hour:, minute: and second: keys. Defaults to the default value set in the default_time_segment_names setting in DEFAULTS

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

    configures the form group

  • before_inputs (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_inputs (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the legend element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



1076
1077
1078
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1076

def govuk_time_field(attribute_name, hint: {}, legend: {}, caption: {}, omit_second: false, maxlength_enabled: false, segments: config.default_time_segments, segment_names: config.default_time_segment_names, before_inputs: nil, after_inputs: nil, form_group: {}, **kwargs, &block)
  Elements::Time.new(self, object_name, attribute_name, hint:, legend:, caption:, omit_second:, maxlength_enabled:, segments:, segment_names:, form_group:, before_inputs:, after_inputs:, **kwargs, &block).html
end

#govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &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

A url field with the label supplied as a proc

= f.govuk_url_field :work_website,
  label: -> { tag.h3("Enter your company's website") }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • hint (Hash, Proc) (defaults to: {}) —

    The content of the hint. No hint will be added if ‘text’ is left nil. When a Proc is supplied the hint will be wrapped in a div instead of a span

  • 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

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

    when true adds space between characters to increase the readability of sequences of letters and numbers. Defaults to false.

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

    configures or sets the associated label content

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

    configures or sets the caption content which is inserted above the label

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

    configures the form group

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

    the text placed before the input. No prefix will be added if left nil

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

    the text placed after the input. No suffix will be added if left nil

  • before_input (String, Proc) (defaults to: nil) —

    the content injected before the input. No content will be added if left nil

  • after_input (String, Proc) (defaults to: nil) —

    the content injected after the input. No content will be added if left nil

  • block (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

    the size of the caption, can be xl, l or m. Defaults to m

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the input element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



235
236
237
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 235

def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil, before_input: nil, after_input: nil, **kwargs, &block)
  Elements::Inputs::URL.new(self, object_name, attribute_name, hint:, label:, caption:, width:, extra_letter_spacing:, form_group:, prefix_text:, suffix_text:, before_input:, after_input:, **kwargs, &block).html
end