apotomo 0.1.1

data/lib/apotomo/event.rb

@@ -0,0 +1,9 @@
+module Apotomo
+  # Events are created by Apotomo in #fire. They bubble up from their source to root and trigger
+  # event handlers. 
+  class Event < Onfire::Event
+    def _dump(depth)
+      raise "You're trying to serialize an instance of Apotomo::Event. Don't do that."
+    end
+  end
+end

data/lib/apotomo/event_handler.rb

@@ -0,0 +1,23 @@
+module Apotomo
+  # EventHandlers are "callbacks", not knowing why they exist, but what to do.
+  class EventHandler
+    
+    def process_event(event)
+      # do something, and return content.
+      nil
+    end
+    
+    def ==(other)
+      self.to_s == other.to_s
+    end
+    
+    # Invoked by Onfire.
+    def call(event)
+      event.source.root.page_updates << process_event(event)
+    end
+    
+  end
+end
+
+require 'apotomo/invoke_event_handler'
+require 'apotomo/proc_event_handler'

data/lib/apotomo/event_methods.rb

@@ -0,0 +1,102 @@
+require 'apotomo/event_handler'
+
+module Apotomo
+  # Introduces event-processing functions into the StatefulWidget.
+  
+  module EventMethods
+    attr_writer :page_updates
+    # Replacement for the EventProcessor singleton queue.
+    def page_updates
+      @page_updates ||= []
+    end
+    
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.initialize_hooks << :add_class_event_handlers
+    end
+    
+    def add_class_event_handlers(*)
+      self.class.responds_to_event_options.each { |options| respond_to_event(*options) }
+    end
+    
+    module ClassMethods
+      def responds_to_event(*options)
+        responds_to_event_options << options
+      end
+      alias_method :respond_to_event, :responds_to_event
+      
+      def responds_to_event_options
+        @responds_to_event_options ||= []
+      end
+    end
+    # Instructs the widget to look out for <tt>type</tt> Events that are passing by while bubbling.
+    # If an appropriate event is encountered the widget will send the targeted widget (or itself) to another
+    # state, which implies an update of the invoked widget.
+    #
+    # You may configure the event handler with the following <tt>options</tt>:
+    #  :with  => (required) the state to invoke on the target widget
+    #  :on    => (optional) the targeted widget's id, defaults to <tt>self.name</tt>
+    #  :from  => (optional) the source id of the widget that triggered the event, defaults to any widget
+    #
+    # Example:
+    #   
+    #   trap = cell(:input_field, :smell_like_cheese, 'mouse_trap')
+    #   trap.respond_to_event :mouseOver, :with => :catch_mouse
+    #
+    # This would instruct <tt>trap</tt> to catch a <tt>:mouseOver</tt> event from any widget (including itself) and
+    # to invoke the state <tt>:catch_mouse</tt> on itself as trigger.
+    #
+    #   
+    #   hunter = cell(:form, :hunt_for_mice, 'my_form')
+    #     hunter << cell(:input_field, :smell_like_cheese,  'mouse_trap')
+    #     hunter << cell(:text_area,   :stick_like_honey,   'bear_trap')
+    #   hunter.respond_to_event :captured, :from => 'mouse_trap', :with => :refill_cheese, :on => 'mouse_trap'
+    #
+    # As both the bear- and the mouse trap can trigger a <tt>:captured</tt> event the later <tt>respond_to_event</tt>
+    # would invoke <tt>:refill_cheese</tt> on the <tt>mouse_trap</tt> widget as soon as this and only this widget fired.
+    # It is important to understand the <tt>:from</tt> parameter as it filters the event source - it wouldn't make
+    # sense to refill the mouse trap if the bear trap snapped, would it?
+    
+    def respond_to_event(type, options)
+      options[:once] = true if options[:once].nil?
+      
+      handler_opts              = {}
+      handler_opts[:widget_id]  = options[:on] || self.name
+      handler_opts[:state]      = options[:with]
+      
+      handler = InvokeEventHandler.new(handler_opts)
+      
+      return if options[:once] and event_table.all_handlers_for(type, options[:from]).include?(handler)
+      
+      on(type, :do => handler, :from => options[:from])
+    end
+    
+    def trigger(*args)
+      fire(*args)
+    end
+    
+    # Invokes <tt>state</tt> on the widget <em>and</end> updates itself on the page. This should
+    # never be called from outside but in setters when some internal value changed and must be
+    # displayed instantly.
+    # 
+    # Implements the following pattern (TODO: remove example as soon as invoke! proofed):
+    # 
+    #   def title=(str)
+    #     @title = str
+    #     peek(:update, self.name, :display, self.name)
+    #     trigger(:update)
+    #   end
+    def invoke!(state)
+      ### TODO: encapsulate in PageUpdateQueue:
+      Apotomo::EventProcessor.instance.processed_handlers << [name, invoke(:state)]
+    end
+    
+    
+    
+    protected
+    # Get all handlers from self for the passed event (overriding Onfire#local_event_handlers).
+    def local_event_handlers(event)
+      event_table.all_handlers_for(event.type, event.source.name) # we key with widget_id.
+    end
+  end
+end

data/lib/apotomo/invoke_event_handler.rb

@@ -0,0 +1,24 @@
+module Apotomo
+  class InvokeEventHandler < EventHandler
+    attr_accessor :widget_id, :state
+    
+    def initialize(opts={})
+      @widget_id  = opts.delete(:widget_id)
+      @state      = opts.delete(:state)
+    end
+    
+    def process_event(event)
+      target = event.source.root.find_by_path(widget_id) ### DISCUSS: widget_id or widget_selector?
+      
+      #::Rails.logger.debug "EventHandler: invoking #{target.name}##{state}"
+      ### DISCUSS: let target access event?
+      ###   pass additional opts to #invoke?
+      ### DISCUSS: pass block here?
+      target.opts[:event] = event
+      
+      target.invoke(state)
+    end
+    
+    def to_s; "InvokeEventHandler:#{widget_id}##{state}"; end
+  end
+end

data/lib/apotomo/javascript_generator.rb

@@ -0,0 +1,57 @@
+module Apotomo
+  class JavascriptGenerator
+    def initialize(framework)
+      raise "No JS framework specified" if framework.blank?
+      extend "apotomo/javascript_generator/#{framework}".camelize.constantize
+    end
+    
+    def <<(javascript)
+      "#{javascript}"
+    end
+    
+    # Copied from ActionView::Helpers::JavascriptHelper.
+    JS_ESCAPE_MAP = {
+      '\\'    => '\\\\',
+      '</'    => '<\/',
+      "\r\n"  => '\n',
+      "\n"    => '\n',
+      "\r"    => '\n',
+      '"'     => '\\"',
+      "'"     => "\\'" }
+
+    # Escape carrier returns and single and double quotes for JavaScript segments.
+    def self.escape(javascript)
+      return javascript.gsub(/(\\|<\/|\r\n|[\n\r"'])/) { JS_ESCAPE_MAP[$1] } if javascript
+      
+      ''
+    end
+    
+    def escape(javascript)
+      self.class.escape(javascript)
+    end
+    
+    module Prototype
+      def prototype;            end
+      def element(id);          "$(\"#{id}\")"; end
+      def xhr(url);             "new Ajax.Request(\"#{url}\")"; end
+      def update(id, markup);   element(id) + '.update("'+escape(markup)+'")'; end
+      def replace(id, markup);  element(id) + '.replace("'+escape(markup)+'")'; end
+    end
+    
+    module Right
+      def right;                end
+      def element(id);          "$(\"#{id}\")"; end
+      def xhr(url);             "new Xhr(\"#{url}\", {evalScripts:true}).send()"; end
+      def update(id, markup);   element(id) + '.update("'+escape(markup)+'")'; end
+      def replace(id, markup);  element(id) + '.replace("'+escape(markup)+'")'; end
+    end
+    
+    module Jquery
+      def jquery;               end
+      def element(id);          "$(\"##{id}\")"; end
+      def xhr(url);             "$.ajax({url: \"#{url}\"})"; end
+      def update(id, markup);   element(id) + '.html("'+escape(markup)+'")'; end
+      def replace(id, markup);  element(id) + '.replaceWith("'+escape(markup)+'")'; end
+    end
+  end
+end

data/lib/apotomo/persistence.rb

@@ -0,0 +1,139 @@
+module Apotomo
+  # Methods needed to serialize the widget tree and back.
+  module Persistence
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    
+    # For Ruby 1.8/1.9 compatibility.
+    def symbolized_instance_variables
+      instance_variables.map { |ivar| ivar.to_sym }
+    end
+    
+    def freeze_ivars_to(storage)
+      frozen = {}
+      (symbolized_instance_variables - unfreezable_ivars).each do |ivar|
+        frozen[ivar] = instance_variable_get(ivar)
+      end
+      storage[path] = frozen
+    end
+    
+    ### FIXME: rewrite so that root might be stateless as well.
+    def freeze_data_to(storage)
+      freeze_ivars_to(storage)# if self.kind_of?(StatefulWidget)
+      children.each { |child| child.freeze_data_to(storage)  if child.kind_of?(StatefulWidget) }
+    end
+    
+    def freeze_to(storage)
+      storage[:apotomo_root]          = self          # save structure.
+      storage[:apotomo_widget_ivars]  = {}
+      freeze_data_to(storage[:apotomo_widget_ivars])  # save ivars.
+    end
+    
+    def thaw_ivars_from(storage)
+      storage.fetch(path, {}).each do |k, v|
+        instance_variable_set(k, v)
+      end
+    end
+    
+    def thaw_data_from(storage)
+      thaw_ivars_from(storage)
+      children.each { |child| child.thaw_data_from(storage) }
+    end
+    
+    
+    # Serializes the widget node structure (not children, not content).
+    def dump_node
+      field_sep = self.class.field_sep
+      "#{@name}#{field_sep}#{self.class}#{field_sep}#{root? ? @name : parent.name}"
+    end
+    
+    # Serializes the tree structure.
+    def _dump(depth)
+      inject("") { |str, node| str << node.dump_node << self.class.node_sep }
+    end
+    
+    module ClassMethods
+      def field_sep;  '|';  end
+      def node_sep;   "\n"; end
+      
+      # Creates an empty widget instance from <tt>line</tt>.
+      def load_node(line)
+        name, klass, parent = line.split(field_sep)
+        [klass.constantize.new(name, nil), parent]
+      end
+      
+      def _load(str)
+        nodes = {}
+        root  = nil
+        str.split(node_sep).each do |line|
+          node, parent = load_node(line)
+          nodes[node.name] = node
+          
+          if node.name == parent # we're at the root node.
+            root = node and next
+          end
+          
+          nodes[parent].add(node)
+        end
+        root
+      end
+      
+      def freeze_for(storage, root)
+        storage[:apotomo_stateful_branches] = []
+        storage[:apotomo_widget_ivars]      = {}
+        
+        stateful_branches_for(root).each do |branch|
+          branch.freeze_data_to(storage[:apotomo_widget_ivars])  # save ivars.
+          storage[:apotomo_stateful_branches] << [branch, branch.parent.name]
+          branch.root!  # disconnect from tree.
+        end
+      end
+      
+      def thaw_for(storage, root)
+        branches = storage.delete(:apotomo_stateful_branches) || []
+        branches.each do |config|
+          branch = config.first
+          parent = root.find_widget(config.last) or raise "Couldn't find parent `#{config.last}` for `#{branch.name}`"
+          
+          parent << branch
+          branch.thaw_data_from(storage.delete(:apotomo_widget_ivars) || {})
+        end
+        
+        root
+      end
+  
+      def thaw_from(storage)
+        root = storage[:apotomo_root]
+        root.thaw_data_from(storage.fetch(:apotomo_widget_ivars, {}))
+        root
+      end
+      
+      def frozen_widget_in?(storage)
+        branches = storage[:apotomo_stateful_branches]
+        branches.present? and branches.first.first.kind_of? Apotomo::StatefulWidget
+      end
+      
+      def flush_storage(storage)
+        storage[:apotomo_stateful_branches] = nil
+        storage[:apotomo_widget_ivars]      = nil
+      end
+      
+      # Find the first stateful widgets on each branch from +root+.
+      def stateful_branches_for(root)
+        to_traverse     = [root]
+        stateful_roots  = []
+        
+        while node = to_traverse.shift
+          if node.kind_of?(StatefulWidget)
+            stateful_roots << node and next
+          end
+          to_traverse += node.children
+        end
+        
+        stateful_roots
+      end
+      
+    end
+  end
+end

data/lib/apotomo/proc_event_handler.rb

@@ -0,0 +1,18 @@
+module Apotomo
+  class ProcEventHandler < EventHandler
+    attr_accessor :proc
+    
+    def initialize(opts={})
+      @proc = opts.delete(:proc)
+    end
+    
+    def process_event(event)
+      Rails.logger.debug "ProcEventHandler: calling #{@proc}"
+      #@proc.call(event)
+      event.source.controller.send(@proc, event)
+      nil ### DISCUSS: needed so that controller doesn't evaluate the "content".
+    end
+    
+    def to_s; "ProcEventHandler:#{proc}"; end
+  end
+end

data/lib/apotomo/rails/controller_methods.rb

@@ -0,0 +1,161 @@
+require 'apotomo/request_processor'
+require 'apotomo/rails/view_methods'
+
+  module Apotomo
+    module Rails
+      module ControllerMethods
+        include WidgetShortcuts
+        
+        def self.included(base) #:nodoc:
+          base.class_eval do
+            extend WidgetShortcuts
+            extend ClassMethods      
+            
+            class_inheritable_array :uses_widgets_blocks
+            self.uses_widgets_blocks = []
+            
+            helper ::Apotomo::Rails::ViewMethods
+            
+            after_filter :apotomo_freeze
+          end
+        end
+        
+        module ClassMethods
+          def uses_widgets(&block)
+            uses_widgets_blocks << block
+          end
+          
+          alias_method :has_widgets, :uses_widgets
+        end
+        
+        def bound_use_widgets_blocks
+          session[:bound_use_widgets_blocks] ||= ProcHash.new
+        end
+        
+        def flush_bound_use_widgets_blocks
+          session[:bound_use_widgets_blocks] = nil
+        end
+        
+        def apotomo_request_processor
+          return @apotomo_request_processor if @apotomo_request_processor
+          
+          # happens once per request:
+          ### DISCUSS: policy in production?
+          options = { :flush_widgets  => params[:flush_widgets],
+                      :js_framework   => Apotomo.js_framework || :prototype,
+          }  ### TODO: process rails options (flush_tree, version)
+          
+          @apotomo_request_processor = Apotomo::RequestProcessor.new(session, options, self.class.uses_widgets_blocks)
+          
+          flush_bound_use_widgets_blocks if @apotomo_request_processor.widgets_flushed?
+          
+          
+          @apotomo_request_processor
+        end
+        
+        def apotomo_root
+          apotomo_request_processor.root
+        end
+        
+        # Yields the root widget for manipulating the widget tree in a controller action.
+        # Note that the passed block is executed once per session and not in every request.
+        #
+        # Example:
+        #   def login
+        #     use_widgets do |root|
+        #       root << cell(:login, :form, 'login_box')
+        #     end
+        #
+        #     @box = render_widget 'login_box'
+        #   end
+        def use_widgets(&block)
+          root = apotomo_root ### DISCUSS: let RequestProcessor initialize so we get flushed, eventually. maybe add a :before filter for that? or move #use_widgets to RequestProcessor?
+          
+          return if bound_use_widgets_blocks.include?(block)
+          
+          yield root
+          
+          bound_use_widgets_blocks << block  # remember the proc.
+        end
+        
+        
+        def render_widget(widget, options={}, &block)
+          apotomo_request_processor.render_widget_for(widget, options, self, &block)
+        end
+        
+        def apotomo_freeze
+          apotomo_request_processor.freeze!
+        end
+      
+        def render_event_response
+          page_updates = apotomo_request_processor.process_for({:type => params[:type], :source => params[:source]}, self)
+          
+          return render_iframe_updates(page_updates) if params[:apotomo_iframe]
+          
+          render :text => apotomo_request_processor.render_page_updates(page_updates), :content_type => Mime::JS
+        end
+        
+        # Returns the url to trigger a +type+ event from +:source+, which is a non-optional parameter.
+        # Additional +options+ will be appended to the query string.
+        #
+        # Note that this method will use the framework's internal routing if available (e.g. #url_for in Rails).
+        #
+        # Example:
+        #   url_for_event(:paginate, :source => 'mouse', :page => 2)
+        #   #=> http://apotomo.de/mouse/process_event_request?type=paginate&source=mouse&page=2
+        def url_for_event(type, options)
+          options.reverse_merge!(:type => type)
+          
+          apotomo_event_path(apotomo_request_processor.address_for(options))
+        end
+        
+        protected
+        
+        
+        # Renders the page updates through an iframe. Copied from responds_to_parent,
+        # see http://github.com/markcatley/responds_to_parent .
+        def render_iframe_updates(page_updates)
+          script = apotomo_request_processor.render_page_updates(page_updates)
+          escaped_script = Apotomo::JavascriptGenerator.escape(script)
+          
+          render :text => "<html><body><script type='text/javascript' charset='utf-8'>
+var loc = document.location;
+with(window.parent) { setTimeout(function() { window.eval('#{escaped_script}'); window.loc && loc.replace('about:blank'); }, 1) }
+</script></body></html>", :content_type => 'text/html'
+        end
+        
+        def respond_to_event(type, options)
+          handler = ProcEventHandler.new
+          handler.proc = options[:with]
+          ### TODO: pass :from => (event source).
+          
+          # attach once, not every request:
+          apotomo_root.evt_table.add_handler_once(handler, :event_type => type)
+        end
+        
+        
+        
+        ### DISCUSS: rename? should say "this controller action wants apotomo's deep linking!"
+        ### DISCUSS: move to deep_link_methods?
+        def respond_to_url_change
+          return if apotomo_root.find_widget('deep_link')  # add only once.
+          apotomo_root << widget("apotomo/deep_link_widget", :setup, 'deep_link')
+        end
+      
+      
+      class ProcHash < Array
+        def id_for_proc(proc)
+          proc.to_s.split('@').last
+        end
+      
+        def <<(proc)
+          super(id_for_proc(proc))
+        end
+        
+        def include?(proc)
+          super(id_for_proc(proc))
+        end
+      end
+    end
+  end
+end