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

  • block (Block) —

    any HTML passed in will form the contents of the fieldset

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

    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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


789
790
791
792
793
794
795
796
797
798
799
800
801
802
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 789

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

#govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, classes: nil, form_group: {}, multiple: true, &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

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

    Classes to add to the checkbox container.

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

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 746

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

#govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, small: false, classes: nil, form_group: {}, include_hidden: config.default_collection_check_boxes_include_hidden, &block) ⇒ ActiveSupport::SafeBuffer

Generate a list of check boxes from a collection

Examples:

A collection of check boxes for sandwich fillings


@fillings = [
  OpenStruct.new(id: 'pastrami', name: 'Pastrami', description: 'Brined, smoked, steamed and seasoned'),
  OpenStruct.new(id: 'cheddar', name: 'Cheddar', description: 'A sharp, off-white natural cheese')
]

= f.govuk_collection_check_boxes :desired_filling,
  @fillings,
  :id,
  :name,
  :description,
  legend: { text: 'What do you want in your sandwich?', size: 'm' },
  hint: { text: "If it isn't listed here, tough luck" },
  inline: false,
  classes: 'app-overflow-scroll',

A collection of check boxes for types of bread

= f.govuk_collection_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

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

    Classes to add to the checkbox container.

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

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output


686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 686

def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, small: false, classes: nil, form_group: {}, include_hidden: config.default_collection_check_boxes_include_hidden, &block)
  Elements::CheckBoxes::Collection.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method: value_method,
    text_method: text_method,
    hint_method: hint_method,
    hint: hint,
    legend: legend,
    caption: caption,
    small: small,
    classes: classes,
    form_group: form_group,
    include_hidden: include_hidden,
    &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: false, classes: nil, include_hidden: config.default_collection_radio_buttons_include_hidden, form_group: {}, &block) ⇒ ActiveSupport::SafeBuffer

Note:

Unlike the Rails #collection_radio_buttons helper, this version can also insert hints per item in the collection by supplying a :hint_method

Note:

:bold_labels, while false by default, is set to true when a :hint_method is provided. This is done to make the label stand out more from the hint.

Generates a radio button for each item in the supplied collection

Examples:

A collection of radio buttons for favourite colours, labels capitalised via a proc


@colours = [
  OpenStruct.new(id: 'red', name: 'Red', description: 'Roses are red'),
  OpenStruct.new(id: 'blue', name: 'Blue', description: 'Violets are... purple?')
]

= f.govuk_collection_radio_buttons :favourite_colour,
  @colours,
  :id,
  ->(option) { option.name.upcase },
  :description,
  legend: { text: 'Pick your favourite colour', size: 'm' },
  hint: { text: 'If you cannot find the exact match choose something close' },
  inline: false

A collection of radio buttons for grades with injected content

= f.govuk_collection_radio_buttons :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: false) —

    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

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

    Classes to add to the radio button container.

  • 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


504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 504

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: false, classes: nil, include_hidden: config.default_collection_radio_buttons_include_hidden, form_group: {}, &block)
  Elements::Radios::Collection.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method: value_method,
    text_method: text_method,
    hint_method: hint_method,
    hint: hint,
    legend: legend,
    caption: caption,
    inline: inline,
    small: small,
    bold_labels: bold_labels,
    classes: classes,
    form_group: form_group,
    include_hidden: include_hidden,
    &block
  ).html
end

#govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint: {}, label: {}, caption: {}, form_group: {}, &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

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

    Options hash passed through to Rails' collection_select helper

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

    HTML Options hash passed through to Rails' collection_select helper

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

    configures the form group

  • block (Block) —

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

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

    a customizable set of options

Options Hash (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:):

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


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

def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint: {}, label: {}, caption: {}, form_group: {}, &block)
  Elements::Select.new(
    self,
    object_name,
    attribute_name,
    collection,
    value_method: value_method,
    text_method: text_method,
    hint: hint,
    label: label,
    caption: caption,
    options: options,
    html_options: html_options,
    form_group: form_group,
    &block
  ).html
end

#govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group: {}, wildcards: false, &block) ⇒ ActiveSupport::SafeBuffer

Note:

When using this input be aware that Rails's multiparam time and date handling falls foul of this bug, so incorrect dates like 2019-09-31 will be 'rounded' up to 2019-10-01.

Generates three inputs for the day, month and year components of a date

Examples:

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

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

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

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

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

    add an 'X' to the day and month patterns so users can add approximate dates

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

    configures the form group

  • block (Block) —

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

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

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

Options Hash (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:):

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


880
881
882
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 880

def govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group: {}, wildcards: false, &block)
  Elements::Date.new(self, object_name, attribute_name, hint: hint, legend: legend, caption: caption, date_of_birth: date_of_birth, omit_day: omit_day, form_group: form_group, wildcards: wildcards, &block).html
end

#govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, 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') }

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

  • 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

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

  • classes (Array, String) —

    sets the form group's classes

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


158
159
160
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 158

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

#govuk_error_summary(title = config.default_error_summary_title, link_base_errors_to: nil) ⇒ 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.

See Also:


898
899
900
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 898

def govuk_error_summary(title = config.default_error_summary_title, link_base_errors_to: nil)
  Elements::ErrorSummary.new(self, object_name, title, link_base_errors_to: link_base_errors_to).html
end

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

Generates a fieldset containing the contents of the block

Examples:

A fieldset containing address fields

= f.govuk_fieldset legend: { text: 'Address' } 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

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

See Also:


930
931
932
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 930

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

#govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, **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

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

  • classes (Array, String) —

    sets the form group's classes

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


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

def govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, **kwargs, &block)
  Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint: hint, form_group: form_group, **kwargs, &block).html
end

#govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, 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?") }

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

  • 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

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

  • classes (Array, String) —

    sets the form group's classes

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


313
314
315
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 313

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

#govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block) ⇒ ActiveSupport::SafeBuffer

Generates a input of type password

Examples:

A password field

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

A password field with injected content

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

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

A password field with the label supplied as a proc

= f.govuk_password_field :passcode,
  label: -> { tag.h3('What is your secret pass code?') }

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

  • 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

  • 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 (form_group:):

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

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:


208
209
210
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 208

def govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
  Elements::Inputs::Password.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &block).html
end

#govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, 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') }

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

  • 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

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

  • classes (Array, String) —

    sets the form group's classes

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


107
108
109
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 107

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

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

Note:

This should only be used from within a #govuk_radio_buttons_fieldset

Generates a radio button

Examples:

A 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

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


607
608
609
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 607

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

#govuk_radio_buttons_fieldset(attribute_name, hint: {}, legend: {}, caption: {}, inline: false, small: false, classes: nil, form_group: {}, &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

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

    Classes to add to the radio button container.

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

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


576
577
578
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 576

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


619
620
621
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 619

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

#govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, classes: nil, prevent_double_click: true, validate: false, disabled: false, &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 <input type='submit'> tag, HTML content is not supported inside. You can place <button> tags inside the form to have the same effect

Generates a submit button, green by default

Examples:

A submit button with custom text, double click protection and an inline cancel link

= f.govuk_submit "Proceed", prevent_double_click: true do
  = link_to 'Cancel', some_other_path, class: 'govuk-button__secondary'

Parameters:

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

    the button text

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

    makes the button red (warning) when true

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

    makes the button grey (secondary) when true

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

    Classes to add to the submit button

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

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

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

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

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

Raises:

  • (ArgumentError) —

    raised if both warning and secondary are true

See Also:


832
833
834
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 832

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

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

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

  • classes (Array, String) —

    sets the form group's classes

  • kwargs (Hash) —

    additional attributes added to the form group

Options Hash (**kwargs):

  • kwargs (Hash) —

    additional arguments are applied as attributes to the textarea element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:


369
370
371
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 369

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: hint, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, form_group: form_group, **kwargs, &block).html
end

#govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, 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') }

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

  • 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

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

  • classes (Array, String) —

    sets the form group's classes

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


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

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

#govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, 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") }

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

  • 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

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

  • classes (Array, String) —

    sets the form group's classes

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


259
260
261
 
# File 'lib/govuk_design_system_formbuilder/builder.rb', line 259

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