Module: StateGate::Engine::Stator

Included in:
StateGate::Engine
Defined in:
lib/state_gate/engine/stator.rb

Overview

Description

Provides state helper methods for StateGate::Engine.

Instance Method Summary collapse

Instance Method Details

#assert_valid_state!(value) ⇒ Symbol

Note:

Valid state names preceeded with force_ are also allowed.

.assert_valid_state!(:force_active)  #=> :force_active

Ensures the given value is a valid state name.

Examples:

.assert_valid_state!(:active)    #=> :active
.assert_valid_state!('PENDING')  #=> :pending
.assert_valid_state!(:dummy)     #=> ArgumentError

Parameters:

  • value (String, Symbol) —

    the state name.

Returns:

  • (Symbol) —

    the Symbol state name

Raises:

  • (ArgumentError) —

    if the value is not a valid state name.



105
106
107
108
109
110
 
# File 'lib/state_gate/engine/stator.rb', line 105

def assert_valid_state!(value)
  state_name                      = StateGate.symbolize(value)
  unforced_state                  = state_name.to_s.remove(/^force_/).to_sym
  _invalid_state_error(value) unless @states.keys.include?(unforced_state)
  state_name
end

#default(default_state = nil) ⇒ Object

The name for the default state for a new object. (String | required)

Examples:

default :state_name

Parameters:

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

    the state name to set as default



58
59
60
61
62
 
# File 'lib/state_gate/engine/stator.rb', line 58

def default(default_state = nil)
  _cerr(:default_type_err, kattr: true) unless default_state.is_a?(Symbol)
  _cerr(:default_repeat_err, kattr: true) if   @default
  @default = StateGate.symbolize(default_state)
end

#default_state ⇒ String

Returns the state_gate default state.

Examples:

.default_state   #=> :pending

Returns:

  • (String) —

    the state_gate default state



198
199
200
 
# File 'lib/state_gate/engine/stator.rb', line 198

def default_state
  @default
end

#human_state_for(state) ⇒ Object

Returns the human display name for a given state.

Examples:

.human_state_for(:pending)  #=> 'Panding Activation'
.human_state_for(:active)   #=> 'Active'

Parameters:

  • state (Symbol) —

    the state name



136
137
138
139
 
# File 'lib/state_gate/engine/stator.rb', line 136

def human_state_for(state)
  state_name = assert_valid_state!(state)
  @states[state_name][:human]
end

#human_states ⇒ Object

Returns an Array of the human display names for each defined state.

Examples:

human_states  #=> ['Pending Activation', 'Active', 'Suspended By Admin']


120
121
122
 
# File 'lib/state_gate/engine/stator.rb', line 120

def human_states
  @states.map { |_k, v| v[:human] }
end

#raw_states ⇒ Hash

Returns a hash of states and their transitions & human names.

Examples:

.raw_states  #=> { pending: { transitions_to: [:active],
                               human:          'Pending Activation'},
                    active:  { transitions_to: [:pending],
                               human:          'Active'}}

Returns:

  • (Hash) —

    a hash of states and their transitions & human names



185
186
187
 
# File 'lib/state_gate/engine/stator.rb', line 185

def raw_states
  @states
end

#state(name, opts = {}) ⇒ Object

Add a new state.

Parameters:

  • name (Symbol, String) —

    The name for the new state. It must be converatbel to a Symbol

    state :state_name
  • opts (Hash) (defaults to: {}) —

    configuration options for the given state

Options Hash (opts):

  • :transitions_to (Hash) —

    A list of other state that this state may change to. (Array | optional)

    state :state_name, transtions_to: [:state_1, :state_4, :state_5]
  • :human (Hash) —

    A display name for the state used in views, defaulting to state.titleized.

    state :state_name, transtions_to: [:state_1, :state_4, :state_5], human: "My State"



33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/state_gate/engine/stator.rb', line 33

def state(name, opts = {})
  name = StateGate.symbolize(name)
  _assert_valid_state_name(name)
  _assert_valid_opts(opts, name)

  # add the state
  @states[name] = _state_template.merge({ human: opts[:human] || name.to_s.titleize })

  # add the state transitions
  Array(opts[:transitions_to]).each do |transition|
    @states[name][:transitions_to] << StateGate.symbolize(transition)
  end
end

#states ⇒ Object

Returns an Array defined states.

Examples:

.states  #=> [:pending, :active, :suspended, :archived]


76
77
78
 
# File 'lib/state_gate/engine/stator.rb', line 76

def states
  @states.keys
end

#states_for_select(sorted = false) ⇒ Array[Array[Strings]]

Return an Array of states, with their human display names, ready for use in a form select.

Examples:

.states_for_select        #=> [['Pending Activation', 'pending'],
                                ['Active', 'active'],
                                ['Suspended by Admin', 'suspended']]

.states_for_select(true)  #=> [['Active', 'active'],
                                ['Pending Activation', 'pending'],
                                ['Suspended by Admin', 'suspended']]

Parameters:

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

    true is the states should be sorted by human name, defaults to false

Returns:

  • (Array[Array[Strings]]) —

    Array of state names with their human names



162
163
164
165
166
167
168
169
170
171
 
# File 'lib/state_gate/engine/stator.rb', line 162

def states_for_select(sorted = false)
  result = []
  if sorted
    @states.sort_by { |_k, v| v[:human] }
           .each { |state, opts| result << [opts[:human], state.to_s] }
  else
    @states.each { |state, opts| result << [opts[:human], state.to_s] }
  end
  result
end