apotomo 0.1.1

data/lib/apotomo/widget.rb

@@ -0,0 +1,289 @@
+require 'onfire'
+require 'apotomo/tree_node'
+
+
+require 'apotomo/event'
+require 'apotomo/event_methods'
+require 'apotomo/transition'
+require 'apotomo/caching'
+require 'apotomo/deep_link_methods'
+require 'apotomo/widget_shortcuts'
+require 'apotomo/rails/view_helper'
+
+### TODO: use load_hooks when switching to rails 3.
+# wycats@gmail.com: ActiveSupport.run_load_hooks(:name)
+# (21:01:17) wycats@gmail.com: ActiveSupport.on_load(:name) { … }
+#require 'active_support/lazy_load_hooks'
+
+module Apotomo
+  class Widget < Cell::Base
+    
+    class_inheritable_array :initialize_hooks, :instance_writer => false
+    self.initialize_hooks = []
+    
+    attr_accessor :opts
+    attr_writer   :visible
+    
+    include TreeNode
+    
+    
+    include Onfire
+    include EventMethods
+    
+    include Transition
+    include Caching
+    
+    include DeepLinkMethods
+    include WidgetShortcuts
+    
+    helper Apotomo::Rails::ViewHelper
+    
+    
+    attr_writer   :controller
+    attr_accessor :version
+    
+    ### DISCUSS: extract to has_widgets_methods for both Widget and Controller?
+    #class_inheritable_array :has_widgets_blocks
+    
+    class << self
+      include WidgetShortcuts
+      
+      def has_widgets_blocks
+        @has_widgets_blocks ||= []
+      end
+      
+      def has_widgets(&block)
+        has_widgets_blocks << block
+      end
+    end
+    self.initialize_hooks << :add_has_widgets_blocks
+    
+    def add_has_widgets_blocks(*)
+      self.class.has_widgets_blocks.each { |block| block.call(self) }
+    end
+    
+    
+    # Constructor which needs a unique id for the widget and one or multiple start states.
+    # <tt>start_state</tt> may be a symbol or an array of symbols.    
+    def initialize(id, start_state, opts={})
+      @opts         = opts
+      @name         = id
+      @start_state  = start_state
+
+      @visible      = true
+      @version      = 0
+      
+      @cell         = self
+      
+      process_initialize_hooks(id, start_state, opts)
+    end
+    
+    def process_initialize_hooks(*args)
+      self.class.initialize_hooks.each { |method| send(method, *args) }
+    end
+    
+    def last_state
+      @state_name
+    end
+    
+    def visible?
+      @visible
+    end
+
+    # Defines the instance vars that should <em>not</em> survive between requests, 
+    # which means they're not frozen in Apotomo::StatefulWidget#freeze.
+    def ivars_to_forget
+      unfreezable_ivars
+    end
+    
+    def unfreezable_ivars
+      [:@childrenHash, :@children, :@parent, :@controller, :@cell, :@invoke_block, :@rendered_children, :@page_updates, :@opts,
+      :@suppress_javascript ### FIXME: implement with ActiveHelper and :locals.
+      
+      ]
+    end
+
+    # Defines the instance vars which should <em>not</em> be copied to the view.
+    # Called in Cell::Base.
+    def ivars_to_ignore
+      []
+    end
+    
+    ### FIXME:
+    def logger; self; end
+    def debug(*args); puts args; 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, &block)
+      @invoke_block = block ### DISCUSS: store block so we don't have to pass it 10 times?
+      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)
+    end
+    
+    
+    
+    # called in Cell::Base#render_state
+    def dispatch_state(state)
+      send(state, &@invoke_block)
+    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
+    #      # ... 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>.
+    #
+    #  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)
+      
+      @controller = controller # that dependency SUCKS.
+      @suppress_js = options[:suppress_js]    ### FIXME: implement with ActiveHelper and :locals.
+      
+      
+      render_view_for(options, @state_name) # defined in Cell::Base.
+    end
+    
+    alias_method :emit, :render
+    
+    
+    def replace(options={})
+      content = render(options)
+      Apotomo.js_generator.replace(self.name, content) 
+    end
+    
+    def update(options={})
+      content = render(options)
+      Apotomo.js_generator.update(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={})
+      returning rendered_children = ActiveSupport::OrderedHash.new do
+        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]
+    end
+    
+    
+    # Returns the address hash to the event controller and the targeted widget.
+    #
+    # Reserved options for <tt>way</tt>:
+    #   :source   explicitly specifies an event source.
+    #             The default is to take the current widget as source.
+    #   :type     specifies the event type.
+    #
+    # Any other option will be directly passed into the address hash and is 
+    # available via StatefulWidget#param in the widget.
+    #
+    # Can be passed to #url_for.
+    # 
+    # Example:
+    #   address_for_event :type => :squeak, :volume => 9
+    # will result in an address that triggers a <tt>:click</tt> event from the current
+    # widget and also provides the parameter <tt>:item_id</tt>.
+    def address_for_event(options)
+      raise "please specify the event :type" unless options[:type]
+      
+      options[:source] ||= self.name
+      options
+    end
+    
+    # Returns the widget named <tt>widget_id</tt> as long as it is below self or self itself.
+    def find_widget(widget_id)
+      find {|node| node.name.to_s == widget_id.to_s}
+    end
+    
+    def controller
+      root? ? @controller : root.controller
+    end
+  end
+end

data/lib/apotomo/widget_shortcuts.rb

@@ -0,0 +1,36 @@
+module Apotomo
+  # Shortcut methods for creating widget trees.
+  module WidgetShortcuts
+    # Creates an instance of <tt>class_name</tt> with the id <tt>id</tt> and start state <tt>state</tt>.
+    # Default start state is <tt>:display</tt>.
+    # Yields self if a block is passed.
+    # Example:
+    #   widget(:form, 'uploads', :build_form) do |form|
+    #     form << widget(:upload_field)
+    def widget(class_name, id, state=:display, *args)
+      object = class_name.to_s.classify.constantize.new(id, state, *args)
+      yield object if block_given?
+      object
+    end
+    
+    def container(id, *args, &block)
+      widget('apotomo/container_widget', id, *args, &block)
+    end
+    
+    def section(*args)
+      container(*args)
+    end
+    
+    def cell(base_name, states, id, *args)
+      widget(base_name.to_s + '_cell', states, id, *args)
+    end
+    
+    def tab_panel(id, *args)
+      widget('apotomo/tab_panel_widget', :display, id, *args)
+    end
+    
+    def tab(id, *args)
+      widget('apotomo/tab_widget', :display, id, *args)
+    end
+  end
+end

data/test/fixtures/application_widget_tree.rb

@@ -0,0 +1,2 @@
+class ApplicationWidgetTree < Apotomo::WidgetTree
+end

data/test/rails/controller_methods_test.rb

@@ -0,0 +1,206 @@
+require File.join(File.dirname(__FILE__), *%w[.. test_helper])
+ 
+class ControllerMethodsTest < ActionController::TestCase
+  context "A Rails controller" do
+    setup do
+      barn_controller!
+    end
+    
+    context "responding to #apotomo_root" do
+      should "initially return a root widget" do
+        assert_equal 1, @controller.apotomo_root.size
+      end
+      
+      should "allow tree modifications" do
+        @controller.apotomo_root << mouse_mock
+        assert_equal 2, @controller.apotomo_root.size
+      end
+    end
+    
+    context "responding to #apotomo_request_processor" do
+      should "initially return the processor which has a flushed root" do
+        assert_kind_of Apotomo::RequestProcessor, @controller.apotomo_request_processor
+        assert_equal 1, @controller.apotomo_request_processor.root.size
+      end
+    end
+    
+    context "invoking #uses_widgets" do
+      setup do
+        @controller.class.uses_widgets do |root|
+          root << mouse_mock('mum')
+        end
+      end
+      
+      should "add the widgets to apotomo_root" do
+        assert_equal 'mum', @controller.apotomo_root['mum'].name
+      end
+      
+      should "add the widgets only once in apotomo_root" do
+        @controller.apotomo_root
+        assert @controller.apotomo_root['mum']
+      end
+      
+      should "allow multiple calls to uses_widgets" do
+        @controller.class.uses_widgets do |root|
+          root << mouse_mock('kid')
+        end
+        
+        assert @controller.apotomo_root['mum']
+        assert @controller.apotomo_root['kid']
+      end
+      
+      should "inherit uses_widgets blocks to sub-controllers" do
+        berry = mouse_mock('berry')
+        @sub_controller = Class.new(@controller.class) do
+          uses_widgets { |root| root << berry }
+        end.new
+        @sub_controller.params  = {}
+        @sub_controller.session = {}
+        
+        assert @sub_controller.apotomo_root['mum']
+        assert @sub_controller.apotomo_root['berry']
+      end
+      
+      should "be aliased to has_widgets" do
+        @controller.class.has_widgets do |root|
+          root << mouse_mock('kid')
+        end
+        
+        assert @controller.apotomo_root['mum']
+        assert @controller.apotomo_root['kid']
+      end
+    end
+    
+    context "invoking #use_widgets" do
+      should "have an empty apotomo_root if no call happened, yet" do
+        assert_equal [],  @controller.bound_use_widgets_blocks
+        assert_equal 1,   @controller.apotomo_root.size
+      end
+      
+      should "extend the widget family and remember the block with one #use_widgets call" do
+        @controller.use_widgets do |root|
+          root << mouse_mock
+        end
+        
+        assert_equal 1, @controller.bound_use_widgets_blocks.size
+        assert_equal 2, @controller.apotomo_root.size
+      end
+      
+      should "add blocks only once" do
+        block = Proc.new {|root| root << mouse_mock}
+        
+        @controller.use_widgets &block
+        @controller.use_widgets &block
+        
+        assert_equal 1, @controller.bound_use_widgets_blocks.size
+        assert_equal 2, @controller.apotomo_root.size
+      end
+      
+      should "allow multiple calls with different blocks" do
+        mum_and_kid!
+        @controller.use_widgets do |root|
+          root << @mum
+        end
+        @controller.use_widgets do |root|
+          root << mouse_mock('pet')
+        end
+        
+        assert_equal 2, @controller.bound_use_widgets_blocks.size
+        assert_equal 4, @controller.apotomo_root.size
+      end
+    end
+    
+    context "invoking #url_for_event" do
+      should "compute an url for any widget" do
+        assert_equal "/barn/render_event_response?source=mouse&type=footsteps&volume=9", @controller.url_for_event(:footsteps, :source => :mouse, :volume => 9)
+      end
+    end
+    
+    should "flush its bound_use_widgets_blocks with, guess, #flush_bound_use_widgets_blocks" do
+      @controller.bound_use_widgets_blocks << Proc.new {}
+      assert_equal 1, @controller.bound_use_widgets_blocks.size
+      @controller.flush_bound_use_widgets_blocks
+      assert_equal 0, @controller.bound_use_widgets_blocks.size
+    end 
+  end
+  
+  context "invoking #render_widget" do
+    setup do
+      @mum = mouse_mock('mum', 'snuggle') {def snuggle; render; end}
+    end
+    
+    should "render the widget" do
+      @controller.apotomo_root << @mum
+      assert_equal '<div id="mum"><snuggle></snuggle></div>', @controller.render_widget('mum')
+    end
+  end
+  
+  
+  
+  context "invoking #apotomo_freeze" do
+    should "freeze the widget tree to session" do
+      assert_equal 0, @controller.session.size
+      @controller.send :apotomo_freeze
+      assert @controller.session[:apotomo_widget_ivars]
+      assert @controller.session[:apotomo_stateful_branches]
+    end
+  end
+    
+  context "processing an event request" do
+    setup do
+      @mum = mouse_mock('mum', :eating)
+      @mum << @kid = mouse_mock('kid', :squeak)
+      
+      @kid.respond_to_event :doorSlam, :with => :eating, :on => 'mum'
+      @kid.respond_to_event :doorSlam, :with => :squeak
+      @mum.respond_to_event :doorSlam, :with => :squeak
+      
+      @mum.instance_eval do
+        def squeak; render :js => 'squeak();'; end
+      end
+      @kid.instance_eval do
+        def squeak; render :text => 'squeak!', :update => :true; end
+      end
+    end
+    
+    ### DISCUSS: needed?
+    context "in event mode" do
+      should_eventually "set the MIME type to text/javascript" do
+        @controller.apotomo_root << @mum
+        
+        get :render_event_response, :source => :kid, :type => :doorSlam
+        
+        assert_equal Mime::JS, @response.content_type
+        assert_equal "$(\"mum\").replace(\"<div id=\\\"mum\\\">burp!<\\/div>\")\n$(\"kid\").update(\"squeak!\")\nsqueak();", @response.body
+      end
+    end
+  end
+  
+  context "The ProcHash" do
+    setup do
+      @procs = Apotomo::Rails::ControllerMethods::ProcHash.new
+      @b = Proc.new{}; @d = Proc.new{}
+      @c = Proc.new{}
+      @procs << @b
+    end
+    
+    should "return true for procs it includes" do
+      assert @procs.include?(@b)
+      assert @procs.include?(@d)  ### DISCUSS: line nr is id, or do YOU got a better idea?!
+    end
+    
+    should "reject unknown procs" do
+      assert ! @procs.include?(@c)
+    end
+  end
+  
+  ### FIXME: could somebody get that working?
+  context "Routing" do
+    should_eventually "generate routes to the render_event_response action" do
+      assert_generates "/barn/render_event_response?type=squeak", { :controller => "barn", :action => "render_event_response", :type => "squeak" }
+      
+      assert_recognizes({ :controller => "apotomo", :action => "render_event_response", :type => "squeak" }, "/apotomo/render_event_response?type=squeak")
+    end
+  end
+  
+end