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

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



853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 853

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'

See Also:



878
879
880
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 878

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

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



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

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

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



749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 749

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

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



570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 570

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: {}, **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?") }

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

See Also:



446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 446

def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, hint: {}, label: {}, caption: {}, form_group: {}, **kwargs, &block)
  Elements::CollectionSelect.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method:,
    text_method:,
    hint:,
    label:,
    caption:,
    options:,
    form_group:,
    **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, 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 eligable 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?') }

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

See Also:



965
966
967
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 965

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, 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:, **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, **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: '[email protected]'

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

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

See Also:



175
176
177
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 175

def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: 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:, **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'

Options Hash (**kwargs):

  • kwargs (Hash) —

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

See Also:



995
996
997
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 995

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

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

See Also:



1028
1029
1030
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1028

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

A CV upload field with label as a proc

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

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:



1070
1071
1072
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 1070

def govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, javascript: false, **kwargs, &block)
  Elements::File.new(self, object_name, attribute_name, label:, caption:, hint:, form_group:, javascript:, **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' }



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, **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?") }

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

See Also:



282
283
284
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 282

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

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



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 316

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, **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') }

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

See Also:



123
124
125
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 123

def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: 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:, **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' }

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

See Also:



672
673
674
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 672

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

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

See Also:



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

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'

See Also:



684
685
686
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 684

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: {}, **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)

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

See Also:



495
496
497
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 495

def govuk_select(attribute_name, choices = nil, options: {}, label: {}, hint: {}, form_group: {}, caption: {}, **kwargs, &block)
  Elements::Select.new(self, object_name, attribute_name, choices, options:, label:, hint:, form_group:, caption:, **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'

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the button element

Raises:

  • (ArgumentError) —

    raised if both warning and secondary are true

See Also:



912
913
914
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 912

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: {}, **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?") }

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

See Also:



402
403
404
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 402

def govuk_text_area(attribute_name, hint: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, **kwargs, &block)
  Elements::TextArea.new(self, object_name, attribute_name, hint:, label:, caption:, max_words:, max_chars:, rows:, threshold:, form_group:, **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, **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') }

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

See Also:



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

def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: 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:, **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, **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") }

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

See Also:



227
228
229
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 227

def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: 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:, **kwargs, &block).html
end