Class: Primer::Alpha::ToggleSwitch

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

Overview

The ToggleSwitch component is a button that toggles between two boolean states. It is meant to be used for settings that should cause an immediate update. If configured with a “src” attribute, the component will make a POST request containing data of the form “value: 0 | 1”.

Constant Summary collapse

SIZE_DEFAULT = 
:medium
SIZE_MAPPINGS = 
{
  SIZE_DEFAULT => nil,
  :small => "ToggleSwitch--small"
}.freeze
SIZE_OPTIONS = 
SIZE_MAPPINGS.keys.freeze
STATUS_LABEL_POSITION_DEFAULT = 
:start
STATUS_LABEL_POSITION_MAPPINGS = 
{
  STATUS_LABEL_POSITION_DEFAULT => nil,
  :end => "ToggleSwitch--statusAtEnd"
}.freeze
STATUS_LABEL_POSITION_OPTIONS = 
STATUS_LABEL_POSITION_MAPPINGS.keys.freeze

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(src: nil, csrf_token: nil, checked: false, enabled: true, size: SIZE_DEFAULT, status_label_position: STATUS_LABEL_POSITION_DEFAULT, turbo: false, autofocus: nil, on_label: nil, off_label: nil, button_type: nil, **system_arguments) ⇒ ToggleSwitch

Returns a new instance of ToggleSwitch.

Parameters:

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

    The URL to POST to when the toggle switch is toggled. If ‘nil`, the toggle switch will not make any requests.

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

    A CSRF token that will be sent to the server as “authenticity_token” when the toggle switch is toggled. Unused if ‘src` is `nil`.

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

    Whether the toggle switch is on or off.

  • enabled (Boolean) (defaults to: true) —

    Whether or not the toggle switch responds to user input.

  • size (Symbol) (defaults to: SIZE_DEFAULT) —

    What size toggle switch to render. <%= one_of(Primer::Alpha::ToggleSwitch::SIZE_OPTIONS) %>

  • status_label_position (Symbol) (defaults to: STATUS_LABEL_POSITION_DEFAULT) —

    Which side of the toggle switch to render the status label. <%= one_of(Primer::Alpha::ToggleSwitch::STATUS_LABEL_POSITION_OPTIONS) %>

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

    Whether or not to request a turbo stream and render the response as such.

  • autofocus (Boolean) (defaults to: nil) —

    Whether switch should be autofocused when rendered.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>

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

    Custom label to show when the switch is ON. Defaults to On. Only customize this label if it makes the toggle’s state more meaningful in its specific context. For example, for a “Show images” setting, you might use “Hide” when the switch is ON.

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

    Custom label to show when the switch is OFF. Defaults to (“Off”). Only customize this label if it makes the toggle’s state more meaningful in its specific context. For example, for a “Show images” setting, you might use “Show” when the switch is OFF.

  • button_type (Symbol) (defaults to: nil) —

    The type attribute for the underlying button element. If ‘nil`, the button will not have a type attribute, which means it will default to “submit” if it’s inside a form and “button” otherwise.



44
45
46
47
48
49
50
51
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
83
84
85
86
87
88
89
90
91
92
 
# File 'app/components/primer/alpha/toggle_switch.rb', line 44

def initialize(
  src: nil,
  csrf_token: nil,
  checked: false,
  enabled: true,
  size: SIZE_DEFAULT,
  status_label_position: STATUS_LABEL_POSITION_DEFAULT,
  turbo: false,
  autofocus: nil,
  on_label: nil,
  off_label: nil,
  button_type: nil,
  **system_arguments
)
  @src = src
  @csrf_token = csrf_token
  @checked = checked
  @enabled = enabled
  @turbo = turbo
  @system_arguments = system_arguments

  @size = fetch_or_fallback(SIZE_OPTIONS, size, SIZE_DEFAULT)
  @status_label_position = fetch_or_fallback(
    STATUS_LABEL_POSITION_OPTIONS, status_label_position, STATUS_LABEL_POSITION_DEFAULT
  )

  @system_arguments[:classes] = class_names(
    @system_arguments.delete(:classes),
    "ToggleSwitch",
    on? ? "ToggleSwitch--checked" : nil,
    enabled? ? nil : "ToggleSwitch--disabled",
    STATUS_LABEL_POSITION_MAPPINGS[@status_label_position],
    SIZE_MAPPINGS[@size]
  )

  @button_arguments = {
    type: button_type,
    aria: merge_aria(
      @system_arguments,
      aria: { pressed: on? }
    )
  }
  @button_arguments[:autofocus] = true if autofocus

  @system_arguments[:src] = @src if @src

  @on_label  = on_label  || "On"
  @off_label = off_label || "Off"
end

Instance Method Details

#disabled? ⇒ Boolean

Returns:

  • (Boolean) 


102
103
104
 
# File 'app/components/primer/alpha/toggle_switch.rb', line 102

def disabled?
  !enabled?
end

#enabled? ⇒ Boolean

Returns:

  • (Boolean) 


98
99
100
 
# File 'app/components/primer/alpha/toggle_switch.rb', line 98

def enabled?
  @enabled
end

#on? ⇒ Boolean

Returns:

  • (Boolean) 


94
95
96
 
# File 'app/components/primer/alpha/toggle_switch.rb', line 94

def on?
  @checked
end