Module: Katalyst::GOVUK::FormBuilder::Builder

Extended by:
ActiveSupport::Concern
Defined in:
lib/katalyst/govuk/form_builder/builder.rb

Instance Method Summary collapse

Instance Method Details

#fieldset_context ⇒ Object

Keep track of whether we are inside a fieldset This allows labels to default to bold (“s”) normally but use the default otherwise



365
366
367
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 365

def fieldset_context
  @fieldset_context ||= []
end

#govuk_check_box_field(attribute_name, value = 1, unchecked_value = 0, small: true, hint: {}, label: {}, link_errors: false) ⇒ ActiveSupport::SafeBuffer

Generates a check box within a fieldset to be used as a boolean toggle for a single attribute. The values are 1 (toggled on), and 0 (toggled off).

Examples:

A single check box for terms and conditions

= f.govuk_check_box_field :terms_agreed,
  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

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

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

  • 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 checkbox should be linked to from #govuk_error_summary

  • block (Block) —

    any HTML passed in will form the contents of the fieldset

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

    a customizable set of options

  • kwargs (Hash) —

    a customizable set of options

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

Options Hash (label:):

  • text (String) —

    the label text

  • size (String) —

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

  • tag (Symbol, String) —

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

  • hidden (Boolean) —

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 165

def govuk_check_box_field(attribute_name, value = 1, unchecked_value = 0,
                          small: true, hint: {}, label: {}, link_errors: false, **, &)
  govuk_check_boxes_fieldset(attribute_name, legend: nil, multiple: false, small:) do
    fieldset_context.pop # undo push from fieldset extension, labels should be bold unless already nested
    checkbox = govuk_check_box(attribute_name, value, unchecked_value,
                               hint:,
                               label:,
                               link_errors:,
                               multiple:    false,
                               exclusive:   false,
                               **, &)
    fieldset_context.push attribute_name # restore push from fieldset
    checkbox
  end
end

#govuk_combobox(attribute_name, options_or_src = [], options: {}, label: {}, hint: {}, form_group: {}, caption: {}) ⇒ ActiveSupport::SafeBuffer

Generates a combobox element that uses Hotwire Combobox to generate a combobox selection element.

Examples:

A combobox that allows the user to choose from a list of states


= f.combobox "state", State.all

A combobox that allows the user to choose from an asynchronous states endpoint


= f.combobox "state", states_path

A multi-select combobox that allows the user to choose multiple states


= f.combobox "state", State.all, multiselect_chip_src: states_chips_path

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

  • options_or_src (Array) (defaults to: []) —

    The option values or a source path for async combobox

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

    Options hash passed through to the combobox helper

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

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

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

    configures or sets the associated label content

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

    configures the form group

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 visibility of the label. Hidden labels will still be read by screenreaders

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



291
292
293
294
295
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 291

def govuk_combobox(attribute_name, options_or_src = [], options: {}, label: {}, hint: {}, form_group: {},
                   caption: {}, **, &)
  Elements::Combobox.new(self, object_name, attribute_name, options_or_src,
                         options:, label:, hint:, form_group:, caption:, **, &).html
end

#govuk_document_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, mime_types: config.document_mime_types) ⇒ Object

Generates a file input element for uploading documents.

Examples:

A upload field with label as a proc

= f.govuk_document_field :data, label: -> { tag.h3('Upload your document') }


302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 302

def govuk_document_field(attribute_name,
                         label: {},
                         caption: {},
                         hint: {},
                         form_group: {},
                         mime_types: config.document_mime_types,
                         **,
                         &)
  Elements::Document.new(
    self, object_name, attribute_name, label:, caption:, hint:, form_group:, mime_types:, **, &
  ).html
end

#govuk_enum_check_boxes(attribute_name) ⇒ Object

Generates a checkbox fieldset for an enum defined in the model.

See Also:

  • GOVUKDesignSystemFormBuilder::Builder#govuk_collection_check_boxes


192
193
194
195
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 192

def govuk_enum_check_boxes(attribute_name, **, &)
  govuk_collection_check_boxes(attribute_name, enum_values(attribute_name),
                               :itself, enum_labels_for(attribute_name), **, &)
end

#govuk_enum_radio_buttons(attribute_name) ⇒ Object

Generates a radio buttons fieldset for an enum defined in the model.

See Also:

  • GOVUKDesignSystemFormBuilder::Builder#govuk_collection_radio_buttons


199
200
201
202
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 199

def govuk_enum_radio_buttons(attribute_name, **, &)
  govuk_collection_radio_buttons(attribute_name, enum_values(attribute_name),
                                 :itself, enum_labels_for(attribute_name), **, &)
end

#govuk_enum_select(attribute_name) ⇒ Object

Generates a select for an enum defined in the model.

See Also:

  • GOVUKDesignSystemFormBuilder::Builder#govuk_collection_select


183
184
185
186
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 183

def govuk_enum_select(attribute_name, **, &)
  govuk_collection_select(attribute_name, enum_values(attribute_name),
                          :itself, enum_labels_for(attribute_name), **, &)
end

#govuk_image_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, mime_types: config.image_mime_types) ⇒ ActiveSupport::SafeBuffer

Generates a file input element with a preview for uploading images.

Examples:

An image field with injected content

= f.govuk_image_field :incident_image,
  label: { text: 'Attach a picture of the incident' } do

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

A image upload field with label as a proc

= f.govuk_image_field :image, label: -> { tag.h3('Upload your image') }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

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

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

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

    configures or sets the associated label content

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

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

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

    configures the form group

  • & (Block) —

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

  • kwargs (Hash) —

    a customizable set of options

Options Hash (label:):

  • text (String) —

    the label text

  • size (String) —

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

  • tag (Symbol, String) —

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

  • hidden (Boolean) —

    control the visibility of the label. Hidden labels will still be read by screen readers

  • 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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 350

def govuk_image_field(attribute_name,
                      label: {},
                      caption: {},
                      hint: {},
                      form_group: {},
                      mime_types: config.image_mime_types,
                      **,
                      &)
  Elements::Image.new(
    self, object_name, attribute_name, label:, caption:, hint:, form_group:, mime_types:, **, &
  ).html
end

#govuk_rich_text_area(attribute_name, hint: {}, label: {}, caption: {}, form_group: {}) ⇒ ActiveSupport::SafeBuffer

Generates a pair of trix-toolbar and trix-editor elements with a label, optional hint. Requires action-text to be correctly setup in the application

Examples:

A rich text area with injected content

= f.govuk_rich_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 rich text area with the label supplied as a proc

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

A rich text area with a custom direct upload url and a custom stimulus controller

= f.govuk_rich_text_area :description,
  data: {
          direct_upload_url: direct_uploads_url,
          controller:        "content--editor--trix",
          action:            "trix-initialize->content--editor--trix#trixInitialize",
        }

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

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

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

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

    configures or sets the associated label content

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

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

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

    configures the form group

  • & (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 visibility of the label. Hidden labels will still be read by screen readers

  • 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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output



250
251
252
253
254
255
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 250

def govuk_rich_text_area(attribute_name, hint: {}, label: {}, caption: {}, form_group: {}, **, &)
  Elements::RichTextArea.new(
    self, object_name, attribute_name,
    hint:, label:, caption:, form_group:, **, &
  ).html
end

#govuk_time_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false, form_group: {}, prefix_text: nil, suffix_text: nil) ⇒ ActiveSupport::SafeBuffer

Generates a input of type time

Examples:

A required time field with a placeholder

= f.govuk_time_field :time,
  label: { text: 'Event time' },
  hint: { text: 'Assumes the server timezone' },
  required: true,
  placeholder: '08:00am'

Parameters:

  • attribute_name (Symbol) —

    The name of the attribute

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

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

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

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

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

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

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

    configures or sets the associated label content

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

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

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

    configures the form group

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

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

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

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

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

Returns:

  • (ActiveSupport::SafeBuffer) —

    HTML output

See Also:



132
133
134
135
136
137
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 132

def govuk_time_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, extra_letter_spacing: false,
                     form_group: {}, prefix_text: nil, suffix_text: nil, **, &)
  Elements::Time.new(self, object_name, attribute_name,
                     hint:, label:, caption:, width:, extra_letter_spacing:, form_group:, prefix_text:,
                     suffix_text:, **, &).html
end