apotomo 1.0.5 → 1.1.0.rc1

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+*.gem
+.bundle
+test/dummy/log/*
+test/dummy/tmp/*

data/CHANGES.textile

@@ -1,17 +1,45 @@
-h2. 1.0.5
+h2. 1.1
 
+h3. Changes
+  * Widgets now reside in @app/widgets/@ and have the @Widget@ appendix per convention, identical to cells and controllers. This introduces the following changes, illustrated with an imaginary @CommentsWidget@:
+  ** @widget(:comments, ...)@ will search and instantiate @CommentsWidget@ (note the missing "Widget").
+  ** The @CommentsWidget@ views are searched in @app/widgets/comments/@ (note the missing "_widget").
+  * Including Apotomo::Rails::ControllerMethods by hand is optional. The first call to Controller.has_widgets will include the real module.
+  * You can now @#render_widget@ in your widget views to render children.
+  * @#widget@ now accepts one arg only (the widget prefix). @widget(:comments)@ sets id to @:comments@. We also removed the start state argument.
+  * Start states are no longer accepted, you have to explicitely pass the state to #render_widget. That's why #invoke now requires an explicit state as well.
+  * The event is no longer added to #options at triggering time.
+  * Options passed in #render_widget are no longer merged with #options. They are passed as state-args to reduce complexity.
+  * We no longer have @opts and @params but #options and #params from Cell::Base.
+  * The params hash is appended to the event in RequestProcessor#process_for. You can now live completely without accessing the global #params.
+  * #respond/#update with :selector does not longer prefix the selector with #. It's up to you.
+  * Event delegates #[] to #data.
+
+h3. Removals
+  * Removed #param, it is simply too complex.
+  * Removed render :render_children and :invoke options. Use #render_widget in your state/view.
+  * Removed render :suppress_js as it was ugly and kills children.
+  * Removed #jump_to_state and #last_state.
+  * Removed `@cell`, now longer available in state views.
+  * Removed #cell, #container and #section widget shortcuts.
+  * Removed @rendered_children@ local in views. Use #render_widget.
+  * Removed ContainerWidget, nobody needs it.
+  
 h3. Bugfixes
-  * Fixed a bug in Widget.responds_to_event. Thanks to Scott Rainey for urging.
+  * Widget.responds_to_event no longer shares its options with multiple widget instances of the same class.
+
 
 h2. 1.0.4
 
 h3. Bugfixes
-  * Caching states works, again. Thanks to Gudleik Rasch for spotting.
-  * We cleanly require cells-3.4.x now. Thanks to Ryan Bates who remarked that Apotomo 1.0.x tries to require cells-3.5, which was wrong.
-  
+    * Caching states works, again. Thanks to Gudleik Rasch for spotting.
+    * We cleanly require cells-3.4.x now. Thanks to Ryan Bates who remarked that Apotomo 1.0.x tries to require cells-3.5, which was wrong.
+
 h3. Notes
-  * Removed the usage of state-args. If you want the event instance in your triggered state, use @opts[:event] or upgrade to apotomo-1.1.
-  
+
+    * Removed the usage of state-args. If you want the event instance in your triggered state, use @opts[:event] or upgrade to apotomo-1.1.
+
+
 h2. 1.0.3
 
 h3. Bugfixes

data/Gemfile

@@ -1,5 +1,3 @@
 source "http://rubygems.org"
 
 gemspec
-
-#gem "rails", :path => "/home/nick/projects/rayls"

data/README.rdoc

@@ -42,7 +42,7 @@ Let's wrap that comments block in a widget.
 
 Go and generate a widget stub.
 
-  $ rails generate apotomo:widget CommentsWidget display write --haml
+  $ rails generate apotomo:widget CommentsWidget display write -e haml
     create  app/cells/
     create  app/cells/comments_widget
     create  app/cells/comments_widget.rb
@@ -84,8 +84,8 @@ A widget is like a cell which is like a mini-controller.
   class CommentsWidget < Apotomo::Widget
     responds_to_event :submit, :with => :write
     
-    def display
-      @comments = param(:post).comments # the parameter from outside.
+    def display(args)
+      @comments = args[:post].comments # the parameter from outside.
       render
     end
 
@@ -93,9 +93,9 @@ Having +display+ as the default state when rendering, this method collects comme
 
 And look at line 2 - if encountering a <tt>:submit</tt> event we invoke +write+, which is simply another state. How cool is that? 
 
-    def write
-      @comment = Comment.new(:post => param(:post))
-      @comment.update_attributes param(:comment)  # like params[].
+    def write(evt)
+      @comment = Comment.new(:post_id => evt[:post_id])
+      @comment.update_attributes evt[:comment]  # a bit like params[].
       
       update :state => :display
     end
@@ -160,8 +160,8 @@ Look, +replace+ basically generates
 
 If that's not what you want, do
 
-  def write
-    if param(:comment)[:text].explicit?
+  def write(evt)
+    if evt[:comment][:text].explicit?
       render :text => 'alert("Hey, you wanted to submit a pervert comment!");'
     end
   end
@@ -210,4 +210,4 @@ If you wanna be cool, subscribe to our feed[http://feeds.feedburner.com/Apotomo]
 
 
 == License
-Copyright (c) 2007-2010 Nick Sutterer <apotonick@gmail.com> under the MIT License
+Copyright (c) 2007-2011 Nick Sutterer <apotonick@gmail.com> under the MIT License

data/apotomo.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.email       = ["apotonick@gmail.com"]
   s.homepage    = "http://github.com/apotonick/apotomo"
   s.summary     = %q{Web components for Rails.}
-  s.description = %q{Web component framework for Rails providing page widgets that trigger events and know when and how to update themselves with AJAX.}
+  s.description = %q{Web component framework for Rails providing widgets that trigger events and know when and how to update themselves with AJAX.}
   
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
@@ -20,8 +20,8 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   
   s.add_dependency "rails",   "~> 3.0"
-  s.add_dependency "cells",   "~> 3.4.0"
-  s.add_dependency "onfire",  "~> 0.1.1"
+  s.add_dependency "cells",   "~> 3.5.4"
+  s.add_dependency "onfire",  "~> 0.1.2"
   s.add_dependency "hooks",   "~> 0.1.3"
 
   s.add_development_dependency "shoulda"

data/lib/apotomo.rb

@@ -1,33 +1,8 @@
-#  Copyright (c) 2007-2010 Nick Sutterer <apotonick@gmail.com>
-#  
-#  The MIT License
-#  
-#  Permission is hereby granted, free of charge, to any person obtaining a copy
-#  of this software and associated documentation files (the "Software"), to deal
-#  in the Software without restriction, including without limitation the rights
-#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-#  copies of the Software, and to permit persons to whom the Software is
-#  furnished to do so, subject to the following conditions:
-#  
-#  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 "rails/railtie"
-require 'rails/engine'
- 
 module Apotomo
   class << self
     def js_framework=(js_framework)
       @js_framework = js_framework
-      @js_generator = ::Apotomo::JavascriptGenerator.new(js_framework)
+      @js_generator = JavascriptGenerator.new(js_framework)
     end
     
     attr_reader :js_generator, :js_framework
@@ -43,31 +18,13 @@ module Apotomo
       yield self
     end
   end
-  
-  # Piotr Sarnacki: Railtie :P
-  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 :prepend_apotomo_routes, :after => :add_routing_paths do |app|
-      app.routes_reloader.paths.unshift(File.dirname(__FILE__) + "/../config/routes.rb")
-    end
-  end 
 end
 
-
 require 'apotomo/widget'
-require 'apotomo/stateful_widget'
-require 'apotomo/container_widget'
+require 'apotomo/railtie'
 require 'apotomo/widget_shortcuts'
 require 'apotomo/rails/controller_methods'
-
-
 require 'apotomo/javascript_generator'
-Apotomo.js_framework = :jquery ### DISCUSS: move to rails.rb
+require 'apotomo/test_case' if Rails.env == "test"
 
-### FIXME: only load in test env.
-require 'apotomo/test_case' #if defined?("Rails") and Rails.env == "test"
+Apotomo.js_framework = :jquery ### DISCUSS: move to rails.rb

data/lib/apotomo/event.rb

@@ -5,5 +5,7 @@ module Apotomo
     def _dump(depth)
       raise "You're trying to serialize an instance of Apotomo::Event. Don't do that."
     end
+    
+    delegate :[], :to => :data
   end
 end

data/lib/apotomo/event_handler.rb

@@ -18,6 +18,3 @@ module Apotomo
     
   end
 end
-
-require 'apotomo/invoke_event_handler'
-require 'apotomo/proc_event_handler'

data/lib/apotomo/event_methods.rb

@@ -1,4 +1,4 @@
-require 'apotomo/event_handler'
+require 'apotomo/invoke_event_handler'
 
 module Apotomo
   # Introduces event-processing functions into the StatefulWidget.
@@ -77,7 +77,7 @@ module Apotomo
     # which can be queried in a triggered state.
     #
     #   def on_drop(event)
-    #     if event.data[:area] == 59 
+    #     if event[:area] == 59 
     def trigger(*args)
       fire(*args)
     end
@@ -87,5 +87,9 @@ module Apotomo
     def local_event_handlers(event)
       event_table.all_handlers_for(event.type, event.source.name) # we key with widget_id.
     end
+    
+    def event_for(*args)  # defined in Onfire: we want Apotomo::Event.
+      Event.new(*args)
+    end
   end
 end

data/lib/apotomo/invoke_event_handler.rb

@@ -1,10 +1,12 @@
+require 'apotomo/event_handler'
+
 module Apotomo
   class InvokeEventHandler < EventHandler
     attr_accessor :widget_id, :state
     
-    def initialize(opts={})
-      @widget_id  = opts.delete(:widget_id)
-      @state      = opts.delete(:state)
+    def initialize(options={})
+      @widget_id  = options.delete(:widget_id)
+      @state      = options.delete(:state)
     end
     
     def process_event(event)

data/lib/apotomo/javascript_generator.rb

@@ -31,27 +31,30 @@ module Apotomo
     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
+      def prototype;              end
+      def element(id);            "$(\"#{id}\")"; end
+      def update(id, markup);     element(id) + '.update("'+escape(markup)+'")'; end
+      def replace(id, markup);    element(id) + '.replace("'+escape(markup)+'")'; end
+      def update_id(id, markup);  update(id, markup); end
+      def replace_id(id, markup); replace(id, 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
+      def right;                  end
+      def element(id);            "$(\"#{id}\")"; end
+      def update(id, markup);     element(id) + '.update("'+escape(markup)+'")'; end
+      def replace(id, markup);    element(id) + '.replace("'+escape(markup)+'")'; end
+      def update_id(id, markup);  update(id, markup); end
+      def replace_id(id, markup); replace(id, 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
+      def jquery;                 end
+      def element(id);            "$(\"#{id}\")"; end
+      def update(id, markup);     element(id) + '.html("'+escape(markup)+'")'; end
+      def replace(id, markup);    element(id) + '.replaceWith("'+escape(markup)+'")'; end
+      def update_id(id, markup);  update("##{id}", markup); end
+      def replace_id(id, markup); replace("##{id}", markup); end
     end
   end
-end
+end

data/lib/apotomo/rails/controller_methods.rb

@@ -1,151 +1,104 @@
 require 'apotomo/request_processor'
-require 'apotomo/rails/view_methods'
 
-  module Apotomo
-    module Rails
-      module ControllerMethods
-        include WidgetShortcuts
-        extend ActiveSupport::Concern
-        
-        included do
-          extend WidgetShortcuts
-          
-          class_inheritable_array :has_widgets_blocks
-          self.has_widgets_blocks = []
-          
-          helper ::Apotomo::Rails::ViewMethods
-          
-          after_filter :apotomo_freeze
-        end
-        
-        module ClassMethods
-          # Yields the root widget to setup your widgets for a controller. The block is executed in 
-          # controller _instance_ context, so you may use instance methods and variables of the
-          # controller.
-          #
-          # Example:
-          #   class PostsController < ApplicationController
-          #     has_widgets do |root|
-          #       root << widget(:comments_widget, 'post-comments', :user => @current_user)
-          #     end
-          def has_widgets(&block)
-            has_widgets_blocks << block
-          end
-        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(self, session, options, self.class.has_widgets_blocks)
-          
-          flush_bound_use_widgets_blocks if @apotomo_request_processor.widgets_flushed?
-          
-          
-          @apotomo_request_processor
-        end
+module Apotomo
+  module Rails
+    # Lazy-loads Apotomo support into controllers when needed.
+    module ControllerMethodsLoader
+      def has_widgets(*args, &block)
+        include ControllerMethods
+        has_widgets(*args, &block)
+      end
+    end
+    
+    
+    module ActionViewMethods
+      delegate :render_widget, :url_for_event, :to => :controller
+    end
+    
+    module ControllerMethods
+      include WidgetShortcuts
+      extend ActiveSupport::Concern
+      
+      included do
+        extend WidgetShortcuts
         
-        def apotomo_root
-          apotomo_request_processor.root
-        end
+        class_inheritable_array :has_widgets_blocks
+        self.has_widgets_blocks = []
         
-        # 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.
+        helper ActionViewMethods
+      end
+      
+      module ClassMethods
+        # Yields the root widget to setup your widgets for a controller. The block is executed in 
+        # controller _instance_ context, so you may use instance methods and variables of the
+        # controller.
         #
         # Example:
-        #   def login
-        #     use_widgets do |root|
-        #       root << widget(:login_widget, 'login_box')
+        #   class PostsController < ApplicationController
+        #     has_widgets do |root|
+        #       root << widget(:comments_widget, 'post-comments', :user => @current_user)
         #     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, &block)
-        end
-        
-        def apotomo_freeze
-          apotomo_request_processor.freeze!
+        def has_widgets(&block)
+          has_widgets_blocks << block
         end
+      end
       
-        def render_event_response
-          page_updates = apotomo_request_processor.process_for({:type => params[:type], :source => params[:source]})
-          
-          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
+      def apotomo_request_processor
+        return @apotomo_request_processor if @apotomo_request_processor
         
-        protected
+        # happens once per request:
+        options = { :js_framework   => Apotomo.js_framework || :prototype } # FIXME: remove :prototype
         
-        def parent_controller
-          self
-        end
+        @apotomo_request_processor = Apotomo::RequestProcessor.new(self, options, self.class.has_widgets_blocks)
+      end
+      
+      def apotomo_root
+        apotomo_request_processor.root
+      end
+      
+      def render_widget(*args, &block)
+        apotomo_request_processor.render_widget_for(*args, &block)
+      end
+      
+      def render_event_response
+        page_updates = apotomo_request_processor.process_for(params)
         
+        return render_iframe_updates(page_updates) if params[:apotomo_iframe]
         
+        render :text => page_updates.join("\n"), :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
+      
+      # TODO: remove me! only needed in widget_shortcuts.
+      def parent_controller
+        self
+      end
+      
+      
+      # 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)
+        escaped_script = Apotomo::JavascriptGenerator.escape(page_updates.join("\n"))
         
-        # 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'>
+        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
-        
-      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