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



326
327
328
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 326

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



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 120

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: {}, before_input: nil, after_input: nil) ⇒ 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

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

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

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

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

  • & (Block) —

    build the contents of the select element manually for exact control

Options Hash (label:):

  • text (String) —

    the label text

  • size (String) —

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

  • tag (Symbol, String) —

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

  • hidden (Boolean) —

    control the 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:



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

def govuk_combobox(attribute_name, options_or_src = [], options: {}, label: {}, hint: {}, form_group: {},
                   caption: {}, before_input: nil, after_input: nil, **, &)
  Elements::Combobox.new(
    self, object_name, attribute_name, options_or_src,
    options:, label:, hint:, form_group:, caption:, before_input:, after_input:, **, &
  ).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') }


263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 263

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


147
148
149
150
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 147

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


154
155
156
157
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 154

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


138
139
140
141
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 138

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



311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 311

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



205
206
207
208
209
210
 
# File 'lib/katalyst/govuk/form_builder/builder.rb', line 205

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