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

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

Instance Method Summary collapse

Instance Method Details

#attachment_preview_url(representation) ⇒ String?

URL for an attachment preview. ActiveStorage's representation route lives in the application's route set, so engine-mounted forms resolve it through main_app. Returns nil when no route is available, in which case the figure renders without a preview.

Parameters:

  • representation (ActiveStorage::Variant, ActiveStorage::VariantWithRecord, ActiveStorage::Preview)

Returns:

  • (String, nil) 


475
476
477
478
479
480
481
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 475

def attachment_preview_url(representation)
  if @template.respond_to?(:rails_representation_path)
    @template.rails_representation_path(representation)
  elsif @template.respond_to?(:main_app) && @template.main_app.respond_to?(:rails_representation_path)
    @template.main_app.rails_representation_path(representation)
  end
end

#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



464
465
466
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 464

def fieldset_context
  @fieldset_context ||= []
end

#govuk_attachment_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, before_input: nil, after_input: nil, choose_files_button_text: nil, drop_instruction_text: nil, multiple_files_chosen_text: nil, multiple_files_chosen_one_text: nil, multiple_files_chosen_other_text: nil, no_file_chosen_text: nil, entered_drop_zone_text: nil, left_drop_zone_text: nil, upload_succeeded_text: nil, upload_failed_text: nil, retry_button_text: nil, file_removed_text: nil, remove_button_text: nil, remove_button_content_text: nil, direct_upload: true, direct_upload_url: (self.direct_upload_url if direct_upload)) ⇒ Object

Generates an input of type file with active storage and preview support.

Examples:

A photo upload field with file type specifier and injected content

= f.govuk_attachment_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_attachment_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

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

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

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

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

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

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

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

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

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

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

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

    The text displayed when JavaScript is enabled and one file has been chosen by the user. The component will replace the %count placeholder with the number of files selected. This can also be set by passing a hash with key one: to multiple_files_chosen_text.

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

    The text displayed when JavaScript is enabled and multiple files have been chosen by the user. The component will replace the %count placeholder with the number of files selected. This can also be set by passing a hash with key other: to multiple_files_chosen_text.

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

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

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

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

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

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

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

    The status shown in a figure's caption when its direct upload completes. Default is "Uploaded successfully". If javascript is not provided, this option will be ignored.

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

    The status shown in a figure's caption when its direct upload fails. Default is "Upload failed — try again". If javascript is not provided, this option will be ignored.

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

    The label of the retry control offered on a failed upload. Default is "Try again". If javascript is not provided, this option will be ignored.

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

    The text announced by assistive technology when a figure is removed. The component will replace the %filename placeholder with the removed file's name. Default is "%filename removed". If javascript is not provided, this option will be ignored.

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

    The accessible name of each figure's remove control and the text of its no-JavaScript remove option. The component will replace the %filename placeholder with the figure's file name. Default is "Remove %filename".

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

    The visible content of each figure's remove button. Default is "Remove".

  • & (Block) —

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

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

    a customizable set of options

  • kwargs (Hash) —

    a customizable set of options

Options Hash (label:):

  • text (String) —

    the label text

  • tag (Symbol, String) —

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

  • size (String) —

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

  • hidden (Boolean) —

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the label element

Options Hash (caption:):

  • text (String) —

    the caption text

  • size (String) —

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

  • kwargs (Hash) —

    additional arguments are applied as attributes on the caption span element

Options Hash (hint:):

  • text (String) —

    the hint text

  • kwargs (Hash) —

    additional arguments are applied as attributes to the hint

Options Hash (form_group:):

  • kwargs (Hash) —

    additional attributes added to the form group

See Also:



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 327

def govuk_attachment_field(
  attribute_name,
  label: {},
  caption: {},
  hint: {},
  form_group: {},
  before_input: nil,
  after_input: nil,
  choose_files_button_text: nil,
  drop_instruction_text: nil,
  multiple_files_chosen_text: nil,
  multiple_files_chosen_one_text: nil,
  multiple_files_chosen_other_text: nil,
  no_file_chosen_text: nil,
  entered_drop_zone_text: nil,
  left_drop_zone_text: nil,
  upload_succeeded_text: nil,
  upload_failed_text: nil,
  retry_button_text: nil,
  file_removed_text: nil,
  remove_button_text: nil,
  remove_button_content_text: nil,
  direct_upload: true,
  direct_upload_url: (self.direct_upload_url if direct_upload),
  **,
  &
)
  Elements::Attachment.new(
    self,
    object_name,
    attribute_name,
    label:,
    caption:,
    hint:,
    form_group:,
    before_input:,
    after_input:,
    direct_upload_url:,
    choose_files_button_text:,
    drop_instruction_text:,
    multiple_files_chosen_text:,
    multiple_files_chosen_one_text:,
    multiple_files_chosen_other_text:,
    no_file_chosen_text:,
    entered_drop_zone_text:,
    left_drop_zone_text:,
    upload_succeeded_text:,
    upload_failed_text:,
    retry_button_text:,
    file_removed_text:,
    remove_button_text:,
    remove_button_content_text:,
    **,
    &
  ).html
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



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 123

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:



246
247
248
249
250
251
252
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 246

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


389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 389

def govuk_document_field(attribute_name,
                         label: {},
                         caption: {},
                         hint: {},
                         form_group: {},
                         mime_types: config.document_mime_types,
                         **,
                         &)
  if config.use_legacy_file_fields
    Elements::Document.new(
      self, object_name, attribute_name, label:, caption:, hint:, form_group:, mime_types:, **, &
    ).html
  else
    govuk_attachment_field(
      attribute_name, label:, caption:, hint:, form_group:, accept: mime_types&.join(","), **, &
    )
  end
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


150
151
152
153
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 150

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


157
158
159
160
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 157

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


141
142
143
144
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 141

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



443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 443

def govuk_image_field(attribute_name,
                      label: {},
                      caption: {},
                      hint: {},
                      form_group: {},
                      mime_types: config.image_mime_types,
                      **,
                      &)
  if config.use_legacy_file_fields
    Elements::Image.new(
      self, object_name, attribute_name, label:, caption:, hint:, form_group:, mime_types:, **, &
    ).html
  else
    govuk_attachment_field(
      attribute_name, label:, caption:, hint:, form_group:, accept: mime_types&.join(","), **, &
    )
  end
end

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

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

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



200
201
202
203
204
205
 
# File 'app/helpers/katalyst/govuk/form_builder/builder.rb', line 200

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