apotomo 1.0.5 → 1.1.0.rc1

data/lib/apotomo/rails/view_helper.rb

@@ -1,7 +1,21 @@
 module Apotomo
   module Rails
+    # == #url_for_event
+    #
+    #   = url_for_event(:paginate, :page => 2)
+    #   #=> http://apotomo.de/mouse/process_event_request?type=paginate&source=mouse&page=2
+    #
+    # == #widget_id
+    #
+    #   = widget_id
+    #   #=> :mouse
+    #
+    # == #children
+    #
+    #   - children.each do |kid|
+    #     = render_widget kid
     module ViewHelper
-      # needs :@controller
+      delegate :children, :url_for_event, :widget_id, :to => :controller
       
       # Returns the app JavaScript generator.
       def js_generator
@@ -20,31 +34,6 @@ module Apotomo
         concat('<iframe id="apotomo_iframe" name="apotomo_iframe" style="display: none;"></iframe>'.html_safe) << 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={})
-        controller.url_for_event(type, options)
-      end
-      
-      ### TODO: test me.
-      ### DISCUSS: rename to rendered_children ?
-      def content
-        @rendered_children.collect{|e| e.last}.join("\n").html_safe
-      end
-      
-      # needs: suppress_javascript
-      def widget_javascript(*args, &block)
-        return if @suppress_js ### FIXME: implement with ActiveHelper and :locals.
-        
-        javascript_tag(*args, &block)
-      end
-      
       # Wraps your content in a +div+ and sets the id. Feel free to pass additional html options.
       #
       # Example:
@@ -61,11 +50,6 @@ module Apotomo
         options.reverse_merge!(:id => widget_id) 
         content_tag(:div, options, &block)
       end
-      
-      # Returns the widget id you passed in a has_widgets block.
-      def widget_id
-        controller.name
-      end
     end  
   end
 end

data/lib/apotomo/railtie.rb

@@ -0,0 +1,24 @@
+require "rails/railtie"
+
+module Apotomo
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load "apotomo/apotomo.rake"
+    end
+    
+    # As we are a Railtie only, the routes won't be loaded automatically. Beside that, we want our 
+    # route to be the very first (otherwise #resources might supersede it).
+    initializer 'apotomo.prepend_routes', :after => :add_routing_paths do |app|
+      app.routes_reloader.paths.unshift(File.dirname(__FILE__) + "/../../config/routes.rb")
+    end
+    
+    # Include a lazy loader via has_widgets.
+    initializer 'apotomo.add_has_widgets' do |app|
+      ActionController::Base.extend Apotomo::Rails::ControllerMethodsLoader
+    end
+    
+    initializer 'apotomo.setup_view_paths', :after => 'cells.setup_view_paths' do |app|
+      Apotomo::Widget.setup_view_paths!
+    end
+  end 
+end

data/lib/apotomo/request_processor.rb

@@ -1,70 +1,39 @@
 module Apotomo
   class RequestProcessor
-    attr_reader :session, :root
+    include Hooks
     
-    def initialize(controller, session, options={}, has_widgets_blocks=[])
-      @session              = session
-      @widgets_flushed      = false
-      
+    define_hook :after_initialize
+    define_hook :after_fire
+    
+    attr_reader :root
+    
+    
+    def initialize(controller, options={}, has_widgets_blocks=[])
       @root = Widget.new(controller, 'root', :display)
       
       attach_stateless_blocks_for(has_widgets_blocks, @root, controller)
       
-      if options[:flush_widgets].blank? and ::Apotomo::StatefulWidget.frozen_widget_in?(session)  
-        @root = ::Apotomo::StatefulWidget.thaw_for(controller, session, @root)
-      else
-        #@root = flushed_root
-        
-        flushed_root  ### FIXME: set internal mode to flushed 
-      end
+      run_hook :after_initialize, self
     end
     
     def attach_stateless_blocks_for(blocks, root, controller)
       blocks.each { |blk| controller.instance_exec(root, &blk) }
     end
     
-    def flushed_root
-      StatefulWidget.flush_storage(session)
-      @widgets_flushed = true
-      #widget('apotomo/widget', 'root')
-    end
-        
-    def widgets_flushed?;  @widgets_flushed; end
-    
-    # Fires the request event in the widget tree and collects the rendered page updates.
+    # Called when the browser wants an url_for_event address. This fires the request event in 
+    # the widget tree and collects the rendered page updates.
     def process_for(request_params)
       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.fire(request_params[:type].to_sym, request_params) # set data to params for now.
+      
+      run_hook :after_fire, self
       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, &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?
-      
-      widget.invoke(&block)
+    # Renders the widget named +widget_id+. Any additional args is passed through to Widget#invoke.
+    def render_widget_for(*args)
+      root.render_widget(*args)
     end
     
     # Computes the address hash for a +:source+ widget and an event +:type+.

data/lib/apotomo/test_case.rb

@@ -42,7 +42,7 @@ module Apotomo
     def setup
       super
       @controller.instance_eval do 
-        def controller_name
+        def controller_path
          'barn'
         end
       end
@@ -53,7 +53,7 @@ module Apotomo
     # Returns the widget tree from TestCase.has_widgets.
     def root
       blk = self.class.has_widgets_blocks or raise "Please setup a widget tree using TestCase.has_widgets"
-      @root ||= widget("apotomo/widget", "root").tap do |root|
+      @root ||= Apotomo::Widget.new(parent_controller, "root").tap do |root|
          self.instance_exec(root, &blk)
       end
     end
@@ -63,8 +63,8 @@ module Apotomo
     end
     
     # Renders the widget +name+.
-    def render_widget(name, options={})
-      @last_invoke = root.find_widget(name).tap { |w| w.opts = options }.invoke # DISCUSS: use ControllerMethods?
+    def render_widget(*args)
+      @last_invoke = root.render_widget(*args)
     end
     
     # Triggers an event of +type+. You have to pass <tt>:source</tt> as options.
@@ -74,7 +74,7 @@ module Apotomo
     #   trigger :submit, :source => "post-comments"
     def trigger(type, options)
       source = root.find_widget(options.delete(:source))
-      source.instance_variable_set :@params, options  # TODO: this is just a try-out (what about children?). 
+      source.options.merge!(options)  # TODO: this is just a try-out (what about children?). 
       source.fire(type)
       root.page_updates # DISCUSS: use ControllerMethods?
     end

data/lib/apotomo/tree_node.rb

@@ -4,27 +4,24 @@
 module TreeNode
   include Enumerable
 
-  attr_reader :content, :name, :parent
-  attr_writer :content, :parent
+  attr_reader :name, :childrenHash
+  attr_accessor :parent
   
   def self.included(base)
     base.after_initialize :initialize_tree_node
   end
   
   def initialize_tree_node(*)
-    self.setAsRoot!
+    root!
 
-    @childrenHash = Hash.new
+    @childrenHash = {}
     @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}"
+    "Node ID: #{widget_id} Parent: " + (root?  ? "ROOT" : "#{parent.name}") +
+      " Children: #{children.length}" + " Total Nodes: #{size}"
   end
 
   # Convenience synonym for Tree#add method. 
@@ -32,7 +29,7 @@ module TreeNode
   # children hierarchies in the tree.
   # E.g. root << child << grand_child
   def <<(child)
-      add(child)
+    add(child)
   end
 
   # Adds the specified child node to the receiver node.
@@ -40,13 +37,13 @@ module TreeNode
   # 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)
+    raise "Child already added" if @childrenHash.has_key?(child.name)
 
-      @childrenHash[child.name]  = child
-      @children << child
-      child.parent = self
-      
-      child.run_widget_hook(:after_add, child, self)
+    @childrenHash[child.name]  = child
+    @children << child
+    child.parent = self
+    
+    child.run_widget_hook(:after_add, child, self)
     child
   end
 
@@ -55,59 +52,55 @@ module TreeNode
   # 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
+    @childrenHash.delete(child.name)
+    @children.delete(child)
+    child.root! unless child == nil
+    child
   end
 
   # Removes this node from its parent. If this is the root node,
   # then does nothing.
-  def removeFromParent!
-      @parent.remove!(self) unless root?
+  def remove_from_parent!
+    @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
+    for child in @children
+      child.root!
+    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!
+    @parent = nil
   end
-
+  
   # Indicates whether this node is a root node. Note that
   # orphaned children will also be reported as root nodes.
   def root?
-      @parent == nil
+    @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
+    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) }
+  def each(&block)
+    yield self
+    children { |child| child.each(&block) }
   end
 
   # Returns the requested node from the set of immediate
@@ -117,44 +110,42 @@ module TreeNode
   # 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
+  def [](name)
+    if name.kind_of?(Integer)
+      children[name]
+    else
+      childrenHash[name]
+    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}
+    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)}
+    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
+    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
+    return +1 if other == nil
+    self.name <=> other.name
   end
   
-  protected :parent=, :setAsRoot!
+  protected :parent=, :root!
   
   def find_by_path(selector)
     next_node = self
@@ -165,7 +156,7 @@ module TreeNode
       }
     end
     
-    return next_node
+    next_node
   end
   
   

data/lib/apotomo/version.rb

@@ -1,3 +1,3 @@
 module Apotomo
-  VERSION = '1.0.5'
+  VERSION = '1.1.0.rc1'
 end

data/lib/apotomo/widget.rb

@@ -5,12 +5,42 @@ require 'hooks'
 require 'apotomo/tree_node'
 require 'apotomo/event'
 require 'apotomo/event_methods'
-require 'apotomo/transition'
 require 'apotomo/widget_shortcuts'
 require 'apotomo/rails/view_helper'
+require 'apotomo/rails/controller_methods'  # FIXME.
+
+require 'apotomo/widget/javascript_methods'
+
 
 module Apotomo
+  # == Accessing Parameters
+  #
+  # Apotomo tries to prevent you from having to access the global #params hash. We have the following
+  # concepts to retrieve input data.
+  #
+  # 1. Configuration values are available both in render and triggered states. Pass those in #widget
+  # when creating the widget tree. Use #options for reading.
+  #
+  #   has_widgets do |root|
+  #     root << widget(:mouse_widget, 'mum', :favorites => ["Gouda", "Chedar"])
+  #
+  # and read in your widget state
+  #
+  #   def display
+  #     @cheese = options[:favorites].first
+  #
+  # 2. Request data from forms etc. is available through <tt>event.data</tt> in the triggered states. 
+  # Use the <tt>#[]</tt> shortcut to access values directly.
+  #
+  #   def update(evt)
+  #     @cheese = Cheese.find evt[:cheese_id]
   class Widget < Cell::Base
+    
+    DEFAULT_VIEW_PATHS = [
+      File.join('app', 'widgets'),
+      File.join('app', 'widgets', 'layouts')
+    ]
+    
     include Hooks
     
     # Use this for setup code you're calling in every state. Almost like a +before_filter+ except that it's
@@ -23,27 +53,31 @@ module Apotomo
     #     
     #     # we need @cheese in every state:
     #     def setup_cheese(*)
-    #       @cheese = Cheese.find @opts[:cheese_id]
+    #       @cheese = Cheese.find options[:cheese_id]
     define_hook :after_initialize
     define_hook :has_widgets
     define_hook :after_add
     
-    attr_accessor :opts
-    attr_writer   :visible
-
+    attr_writer :visible
+    
     include TreeNode
     
     include Onfire
-    include EventMethods
     
-    include Transition
+    include EventMethods
     include WidgetShortcuts
+    include JavascriptMethods
     
     helper Apotomo::Rails::ViewHelper
+    helper Apotomo::Rails::ActionViewMethods
     
     abstract!
+    
     undef :display  # We don't want #display to be listed in #internal_methods.
     
+    alias_method :widget_id, :name
+    
+    
     # Runs callbacks for +name+ hook in instance context.  
     def run_widget_hook(name, *args)
       self.class.callbacks_for_hook(name).each { |blk| instance_exec(*args, &blk) }
@@ -55,180 +89,55 @@ module Apotomo
     after_initialize :add_has_widgets_blocks
     
     
-    # Constructor which needs a unique id for the widget and one or multiple start states.  
-    def initialize(parent_controller, id, start_state, opts={})
-      super(parent_controller, opts)  # do that as long as cells do need a parent_controller.
+    def initialize(parent_controller, id, options={})
+      super(parent_controller, options)  # do that as long as cells do need a parent_controller.
       
       @name         = id
-      @start_state  = start_state
-
       @visible      = true
-      @cell         = self  ### DISCUSS: needed?
-      
-      @params       = parent_controller.params.dup.merge(opts)
       
       run_hook :after_initialize, self
     end
     
-    def last_state
-      action_name
-    end
-    
     def visible?
       @visible
     end
     
-    # Returns the rendered content for the widget by running the state method for <tt>state</tt>.
-    # This might lead us to some other state since the state method could call #jump_to_state.
-    def invoke(state=nil, event=nil)
-      logger.debug "\ninvoke on #{name} with #{state.inspect}"
-      
-      if state.blank?
-        state = next_state_for(last_state) || @start_state
-      end
-      
-      logger.debug "#{name}: transition: #{last_state} to #{state}"
-      logger.debug "                                    ...#{state}"
-      
-      #render_state(state)
-      
-      return render_state(state, event) if method(state).arity == 1
-      
-      opts[:event] = event
+    # Invokes +state+ and hopefully returns the rendered content.
+    def invoke(state, *args)
+      return render_state(state, *args) if state_accepts_args?(state)
       render_state(state)
     end
     
-    
     # Render the view for the current state. Usually called at the end of a state method.
     #
     # ==== Options
     # * <tt>:view</tt> - Specifies the name of the view file to render. Defaults to the current state name.
     # * <tt>:template_format</tt> - Allows using a format different to <tt>:html</tt>.
     # * <tt>:layout</tt> - If set to a valid filename inside your cell's view_paths, the current state view will be rendered inside the layout (as known from controller actions). Layouts should reside in <tt>app/cells/layouts</tt>.
-    # * <tt>:render_children</tt> - If false, automatic rendering of child widgets is turned off. Defaults to true.
-    # * <tt>:invoke</tt> - Explicitly define the state to be invoked on a child when rendering.
     # * see Cell::Base#render for additional options
     #
-    # Note that <tt>:text => ...</tt> and <tt>:update => true</tt> will turn off <tt>:frame</tt>.
-    #
     # Example:
-    #  class MouseCell < Apotomo::StatefulWidget
-    #    def eating
+    #  class MouseWidget < Apotomo::StatefulWidget
+    #    def eat
     #      # ... do something
     #      render 
     #    end
     #
-    # will just render the view <tt>eating.html</tt>.
-    # 
-    #    def eating
-    #      # ... do something
-    #      render :view => :bored, :layout => "metal"
-    #    end
-    #
-    # will use the view <tt>bored.html</tt> as template and even put it in the layout
-    # <tt>metal</tt> that's located at <tt>$RAILS_ROOT/app/cells/layouts/metal.html.erb</tt>.
+    # will just render the view <tt>eat.haml</tt>.
     #
     #  render :js => "alert('SQUEAK!');"
     #
     # issues a squeaking alert dialog on the page.
-    def render(options={}, &block)
-      if options[:nothing]
-        return "" 
-      end
-      
-      if options[:text]
-        options.reverse_merge!(:render_children => false)
-      end
-      
-      options.reverse_merge!  :render_children  => true,
-                              :locals           => {},
-                              :invoke           => {},
-                              :suppress_js      => false
-                              
-      
-      rendered_children = render_children_for(options)
-      
-      options[:locals].reverse_merge!(:rendered_children => rendered_children)
-      
-      @suppress_js = options[:suppress_js]    ### FIXME: implement with ActiveHelper and :locals.
-      
-      
-      render_view_for(options, action_name) # defined in Cell::Base.
+    def render(*args, &block)
+      super
     end
     
     alias_method :emit, :render
     
-    # Wraps the rendered content in a replace statement targeted at your +Apotomo.js_framework+ setting.
-    # Use +:selector+ to change the selector.
-    #
-    # Example:
-    #
-    # Assuming you set 
-    #   Apotomo.js_framework = :jquery
-    #
-    # and call replace in a state
-    #
-    #   replace :view => :squeak, :selector => "div#mouse"
-    #   #=> "$(\"div#mouse\").replaceWith(\"<div id=\\\"mum\\\">squeak!<\\/div>\")"
-    def replace(options={})
-      content = render(options)
-      Apotomo.js_generator.replace(options[:selector] || self.name, content)
-    end
-    
-    # Same as replace except that the content is wrapped in an update statement.
-    #
-    # Example for +:jquery+:
-    #
-    #   update :view => :squeak
-    #   #=> "$(\"mum\").html(\"<div id=\\\"mum\\\">squeak!<\\/div>\")"
-    def update(options={})
-      content = render(options)
-      Apotomo.js_generator.update(options[:selector] || self.name, content)
-    end
-
-    # Force the FSM to go into <tt>state</tt>, regardless whether it's a valid 
-    # transition or not.
-    ### TODO: document the need for return.
-    def jump_to_state(state)
-      logger.debug "STATE JUMP! to #{state}"
-      
-      render_state(state)
-    end
-    
-    
-    def visible_children
-      children.find_all { |kid| kid.visible? }
-    end
-
-    def render_children_for(options)
-      return {} unless options[:render_children]
-      
-      render_children(options[:invoke])
-    end
-    
-    def render_children(invoke_options={})
-      ActiveSupport::OrderedHash.new.tap do |rendered_children|
-        visible_children.each do |kid|
-          child_state = decide_state_for(kid, invoke_options)
-          logger.debug "    #{kid.name} -> #{child_state}"
-          
-          rendered_children[kid.name] = render_child(kid, child_state)
-        end
-      end
-    end
-
-    def render_child(cell, state)
-     cell.invoke(state)
-    end
-
-    def decide_state_for(child, invoke_options)
-      invoke_options.stringify_keys[child.name.to_s]
-    end
-    
-    
-    ### DISCUSS: use #param only for accessing request data.
     def param(name)
-      @params[name]
+      msg = "Deprecated. Use #options for widget constructor options or #params for request data."
+      ActiveSupport::Deprecation.warn(msg)
+      raise msg
     end
     
     
@@ -247,6 +156,21 @@ module Apotomo
       apotomo_event_path address_for_event(type, options) 
     end
     
-    alias_method :widget_id, :name
+    
+    def self.controller_path
+      @controller_path ||= name.sub(/Widget$/, '').underscore unless anonymous?
+    end
+    
+    # Renders the +widget+ (instance or id).
+    def render_widget(widget_id, state=:display, *args)
+      if widget_id.kind_of?(Widget)
+        widget = widget_id
+      else
+        widget = find_widget(widget_id) or raise "Couldn't render non-existent widget `#{widget_id}`"
+      end
+      
+      widget.invoke(state, *args)
+    end
   end
 end
+