webflow 0.0.1

data/lib/webflow/session_handler.rb

@@ -0,0 +1,315 @@
+#--
+# Copyright (c) 2007 The World in General
+#
+# Released under the Creative Commons Attribution-Share Alike 3.0 License.
+# Licence details available at : http://creativecommons.org/licenses/by-sa/3.0/
+#
+# Created by Luc Boudreau ( lucboudreau at gmail )
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+
+# Simply put, this module makes sure that the operations to the state
+# registry associated to a user are transparent to the business logic.
+#
+# Session and it's flow states are all stored inside a session variable
+# called WebFlow::SessionHandler.session_flow_data_prefix followed by
+# 32 random characters.
+#
+
+WebFlow::Base.class_eval do
+
+  private
+
+  # Prefix of the variables which will be created in the user session
+  # to store the flow data.
+  @@session_flow_data_prefix = 'flow_data-'
+  cattr_accessor :session_flow_data_prefix
+
+  # Prefix of the variables which will be created in the flow's user session
+  # to store the state data.
+  @@session_state_data_prefix = 'state_data-'
+  cattr_accessor :session_state_data_prefix
+
+  # Name of the variables which will be created in the flow's user session
+  # to store the user data.
+  @@session_user_data_name = 'user_data'
+  cattr_accessor :session_user_data_name
+
+  # Used to detect flow data keys in the session hash
+  Session_data_prefix_regex = /^#{session_flow_data_prefix}[0-9]{32}$/
+
+  # Name of the key in the flow hash stored in the session which tells when was
+  # this flow last executed
+  @@session_timestamp_placeholder = 'updated_at'
+  cattr_accessor :session_timestamp_placeholder
+
+  # Defines for how long a flow execution data is maintained in the session
+  # placeholder.
+  @@session_ttl = 1.hour
+  cattr_accessor :session_ttl
+
+  # Defines where to store the name of the last executed step
+  @@last_step_placeholder = 'last_step_name'
+  cattr_accessor :last_step_placeholder
+
+  # Cleans the flows data for flows which have not been executed since
+  # the value defined by Session_ttl and Session_timestamp_placeholder.
+  def cleanup
+
+    # Iterate over the real session keys to find flow placeholders
+    session.keys.each do |key|
+
+      # Check if the key is a flow placeholder
+      if key =~ Session_data_prefix_regex
+
+        # Delete it if the flow has expired
+        session.delete(key) if (session[key].fetch(session_timestamp_placeholder) < (Time.now - session_ttl))
+
+      end
+
+    end
+
+  end
+
+
+  # Saves the current flow state data and makes sure that everything will be available
+  # to restore the flow state later on.
+  #def serialize
+  #
+  #  # Update the flow timestamp
+  #  update_timestamp
+  #
+  #  # Copy the current state data
+  #  old_state = (state).deep_copy
+  #
+  #  # Generate a new flow id.
+  #  # With old flows, we use the first 8 characters of the last execution id
+  #  # but we generate 56 new ones which we append
+  #  #
+  #  # Fix for bug #10559 added. Collisions are prevented.
+  #  continue = true
+  #  while continue
+  #
+  #    # Generate a new state id to test
+  #    new_id = WebFlow::RandomGenerator.random_string(32)
+  #
+  #    # Test it
+  #    continue = current_flow_data.has_key?(new_id)
+  #
+  #  end
+  #
+  #  # We can update the flow id
+  #  @flow_id = @flow_id[0, 9] + new_id
+  #
+  #  # Initialize the flow session storage for this execution (state)
+  #  init_state_session_space
+  #
+  #  # Copy the shadow session state into the new state to freeze it
+  #  state = old_state.deep_copy
+  #
+  #  # Return nil
+  #  nil
+  #
+  #end
+
+
+  #
+  # Cleans all data concerning the flow from the session.
+  #
+  def terminate
+
+    # Destroy the flow placeholder in the session
+    session.delete(flow_session_name)
+
+    nil
+
+  end
+
+
+  # Does everything needed to store data concerning a new flow execution
+  def start_new_flow_session_storage
+
+    # With new flows, we define a completely new 32 characters id
+    @flow_id = WebFlow::RandomGenerator.random_string(32)
+
+    # Initialize the flow session storage for the flow itself, since it will
+    # then contain all the states
+    init_flow_session_space
+
+    # Initialize the flow session state storage for this execution
+    init_state_session_space
+
+    # Initialize the flow session user storage for this execution
+    init_user_session_space
+
+  end
+
+
+  # Updates the timestamp for the current flow. Is to be called on each session
+  # modification.
+  def update_timestamp
+
+    # Update the timestamp for the current flow
+    session[flow_session_name].store session_timestamp_placeholder, Time.now
+
+  end
+
+
+  # Adds the last step name to the current flow data so we can interpret the
+  # returned event correctly once the user submits data back.
+  def persist_last_step_name(state_name)
+
+    # Store the last step name in the correct placeholder
+    current_flow_data.fetch(state_session_name).store(last_step_placeholder, state_name.to_s)
+
+    # Return nil
+    nil
+
+  end
+
+
+  # Adds the last step name to the current flow data so we can interpret the
+  # returned event correctly once the user submits data back.
+  def fetch_last_step_name
+
+    # Fetch the last step name from the correct placeholder
+    current_flow_data.fetch(state_session_name).fetch(last_step_placeholder)
+
+  end
+
+
+  # Validates that the given flow key corresponds to a stored flow data
+  def validate_flow_existence
+
+    !current_flow_data.nil? && !state.nil?
+
+  end
+
+
+  # Initializes the session variables needed to save the flow data.
+  def init_flow_session_space
+
+    # The placeholder for the flow will be named...
+    flow_placeholder = flow_session_name
+
+    # Create a new placeholder for this flow data in the real session space
+    session[flow_placeholder] = HashWithIndifferentAccess.new
+
+    # Timestamp the creation time
+    update_timestamp
+
+    # Return nil
+    nil
+
+  end
+
+
+  # Initializes the session variables needed to save the state data.
+  def init_state_session_space
+
+    # Create a new placeholder for this state data in the real session space
+    # reserved for this flow data
+    current_flow_data.store state_session_name, HashWithIndifferentAccess.new
+
+    # Return nil
+    nil
+
+  end
+
+
+  # Initializes the session variables needed to save the user data.
+  def init_user_session_space
+
+    # Create a new placeholder for this user data in the real session space
+    # reserved for this flow data
+    current_flow_data.store session_user_data_name, HashWithIndifferentAccess.new
+
+    # Return nil
+    nil
+
+  end
+
+
+  # Returns the name of the variable used in the real session data hash
+  # to store this flow data
+  def flow_session_name
+    (session_flow_data_prefix + @flow_id).to_s
+  end
+
+
+  # Returns the name of the variable used in the flow session data hash
+  # to store this state data
+  def state_session_name
+    (session_state_data_prefix + @flow_id).to_s
+  end
+
+
+  # Returns the current flow data hash from within the
+  # user session.
+  def current_flow_data
+    session[flow_session_name]
+  end
+
+
+  # Returns the current flow user data hash from within the user session.
+  #
+  # @returns current flow user session hash
+  #
+  def current_flow_user_data
+    current_flow_data.fetch session_user_data_name
+  end
+
+
+  # Saves or updates data to the current flow session data hash.
+  #
+  # @params values hash containing values to be added to the flow user session
+  # @params options hash containing options
+  #
+  # @returns nil
+  #
+  def store_flow_data(values, options = {})
+    update = options[:update] || true
+
+    current_flow_user_data.merge!(values) { |key, val1, val2| update ? val2 : val1 }
+
+    update_timestamp
+
+    nil
+  end
+
+
+  public
+
+  # Returns the current flow user data hash from within the user session.
+  #
+  # @returns current flow user session hash
+  #
+  def current_flow_user_data
+    current_flow_data.fetch session_user_data_name
+  end
+
+end
+
+
+# Used to add a deep copy mechanism to objects
+Object.class_eval do
+
+  # Performs a deep copy of an object and returns a copy of the source and all it's sub objects
+  # as copies. Useful for example when a hash contains objects and you want a copy of the Hash
+  # and copies of the objects it contains and not the objects themselves
+  def deep_copy
+    Marshal.load(Marshal.dump(self))
+  end
+
+end

data/lib/webflow/state.rb

@@ -0,0 +1,70 @@
+#--
+# Copyright (c) 2007 The World in General
+#
+# Released under the Creative Commons Attribution-Share Alike 3.0 License.
+# Licence details available at : http://creativecommons.org/licenses/by-sa/3.0/
+#
+# Created by Luc Boudreau ( lucboudreau at gmail )
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+
+  
+  
+  # The State module is simply a method inclusion mechanism which allows
+  # the user to store data relevant to a flow state. It is used exactly like
+  # the 'session' attribute of the ActionController::Base. See the WebFlow
+  # wiki for more details.
+  
+WebFlow::Base.class_eval do
+
+
+  # TODO Send the state method to the ActionViews
+
+  protected
+
+    
+    # Returns the state data hash
+    def state
+      
+      session[ flow_session_name ].fetch( state_session_name )
+      
+    end
+    
+    # Changes the state hash for another one
+    def state=(hash)
+      session[ flow_session_name ].store( state_session_name, hash )
+      state
+    end
+    
+    # Does the same as state(k,v)
+    #def []=(k, v)
+    #  return session[ flow_session_name ].fetch( state_session_name ).store( k.to_s, v )
+    #end
+    
+    
+    # Does the same as state(k)
+    #def [](k)
+      
+    #  return session[ flow_session_name ].fetch( state_session_name ).fetch( k )
+    #  
+    #end
+    
+    
+    # Adds ActionView helper methods
+    def self.included(base)
+      base.send :helper_method, :state
+    end
+end
+  
+

data/lib/webflow/version.rb

@@ -0,0 +1,3 @@
+module WebFlow
+  VERSION = "0.0.1"
+end

data/lib/webflow/view_step.rb

@@ -0,0 +1,238 @@
+#--
+# Copyright (c) 2007 The World in General
+#
+# Released under the Creative Commons Attribution-Share Alike 3.0 License.
+# Licence details available at : http://creativecommons.org/licenses/by-sa/3.0/
+#
+# Created by Luc Boudreau ( lucboudreau at gmail )
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+#require 'flow_step'
+#require 'base'
+#require 'event'
+
+module WebFlow
+
+  # This class allows the controllers to create view steps. It adds the
+  # view_step method to the WebFlow::Base class evaluation so we can
+  # define view steps from the controllers.
+  # 
+  # == Simple usage
+  # 
+  #  view_step :view_name do
+  #    on :success => :another_step
+  #    on :back => :yet_another_step
+  #  end
+  # 
+  # The view name will be stored in the @view_name instance variable
+  # until it is needed.
+  # 
+  # If no method corresponding to @view_name is defined inside the 
+  # calling controller upon execution, the ViewStep tries to render
+  # a file with the same name as the @view_step value. Therefore,
+  # it is not mandatory to define view_step methods in the flow controller.
+  #
+  # The view_step instruction can also be used to batch define view steps.
+  # Just pass a comma separated list of view names. Note that the mappings
+  # defined in the following block will be applied to all the view steps
+  # in the given list.
+  #
+  #  view_step :view_name, :another_view_step
+  # 
+  # == Advanced usage
+  #
+  # You can define how to render the view steps directly in the mapping, 
+  # instead of doing it in the action itself. This gives a more clean code
+  # and separates the rendering concern from the business logic. The to_render
+  # instruction does this job. Here's a simple usage.
+  #
+  #  view_step :view_name do
+  #  
+  #    (...)
+  #  
+  #    to_render :my_event do
+  #      render 'template/path'
+  #    end
+  #  end
+  #
+  # The to_render instruction tells the view step that upon the returning of the
+  # my_event event from the step implementation, we must render the 'template/path' 
+  # file. As a matter of fact, all the to_render does is to call the given block
+  # right after the step definition execution. One could use the to_render mechanism
+  # as he wishes and therefore perform actions other than rendering.
+  #
+  # The to_render can also take many event names as arguments simultaneously,
+  # as shown here :
+  #
+  #  view_step :view_name do
+  #  
+  #    (...)
+  #  
+  #    to_render :my_event, :some_other_event, :yet_more_events do
+  #      render 'template/path'
+  #    end
+  #  end
+  #
+  # == Inherited instructions
+  #
+  # The ViewStep class inherits all the standard step methods defined in FlowStep class.
+  #
+  #
+  class ViewStep < WebFlow::FlowStep
+  
+    # Initializes the instance
+    def initialize( m_view_name )
+      
+      # Holds the view name to render once the execution is complete
+      @view_name = m_view_name
+      
+      # Tells the framework that no method definition is required for
+      # this step type
+      @definition_required = false
+  
+    end
+
+  
+    # This method is required by the WebFlow::Base and will be called
+    # once it relays the execution to this step instance
+    def execute(*args)
+    
+      # Verify if the controller answers to the @view_name value
+      if args[0].respond_to? lookup_method_to_call(@view_name)
+      
+        # The controller defines a method with the same name as @view_name.
+        # Kewl! A 'someone else problem' !!!
+        
+        # Launch execution
+        result = args[0].send( lookup_method_to_call(@view_name) )
+          
+      else
+      
+        # Do we have to do everything here? lazy user...
+      
+        # Render something but only if the user hasn't
+        # defined a custom render block.
+        args[0].send :render, :action => lookup_method_to_call(@view_name) unless renders.has_key?('render')
+        
+        # Return the :render event
+        result = WebFlow::Event.new(:render)
+      
+      end
+      
+      # Verify if we have to override the render result.
+      # Execute if necessary.
+      # Also validate that the return type is an event, or let go and it will
+      # crash as soon as execution completes anyways...
+      if result.kind_of?(WebFlow::Event) && renders.has_key?(result.name)
+      
+        # Execute the render block
+        args[0].instance_eval( &renders.fetch( result.name ) )
+        
+      end
+        
+      result
+         
+    end
+
+    
+    # Used to specify the render action to be taken by the step.
+    # The render result defined here overrides the one defined in the step
+    # definition.
+    # Use it as :
+    #
+    #  class Controller < WebFlow::Base
+    #  
+    #    def initialize
+    #  
+    #      to_render [:some_event_name, :some_other_event_name] do
+    #        render(:action => :whatever )
+    #      end
+    #  
+    #    end
+    #  
+    #  end
+    #def to_render(*events, &block)
+    #
+    #  # Make sure we have a block as a parameter
+    #  raise(WebFlow::WebFlowError.new, "The renders instruction takes a block as a parameter. Use the 'do' format. See API.") unless block_given?
+    #
+    #  # Iterate over the events to map
+    #  events.each do |name|
+    #
+    #    # Associate each event name with the received block
+    #    renders.store name.to_s, block
+    #
+    #  end
+    #
+    #end
+
+
+    def on_render(&block)
+
+      # Make sure we have a block as a parameter
+      raise(WebFlow::WebFlowError.new, "The renders instruction takes a block as a parameter. Use the 'do' format. See API.") unless block_given?
+
+      # Associate render event with the received block
+      renders.store "render", block
+
+    end
+
+    private
+    
+      # Returns the mapped rendering overrides hash.
+      def renders
+          
+        @_renders ||= {}
+            
+      end
+
+  end
+
+
+end
+
+# Let's create the view_step definition inside the WebFlow::Base
+# controller class
+WebFlow::Base.class_eval do
+
+protected
+  
+  # Called to define a step into a flow. Example of usage :
+  # 
+  #  view_step :view_name do
+  #    on :success => :another_step
+  #    on :back => :yet_another_step
+  #  end
+  # 
+  # See the ViewStep class documentation for more options.
+  #
+  def view_step(*view_name, &block)
+  
+    # Instantiate a ViewStep object if symbol or string received
+    view_name.each do |name|
+      
+      step = WebFlow::ViewStep.new(name.to_s)
+      
+      # Register this step in the flow repository
+      register name.to_s, step
+      
+      # Execute the config block
+      step.instance_eval(&block) if block_given?
+      
+    end
+    
+  end
+  
+
+end