Class: Primer::Alpha::MultiInput

Inherits:
Component
  • Object
show all
Includes:
Forms::Dsl::InputMethods
Defined in:
app/components/primer/alpha/multi_input.rb

Overview

Multi inputs are comprised of multiple constituent fields, only one of which is visible at a given time. They are designed for situations where constituent inputs are shown or hidden based on the value of another field. For example, consider an address form. If the user chooses the USA as the country, the region input should show a list of states and US territories; if the user instead chooses Canada, the region input should show a list of Canadian provinces, etc.

Unlike everywhere else in Primer forms, constituent inputs are not directly passed a ‘name` attribute. Instead, developers pass a `name` attribute to the multi input itself. The multi input then automatically assigns each constituent input the same name. This is done so that the multi input looks like a single field from the server’s point of view. Using the address form example from earlier, this means only one value - either a US state or a Canadian provice - will be submitted to the server under the ‘region` key.

Actually, that’s not quite true. Constituent inputs are given a ‘name`, but it’s added to the input as the ‘data-name` attribute as a way to identify constituent inputs, and will not be sent to the server.

Constant Summary

Constants inherited from Component

Component::INVALID_ARIA_LABEL_TAGS

Constants included from Status::Dsl

Status::Dsl::STATUSES

Constants included from ViewHelper

ViewHelper::HELPERS

Constants included from TestSelectorHelper

TestSelectorHelper::TEST_SELECTOR_TAG

Constants included from FetchOrFallbackHelper

FetchOrFallbackHelper::InvalidValueError

Constants included from Primer::AttributesHelper

Primer::AttributesHelper::PLURAL_ARIA_ATTRIBUTES, Primer::AttributesHelper::PLURAL_DATA_ATTRIBUTES

Instance Method Summary collapse

Methods included from Forms::Dsl::InputMethods

#action_menu, #button, #check_box, #check_box_group, #fields_for, #hidden, #inputs, #multi, #radio_button_group, #select_list, #separator, #submit, #text_area, #text_field

Methods inherited from Component

deprecated?, generate_id

Methods included from JoinStyleArgumentsHelper

#join_style_arguments

Methods included from TestSelectorHelper

#add_test_selector

Methods included from FetchOrFallbackHelper

#fetch_or_fallback, #fetch_or_fallback_boolean, #silence_deprecations?

Methods included from ClassNameHelper

#class_names

Methods included from Primer::AttributesHelper

#aria, #data, #merge_aria, #merge_data, #merge_prefixed_attribute_hashes

Constructor Details

#initialize ⇒ Object

Parameters:

  • name (String) —

    Value for the HTML name attribute.

  • id (String) —

    Value for the HTML id attribute.

  • class (String) —

    CSS classes to include in the input’s HTML ‘class` attribute. Exists for compatibility with Rails form builders.

  • classes (Array) —

    CSS classes to include in the input’s HTML ‘class` attribute. Combined with the `:class` argument. The list may contain strings, hashes, or `nil` values, and is automatically cleaned up by Primer’s [‘class_name` helper](github.com/primer/view_components/blob/c9cb95c98fee3e2e27f4a10683f555e22285e7f1/app/lib/primer/class_name_helper.rb) (`nils`, falsy entries, and blank strings are ignored).

  • caption (String) —

    A string describing the field and what sorts of input it expects. Displayed below the input.

  • label (String) —

    Label text displayed above the input.

  • visually_hide_label (Boolean) —

    When set to ‘true`, hides the label. Although the label will be hidden visually, it will still be visible to screen readers.

  • disabled (Boolean) —

    When set to ‘true`, the input will not accept keyboard or mouse input.

  • hidden (Boolean) —

    When set to ‘true`, visually hides the field.

  • invalid (Boolean) —

    If set to ‘true`, the input will be rendered with a red border. Implied if `validation_message` is truthy. This option is set to `true` automatically if the model object associated with the form reports that the input is invalid via Rails validations. It is provided for cases where the form does not have an associated model. If the input is invalid as determined by Rails validations, setting `invalid` to `false` will have no effect.

  • validation_message (String) —

    A string displayed between the caption and the input indicating the input’s contents are invalid. This option is, by default, set to the first Rails validation message for the input (assuming the form is associated with a model object). Use ‘validation_message` to override the default or to provide a validation message in case there is no associated model object.

  • label_arguments (Hash) —

    Attributes that will be passed to Rails’ ‘builder.label` method. These can be HTML attributes or any of the other label options Rails supports. They will appear as HTML attributes on the `<label>` tag.

  • scope_name_to_model (Boolean) —

    Default ‘true`. When set to `false`, prevents the model name from prefixing the field name. For example, if the field name is `my_field`, Rails will normally emit an HTML name attribute of `model`. Setting `scope_name_to_model` to `false` will cause Rails to emit `my_field` instead.

  • scope_id_to_model (Boolean) —

    Default ‘true`. When set to `false`, prevents the model name from prefixing the field ID. For example, if the field name is `my_field`, Rails will normally emit an HTML ID attribute of `model_my_field`. Setting `scope_id_to_model` to `false` will cause Rails to emit `my_field` instead.

  • required (Boolean) —

    Default ‘false`. When set to `true`, causes an asterisk (*) to appear next to the field’s label indicating it is a required field. Note that this option explicitly does not add a ‘required` HTML attribute. Doing so would enable native browser validations, which are inaccessible and inconsistent with the Primer design system.

  • aria (Hash) —

    Key/value pairs that represent Aria attributes and their values. Eg. ‘aria: { current: true }` becomes `aria-current=“true”`.

  • data (Hash) —

    Key/value pairs that represent data attributes and their values. Eg. ‘data: { foo: “bar” }` becomes `data-foo=“bar”`.

  • system_arguments (Hash) —

    A hash of attributes passed to the underlying Rails builder methods. These options may mean something special depending on the type of input, otherwise they are emitted as HTML attributes. See the [Rails documentation](guides.rubyonrails.org/form_helpers.html) for more information. In addition, the usual Primer utility arguments are accepted in system arguments. For example, passing ‘mt: 2` will add the `mt-2` class to the input. See the Primer system arguments docs for details.




# File 'app/components/primer/alpha/multi_input.rb', line 43