====== The Concepts : Flow Step ======

The Flow Step superclass makes basic step instructions available to any ActionFlow step type. Any step types have to inherit from this superclass.

===== Mapping instructions =====

The mapping instructions common to every step type are the following.

==== on ====


The ''on'' instruction is used to map a returned event name to a subsequent step. Here's a simple example of it's usage.

<code ruby>
 action_step :example_step do
  
   (...)
  
   on :success => :next_step_name
  
   on :back => :previous_step_name
  
 end
</code>

In the previous example, the example step will route the flow to the step named ''next_step_name'' if the step definition returns an event which is named ''success''. If the step definition returns a ''back'' event, the flow will then call the ''previous_step_name'' step.

==== upon ====


The ''upon'' instruction is used to map a raised error class to a subsequent step. Here's a simple example of it's usage.

<code ruby>
 action_step :example_step do
  
   (...)
  
   upon :StandardError => :next_step_name
  
 end
</code>

In the previous example, the example step will route the flow to the step named ''next_step_name'' if the step definition raises an error which is a kind of ''StandardError''. If the upon instruction is used more than once, the first declaration has priority. Also note that the ''kind_of?'' method is used to validate the correspondance,
so subclasses of mapped error classes will be included as well.


==== method ====

The ''method'' instruction is meant to override the default step definition name. By default, the definition of a given step has to be declared with the same name as the step name in the mapping. If a step is named ''my_jolly_step'', the controller has to implement the step logic with a ''def'' block which is named ''my_jolly_step''.

The ''method'' instruction will tell the ActionFlow framework to look for a definition of the given value instead of looking for the same name. This allows to reuse business logic and decouple the mapping from the
step implementation. One could then do something like :

<code ruby>
 class MyController < ActionFlow::Base
 
   def initialize
    
     (...)
   
     action_step :step_1 do
       method :shared_implementation
       (...)
     end
   
     action_step :step_2 do
       method :shared_implementation
       (...)
     end
   end
   
   def shared_implementation
     (...)
   end
  
 end
</code>

===== Developper infos =====


This class defines a basic skeletton for different step types used by the ActionFlow framework. All new step types must inherit of this superclass to be usable in the ActionFlow controller. It is also the responsability of any subclass to add it's declaration method in the ActionFlow::Base class. See view_step.rb for an example.
 
Also, subclasses can change the ''@definition_required'' instance variable value to tell the ActionFlow framework that it can handle the execution without the user controller defining explicitely a step implementation.
See view_step.rb(initialize) for an example.

Event outcomes are defined in the ''@outcomes'' instance variable while the error handlers are defined in the ''@handlers'' instance variable. Those variables are protected, so any subclasses of FlowStep can access
them and hack the mechanism if required.