apotomo 0.1.1

data/lib/apotomo/rails/view_helper.rb

@@ -0,0 +1,95 @@
+module Apotomo
+  module Rails
+    module ViewHelper
+      # needs :@controller
+      
+      # Returns the app JavaScript generator.
+      def js_generator
+        Apotomo.js_generator
+      end
+      
+      
+      # Generates the JavaScript code to report an event of <tt>type</tt> to Apotomo with AJAX.
+      # As always per default the event source is the currently rendered widget.
+      # Internally this method just uses <tt>remote_function</tt> for JS output.
+      #
+      # Example:
+      # 
+      #   <%= image_tag "cheese.png", :onMouseover => trigger_event(:mouseAlarm) %>
+      #
+      # will trigger the event <tt>:mouseAlarm</tt> when moving the mouse over the cheese image.
+      def trigger_event(type, options={})
+        js_generator.xhr(url_for_event(type, options))
+      end
+      
+      # Creates a link that triggers an event via AJAX.
+      # This link will <em>only</em> work in JavaScript-able browsers.
+      #
+      # Note that the link is created using #link_to_remote.
+      def link_to_event(title, type, options={}, html_options={})
+        link_to_remote(title, {:url => url_for_event(type, options)}, html_options)
+      end
+      
+      # Creates a form tag that triggers an event via AJAX when submitted.
+      # See StatefulWidget::address_for_event for options.
+      #
+      # The values of form elements are available via StatefulWidget#param.
+      def form_to_event(type, options={}, html_options={}, &block)
+        return multipart_form_to_event(type, options, html_options, &block) if options.delete(:multipart)
+        
+        form_remote_tag({:url => url_for_event(type, options), :html => html_options}, &block)
+        ### FIXME: couldn't get obstrusive js working, i don't understand rails helpers.
+        #html_options[:onSubmit] = js_generator.escape(js_generator.xhr(url_for_event(type, options)))
+        #puts html_options.inspect
+        #form_tag(url_for_event(type, options), html_options, &block)
+      end
+      
+      # Creates a form that submits itself via an iFrame and executes the response
+      # in the parent window. This is needed to upload files via AJAX.
+      #
+      # Better call <tt>#form_to_event :multipart => true</tt> and stay forward-compatible.
+      def multipart_form_to_event(type, options={}, html_options={}, &block)
+        options.reverse_merge!      :apotomo_iframe => true
+        html_options.reverse_merge! :target         => :apotomo_iframe, :multipart => true
+        
+        # i hate rails:
+        concat('<iframe id="apotomo_iframe" name="apotomo_iframe" style="display: none;"></iframe>') << form_tag(url_for_event(type, options), html_options, &block)
+      end
+      
+      # Returns the url to trigger a +type+ event from the currently rendered widget.
+      # The source can be changed with +:source+. 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, :page => 2)
+      #   #=> http://apotomo.de/mouse/process_event_request?type=paginate&source=mouse&page=2
+      def url_for_event(type, options={})
+        options.reverse_merge! :source => @cell.name
+        @controller.url_for_event(type, options)
+      end
+      
+      ### TODO: test me.
+      def update_url(fragment)
+        'SWFAddress.setValue("' + fragment + '");'
+      end
+      
+      ### TODO: test me.
+      ### DISCUSS: rename to rendered_children ?
+      def content
+        @rendered_children.collect{|e| e.last}.join("\n")
+      end
+      
+      # needs: suppress_javascript
+      def widget_javascript(*args, &block)
+        return if @suppress_js ### FIXME: implement with ActiveHelper and :locals.
+        
+        javascript_tag(*args, &block)
+      end
+      
+      def widget_div(*args, &block)
+        content_tag(:div, :id => @cell.name, :class => :widget, &block)
+      end
+    end  
+  end
+end

data/lib/apotomo/rails/view_methods.rb

@@ -0,0 +1,7 @@
+module Apotomo
+  module Rails
+    module ViewMethods
+      delegate :render_widget, :url_for_event, :to => :controller
+    end
+  end
+end

data/lib/apotomo/request_processor.rb

@@ -0,0 +1,92 @@
+module Apotomo
+  class RequestProcessor
+    include WidgetShortcuts
+    
+    attr_reader :session, :root
+    
+    def initialize(session, options={}, uses_widgets_blocks=[])
+      @session              = session
+      @widgets_flushed      = false
+      
+      @root = widget('apotomo/widget', 'root')
+      uses_widgets_blocks.each { |blk| blk.call(@root) } # add stateless widgets.
+      
+      if options[:flush_widgets].blank? and ::Apotomo::StatefulWidget.frozen_widget_in?(session)  
+        @root = ::Apotomo::StatefulWidget.thaw_for(session, @root)
+      else
+        #@root = flushed_root
+        
+        flushed_root  ### FIXME: set internal mode to flushed 
+      end
+      
+      #handle_version!(options[:version])
+    end
+    
+    
+    def flushed_root
+      StatefulWidget.flush_storage(session)
+      @widgets_flushed = true
+      #widget('apotomo/widget', 'root')
+    end
+    
+    ### DISCUSS: do we need the version feature, or should we push that into user code?
+    def handle_version!(version)
+      return if version.blank?
+      return if root.version == version
+      
+      @root = flushed_root
+      @root.version = version
+    end
+    
+    def widgets_flushed?;  @widgets_flushed; end
+    
+    # Fires the request event in the widget tree and collects the rendered page updates.
+    def process_for(request_params, controller)
+      ### TODO: move controller dependency to rails/merb/sinatra layer only!
+      self.root.controller = controller
+      
+      source = self.root.find_widget(request_params[:source]) or raise "Source #{request_params[:source].inspect} non-existent."
+      
+      source.fire(request_params[:type].to_sym)
+      source.root.page_updates ### DISCUSS: that's another dependency.
+    end
+    
+    ### FIXME: remove me!
+    def render_page_updates(page_updates)
+      page_updates.join("\n")
+    end
+    
+    # Serializes the current widget tree to the storage that was passed in the constructor.
+    # Call this at the end of a request.
+    def freeze!
+      Apotomo::StatefulWidget.freeze_for(@session, root)
+    end
+    
+    # Renders the widget named <tt>widget_id</tt>, passing optional <tt>opts</tt> and a block to it.
+    # Use this in your #render_widget wrapper.
+    def render_widget_for(widget_id, opts, controller, &block)
+      if widget_id.kind_of?(::Apotomo::Widget)
+        widget = widget_id
+      else
+        widget = root.find_widget(widget_id)
+        raise "Couldn't render non-existent widget `#{widget_id}`" unless widget
+      end
+      
+      
+      ### TODO: pass options in invoke.
+      widget.opts = opts unless opts.empty?
+      
+      ### TODO: move controller dependency to rails/merb/sinatra layer only!
+      widget.root.controller = controller
+      
+      widget.invoke(&block)
+    end
+    
+    # Computes the address hash for a +:source+ widget and an event +:type+.
+    # Additional parameters will be merged.
+    def address_for(options)
+      raise "You forgot to provide :source or :type" unless options.has_key?(:source) and options.has_key?(:type)
+      options
+    end
+  end
+end

data/lib/apotomo/stateful_widget.rb

@@ -0,0 +1,8 @@
+require 'apotomo/widget'
+require 'apotomo/persistence'
+
+module Apotomo
+  class StatefulWidget < Widget
+    include Persistence
+  end
+end

data/lib/apotomo/transition.rb

@@ -0,0 +1,46 @@
+module Apotomo::Transition
+  
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    # Defines a transition for an implicit invoke.
+    #
+    # Usually when a container widget renders its kids there is no <tt>state</tt> passed to the
+    # kid's #invoke ("implicit invoke") and thus the kid will enter its start state again.
+    # You can customize that behaviour by setting a transition to let the widget jump to the 
+    # defined <tt>:to</tt> state in place of the start state.
+    #
+    # Example:
+    #   class Kid < MouseWidget
+    #     transition :from => :sleep, :to => :snore
+    #
+    # Next time when mum renders and kid is in <tt>:sleep</tt> state kid will not return to its 
+    # start state but invoke <tt>:snore</tt>.
+    #
+    #   class Kid < MouseWidget
+    #     transition :in => :snore
+    #
+    # In subsequent render cycles from mum kid will keep snoring whereas other kids would go back
+    # to the start state.
+    def transition(options)
+      if from = options[:from]
+        class_transitions[from] = options[:to]
+      elsif loop = options[:in]
+        transition :from => loop, :to => loop
+      end
+    end
+    
+    def class_transitions
+      @class_transitions ||= {}
+    end
+  end
+  
+  protected
+    # Returns the next state for <tt>state</tt> or nil. A next state must have been defined 
+    # with #transition.
+    def next_state_for(state)
+      self.class.class_transitions[state]
+    end
+end

data/lib/apotomo/tree_node.rb

@@ -0,0 +1,186 @@
+# stolen from ... ? couldn't find the original lib on the net.
+### TODO: insert copyright notice!
+
+module TreeNode
+  include Enumerable
+
+  attr_reader :content, :name, :parent
+  attr_writer :content, :parent
+  
+  def self.included(base)
+    base.initialize_hooks << :initialize_tree_node_for
+  end
+  
+  # Constructor which expects the name of the node
+  #
+  # name of the node is expected to be unique across the
+  # tree.
+  def initialize_tree_node_for(name, *args)
+    self.setAsRoot!
+
+    @childrenHash = Hash.new
+    @children = []
+  end
+
+  # Print the string representation of this node.
+  def to_s
+          s = size()
+          "Node ID: #{@name} Content: #{@content} Parent: " +
+                  (root?()  ? "ROOT" : "#{@parent.name}") +
+                  " Children: #{@children.length}" +
+                  " Total Nodes: #{s}"
+  end
+
+  # Convenience synonym for Tree#add method. 
+  # This method allows a convenient method to add
+  # children hierarchies in the tree.
+  # E.g. root << child << grand_child
+  def <<(child)
+      add(child)
+  end
+
+  # Adds the specified child node to the receiver node.
+  # The child node's parent is set to be the receiver.
+  # The child is added as the last child in the current
+  # list of children for the receiver node.
+  def add(child)
+      raise "Child already added" if @childrenHash.has_key?(child.name)
+
+      @childrenHash[child.name]  = child
+      @children << child
+      child.parent = self
+      return child
+  end
+
+  # Removes the specified child node from the receiver node.
+  # The removed children nodes are orphaned but available
+  # if an alternate reference exists.
+  # Returns the child node.
+  def remove!(child)
+      @childrenHash.delete(child.name)
+      @children.delete(child)
+      child.setAsRoot! unless child == nil
+      return child
+  end
+
+  # Removes this node from its parent. If this is the root node,
+  # then does nothing.
+  def removeFromParent!
+      @parent.remove!(self) unless root?
+  end
+
+  # Removes all children from the receiver node.
+  def remove_all!
+      for child in @children
+          child.setAsRoot!
+      end
+      @childrenHash.clear
+      @children.clear
+      self
+  end
+  
+  
+  # Private method which sets this node as a root node.
+  def setAsRoot!
+      @parent = nil
+  end
+  
+  def root!
+    setAsRoot!
+  end
+
+  # Indicates whether this node is a root node. Note that
+  # orphaned children will also be reported as root nodes.
+  def root?
+      @parent == nil
+  end
+  
+  # Returns an array of all the immediate children.
+  # If a block is given, yields each child node to the block.
+  def children
+      if block_given?
+          @children.each {|child| yield child}
+      else
+          @children
+      end
+  end
+
+  # Returns every node (including the receiver node) from the
+  # tree to the specified block.
+  def each &block
+      yield self
+      children { |child| child.each(&block) }
+  end
+
+  # Returns the requested node from the set of immediate
+  # children.
+  # 
+  # If the key is _numeric_, then the in-sequence array of
+  # children is accessed (see Tree#children).
+  # If the key is not _numeric_, then it is assumed to be
+  # the *name* of the child node to be returned.
+  def [](key)
+      raise "Key needs to be provided" if key == nil
+
+      if key.kind_of?(Integer)
+          @children[key]
+      else
+          @childrenHash[key]
+      end
+  end
+
+  # Returns the total number of nodes in this tree, rooted
+  # at the receiver node.
+  def size
+      @children.inject(1) {|sum, node| sum + node.size}
+  end
+
+  # Pretty prints the tree starting with the receiver node.
+  def printTree(tab = 0)
+      puts((' ' * tab) + self.to_s)
+      children {|child| child.printTree(tab + 4)}
+  end
+
+  # Returns the root for this node.
+  def root
+      root = self
+      root = root.parent while !root.root?
+      root
+  end
+
+  # Provides a comparision operation for the nodes. Comparision
+  # is based on the natural character-set ordering for the
+  # node names.
+  def <=>(other)
+      return +1 if other == nil
+      self.name <=> other.name
+  end
+  
+  protected :parent=, :setAsRoot!
+  
+  def find_by_path(selector)
+    next_node = self
+    last      = nil # prevents self-finding loop.
+    selector.to_s.split(/ /).each do |node_id| 
+      last = next_node = next_node.find {|n|
+        n.name.to_s == node_id.to_s and not n==last
+      }
+    end
+    
+    return next_node
+  end
+  
+  
+  # Returns the path from the widget to root, encoded as 
+  # a string of slash-seperated names. 
+  def path
+    path      = [name]     
+    ancestor  = parent
+    while ancestor
+      path << ancestor.name
+      ancestor = ancestor.parent
+    end
+    
+    path.reverse.join("/")
+  end
+end

data/lib/apotomo/version.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+module Apotomo
+  VERSION = '0.1.1'
+end