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, #extract_data, #merge_aria, #merge_data, #merge_prefixed_attribute_hashes

Methods included from ExperimentalSlotHelpers

included

Methods included from ExperimentalRenderHelpers

included

Constructor Details

#initialize(label:, caption: nil, validation_message: nil, required: false, visually_hide_label: false, full_width: false, label_arguments: {}, **system_arguments) ⇒ FormControl

Returns a new instance of FormControl.

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.

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

    HTML attributes to attach to the ‘<label>` element that labels the input.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'app/components/primer/alpha/form_control.rb', line 52

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

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

  @label_arguments[:classes] = class_names(
    @label_arguments.delete(:classes),
    "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

Whether or not the form control should take up all the horizontal space allowed by its container.

Returns:

  • (Boolean) 


107
108
109
 
# File 'app/components/primer/alpha/form_control.rb', line 107

def full_width?
  @full_width
end

#required? ⇒ Boolean

Whether or not this input is marked as required.

Returns:

  • (Boolean) 


95
96
97
 
# File 'app/components/primer/alpha/form_control.rb', line 95

def required?
  @required
end

#visually_hide_label? ⇒ Boolean

Whether or not to hide the label visually. The label will still be visible to screen readers.

Returns:

  • (Boolean) 


101
102
103
 
# File 'app/components/primer/alpha/form_control.rb', line 101

def visually_hide_label?
  @visually_hide_label
end

#with_input(&block) ⇒ Object 



89
90
91
 
# File 'app/components/primer/alpha/form_control.rb', line 89

def with_input(&block)
  @input_block = block
end