Class: Primer::Alpha::FormControl

Inherits:
Component
  • Object
show all
Defined in:
app/components/primer/alpha/form_control.rb

Overview

Wraps an input (or arbitrary content) with a label above and a caption and validation message beneath. NOTE: This FormControl component is designed for wrapping inputs that aren’t supported by the Primer forms framework.

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 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(label:, caption: nil, validation_message: nil, required: false, visually_hide_label: false, full_width: false, **system_arguments) ⇒ FormControl

Returns a new instance of FormControl.

Examples:

Default

<%= render(Primer::Alpha::FormControl.new(label: "Best character")) do |component| %>
  <% component.with_input do |input_arguments| %>
    <%= render(Primer::Alpha::SegmentedControl.new("aria-label": "Best character", **input_arguments)) do |seg| %>
      <% seg.with_item(label: "Han Solo") %>
      <% seg.with_item(label: "Luke Skywalker") %>
      <% seg.with_item(label: "Leia Organa") %>
    <% end %>
  <% end %>
<% end %>

Parameters:

  • label (String) —

    Label text displayed above the input.

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

    Describes the field and what sort of input it expects. Displayed below the input. Note that the caption slot is also available and takes precedence over this argument when provided.

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

    A string displayed in red between the caption and the input indicating the input’s contents are invalid.

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

    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.

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

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

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

    When set to true, the form control will take up all the horizontal space allowed by its container.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'app/components/primer/alpha/form_control.rb', line 31

def initialize(label:, caption: nil, validation_message: nil, required: false, visually_hide_label: false, full_width: false, **system_arguments)
  @label = label
  @init_caption = caption
  @validation_message = validation_message
  @required = required
  @visually_hide_label = visually_hide_label
  @full_width = full_width
  @system_arguments = system_arguments

  @system_arguments[:classes] = class_names(
    @system_arguments[:classes],
    "FormControl",
    "FormControl--fullWidth" => full_width?
  )

  @label_arguments = {
    classes: class_names(
      "FormControl-label",
      visually_hide_label? ? "sr-only" : nil
    )
  }

  base_id = self.class.generate_id
  @validation_id = "validation-#{base_id}"
  @caption_id = "caption-#{base_id}"

  @validation_arguments = {
    classes: "FormControl-inlineValidation",
    id: @validation_id
  }
end

Instance Method Details

#full_width? ⇒ Boolean

Returns:

  • (Boolean) 


80
81
82
 
# File 'app/components/primer/alpha/form_control.rb', line 80

def full_width?
  @full_width
end

#required? ⇒ Boolean

Returns:

  • (Boolean) 


72
73
74
 
# File 'app/components/primer/alpha/form_control.rb', line 72

def required?
  @required
end

#visually_hide_label? ⇒ Boolean

Returns:

  • (Boolean) 


76
77
78
 
# File 'app/components/primer/alpha/form_control.rb', line 76

def visually_hide_label?
  @visually_hide_label
end

#with_input(&block) ⇒ Object 



68
69
70
 
# File 'app/components/primer/alpha/form_control.rb', line 68

def with_input(&block)
  @input_block = block
end