apotomo 1.0.0.beta1 → 1.0.0.beta2

data/Gemfile

@@ -1,7 +1,7 @@
 source "http://rubygems.org"
 
 gem "rails", "~> 3.0.0"
-gem "cells", :path => "/home/nick/projects/cells"#"3.4.1"
+gem "cells", "~> 3.4"
 gem "onfire"
 gem "hooks", "~> 0.1.2"
 

data/README.rdoc

@@ -1,141 +1,195 @@
-how does Apotomo handle Ajax and JavaScript?
-framework abstraction with JavascriptGenerator
+= Apotomo
 
-no manual AJAX-routes for dozens of controllers, one generic route to rule them all
+<em>Web Components for Rails.</em>
 
-= Apotomo
+== Overview
 
-Apotomo is a stateful widget component framework for Rails.
+Do you need an <b>interactive user interface</b> for your Rails application? A cool Rich Client Application with dashboards, portlets and AJAX, Drag&Drop and jQuery?
 
-It is good for you if you
-It is perfect for building AJAXed Rich Client Applications.
-It is suitable for iGoogle-like widgets, dashboards, portals, or even full-blown interactive web apps.
-* Development Teams, where separate teams can work on separate components
+Is your controller gettin' fat? And your partial-helper-AJAX pile is getting out of control?
 
-== Widgets
+Do you want a framework to make the implementation easier? <b>You want Apotomo.</b> 
 
-=== Widget Trees
+== Apotomo
 
+Apotomo is based on {Cells}[http://github.com/apotonick/cells], the popular View Components framework for Rails.
 
-== Events
+It gives you widgets and encapsulation, bubbling events, AJAX page updates, rock-solid testing and more. Check out http://apotomo.de for a bunch of tutorials and a nice web 2.0 logo.
 
-=== Event Handlers
+== Installation
 
-== AJAX
+Easy as hell.
 
-== Statefulness vs. Stateless
+=== Rails 3
 
+  gem install apotomo
 
+=== Rails 2.3
 
-A stateful WHAT?
+  gem install apotomo -v 0.1.4
 
-Well, you know that. In Rails, people tend to have fat controllers. One controller action renders the complete page. While many programmers try to separate their code into helpers, controller actions, RJS logic and partials, it is still the controller that has to care about when to update what, and how!
+Don't forget to load the gem in your app, either in your +Gemfile+ or +environment.rb+.
 
+== Example!
 
-In Apotomo, it is the opposite. Widgets are small, autonomous components that look and feel like controllers. These tiny monsters listen to events and thus keep updating themselves on the page via AJAX. However, there's no JavaScript for you - they're pure Ruby.
+A _shitty_ example is worse a _shitty_ framework, so let's choose wisely...
 
+Say you had a blog application. The page showing the post should have a comments block, with a list of comments and a form to post a new comment. Submitting should validate and send back the updated comments list, via AJAX.
 
-== Man, gimme code!
+Let's wrap that comments block in a widget.
 
-Let's use the famous and tiresome counter example.
+== Generate
 
- class CounterCell < Apotomo::StatefulWidget
-   transition :from => :display, :to => :increment
-   
-   def display
-     respond_to_event :counterClick, :with => :increment
-  	  
-     @count = 0
-     render		# renders display.html.erb
-   end
+Go and generate a widget stub.
 
-   def increment
-     @count += 1	# @count is simply there - that's stateful.
-     render :view => :display
-   end
- end
-  
-Since this widget calls <tt>render</tt> it surely needs a view.
+  $ rails generate apotomo:widget CommentsWidget display process --haml
+    create  app/cells/
+    create  app/cells/comments_widget
+    create  app/cells/comments_widget.rb
+    create  app/cells/comments_widget/display.html.haml
+    create  app/cells/comments_widget/process.html.haml
+    create  test/widgets/comments_widget_test.rb
+
+Nothing special.
+
+== Plug it in
+
+You now tell your controller about the new widget.
+
+  class PostsController < ApplicationController
+    include Apotomo::Rails::ControllerMethods
+    
+    has_widgets do |root|
+      root << widget('comments_widget', 'post-comments', :display, :post => post)
+    end
+
+The widget is named <tt>post-comments</tt> and jumps to the <tt>:display</tt> state per default. Assuming your controller has a method +post+ we pass the current post into the widget.
+
+== Render the widget
 
- <!-- I'm display.html.erb -->
+Rendering usually happens in your controller view, <tt>views/posts/show.haml</tt>, for instance.
+
+  %h1 @post.title
+  
+  %p
+    @post.body
   
- <h1><%= @count %></h1>
- 
- <%= link_to_event "Increment me!", :counterClick %>
+  %p
+    = render_widget 'post-comments'
 
+== Write the widget
 
-We now plug the widget in a page.
+A widget is like a cell which is like a mini-controller.
 
- class ExistingController < ApplicationController
-   include Apotomo::ControllerHelper
+  class CommentsWidget < Apotomo::Widget
+    responds_to_event :submit, :with => :process
+    
+    def display
+      @comments = param(:post).comments # the parameter from outside.
+      render
+    end
 
-   def some_action
-     # do what you want...
-     
-     use_widgets do |root|
-       root << cell(:counter, :display, 'my_first_counter')
-     end
-   end
- end
+The +display+ state collects comments to show and renders its view.
 
-As soon as the widget is rendered it will jump to its <tt>:display</tt> state which initializes the counter and renders itself.
+And look at line 2 - if encountering a <tt>:submit</tt> event we invoke +process+, which is simply another state. How cool is that? 
 
-Speaking of rendering: how do we place the widget in our controller?
+    def process
+      @comment = Comment.new(:post => param(:post))
+      @comment.update_attributes param(:comment)  # like params[].
+      
+      update :state => :display
+    end
+  end
 
-  <!-- I'm some_action.html.erb -->
-  <p>
-  	<%= render_widget 'my_first_counter' %>
 
-Ok, so this renders the widget in our controller page.
+The event is processes with three steps in our widget:
 
-When clicking the link it updates automatically on the screen showing the incremented value. Wow.
+* create the new comment
+* re-render the +display+ state
+* update itself on the page.
 
+Apotomo helps you focusing on your app and takes away the pain of <b>action dispatching</b> and <b>page updating</b>.
 
-== That's cool!
-Yes, it is.
+== Triggering events
 
-== Is there more?
-Apotomo got a load of features.
+So how and where is the <tt>:submit</tt> event triggered?
 
-[Composability]     Widgets can range from small standalone components to nested widget trees like dashboards or forms. Remember that each widget can have any number of children.
+Take a look at the widget's view <tt>display.html.haml</tt>.
+  = widget_div do
+    %ul
+      - for c in @comments
+        %li c.text
+    
+    - form_for :comment, @comment, :html => {"data-event-url" => url_for_event(:submit)} do |f|
+      = f.error_messages
+      = f.text_field :text
   
-[Bubbling events]   Widgets can trigger events and watch out for them. While events bubble up from their triggering source to root they can be observed, providing a way to implement loosely coupled, distributable components.
-  
-[Deep Linking]      Apotomo deals with deep links (or url fragments) out-of-the-box while using SWFAddress. Components that register for deep linking will update as soon as the deep link changes. That makes your application back-button-safe!
+      = submit_tag "Don't be shy, comment!"
+
+That's a lot of familiar view code, almost looks like a _partial_.
+
+The view also contains a bit of JavaScript.
+
+  :javascript
+    var form = $("##{widget_id} form");
   
-[Testing]           Needless to say that it is simply easier to test small components instead of fat do-it-all controllers.
+    form.submit(function() {
+      $.ajax({url: form.attr("data-event-url"), data: form.serialize()})
+      return false;
+    });
 
+Triggering happens by sending an AJAX request to an address that the Apotomo helper +url_for_event+ generated for us.
 
-Give it a try- you will love the power and simplicity of real stateful components!
+== Event processing
 
+Now what happens when the event request is sent? Apotomo - again - does three things for you, it
 
-== Bugs, Community
-Please visit http://apotomo.de, the official project page with <em>lots</em> of examples.
-Join the mailing list and visit us in the IRC channel. More information is
-here[http://apotomo.de/download].
+* <b>accepts the request</b> on a special event route it adds to your app
+* <b>triggers the event</b> in your ruby widget tree, which will invoke the +#process+ state in our comment widget
+* <b>sends back</b> the page updates your widgets rendered
 
+== JavaScript Agnosticism
+
+In this example, we use jQuery for triggering. We could  also use Prototype, RightJS, YUI, or a self-baked framework, that's up to you.
+
+Also, updating the page is in your hands. Where Apotomo provides handy helpers as +#replace+, you could also <b>emit your own JavaScript</b>.
+
+Look, +replace+ basically generates
+
+  $("post-comments").replaceWith(<the rendered view>);
+
+If that's not what you want, do
+
+  def process
+    if param(:comment)[:text].explicit?
+      render :text => 'alert("Hey, you wanted to submit a pervert comment!");'
+    end
+  end
+
+Apotomo doesn't depend on _any_ JS framework - you choose!
 
-== License
-Copyright (c) 2007-2010 Nick Sutterer <apotonick@gmail.com>
 
-The MIT License
+== More features
 
-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:
+There's even more, too much for a simple README.
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+[Statefulness]      Deriving your widget from +StatefulWidget+ gives you free statefulness.
+[Composability]     Widgets can range from small standalone components to nested widget trees like complex dashboards.
+[Bubbling events]   Events bubble up from their triggering source to root and thus can be observed, providing a way to implement loosely coupled, distributable components.
+[Testing]           Apotomo comes with testing assertions to build rock-solid web components.
+[Team-friendly]     Widgets encourage encapsulation and help having different developers working on different components without getting out of bounds.
 
-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.
 
+Give it a try- you will love the power and simplicity of real web components!
 
+
+== Bugs, Community
+Please visit http://apotomo.de, the official project page with <em>lots</em> of examples.
+
+If you have questions, visit us in the IRC channel #cells at irc.freenode.org.
+
+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

data/Rakefile

@@ -30,7 +30,8 @@ Jeweler::Tasks.new do |spec|
   spec.authors      = ["Nick Sutterer"]
   spec.email        = "apotonick@gmail.com"
 
-  spec.files = FileList["[A-Z]*", File.join(*%w[{generators,lib,rails,app,config} ** *]).to_s]
+  spec.files        = FileList["[A-Z]*", "lib/**/*", "config/*"] - ["Gemfile.lock"]
+  spec.test_files   = FileList["test/**/*"] - FileList["test/dummy/tmp", "test/dummy/tmp/**/*", "test/dummy/log/*"]
   
   spec.add_dependency 'cells', '~> 3.4.2'
   spec.add_dependency 'rails', '>= 3.0.0'

data/lib/apotomo.rb

@@ -46,12 +46,10 @@ module Apotomo
 end
 
 require 'apotomo/javascript_generator'
-Apotomo.js_framework = :prototype ### DISCUSS: move to rails.rb
+Apotomo.js_framework = :jquery ### DISCUSS: move to rails.rb
 
 require 'apotomo/widget'
 require 'apotomo/stateful_widget'
 require 'apotomo/container_widget'
 require 'apotomo/widget_shortcuts'
 require 'apotomo/rails/controller_methods'
-
-#require 'apotomo/engine' if defined?(Rails)

data/lib/apotomo/rails/controller_methods.rb

@@ -21,6 +21,15 @@ require 'apotomo/rails/view_methods'
         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
@@ -63,7 +72,7 @@ require 'apotomo/rails/view_methods'
         # Example:
         #   def login
         #     use_widgets do |root|
-        #       root << cell(:login, :form, 'login_box')
+        #       root << widget(:login_widget, 'login_box')
         #     end
         #
         #     @box = render_widget 'login_box'
@@ -111,6 +120,11 @@ require 'apotomo/rails/view_methods'
         
         protected
         
+        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 .
@@ -158,4 +172,4 @@ with(window.parent) { setTimeout(function() { window.eval('#{escaped_script}');
       end
     end
   end
-end
+end

data/lib/apotomo/request_processor.rb

@@ -22,14 +22,7 @@ module Apotomo
     end
     
     def attach_stateless_blocks_for(blocks, root, controller)
-      blocks.each do |blk|
-        if blk.arity == 1
-          #blk.call(root) and next # fixes misbehaviour in ruby 1.8.
-          root.instance_exec(root, &blk) and next
-        end
-        ### FIXME: use Widget.has_widgets func.
-        root.instance_exec(root, controller, &blk)  
-      end
+      blocks.each { |blk| controller.instance_exec(root, &blk) }
     end
     
     def flushed_root

data/lib/apotomo/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module Apotomo
-  VERSION = '1.0.0.beta1'
+  VERSION = '1.0.0.beta2'
 end

data/lib/apotomo/widget.rb

@@ -70,6 +70,8 @@ module Apotomo
       
       @cell         = self  ### DISCUSS: needed?
       
+      @params       = parent_controller.params.dup.merge(opts)
+      
       run_hook(:after_initialize, id, start_state, opts)
     end
     
@@ -88,7 +90,7 @@ module Apotomo
     end
     
     def unfreezable_ivars
-      [:@childrenHash, :@children, :@parent, :@parent_controller, :@_request, :@_config, :@cell, :@invoke_block, :@rendered_children, :@page_updates, :@opts,
+      [:@childrenHash, :@children, :@parent, :@parent_controller, :@_request, :@_config, :@cell, :@invoke_block, :@rendered_children, :@page_updates, :@opts, :@params,
       :@suppress_javascript ### FIXME: implement with ActiveHelper and :locals.
       
       ]
@@ -250,7 +252,7 @@ module Apotomo
     
     ### DISCUSS: use #param only for accessing request data.
     def param(name)
-      params[name]
+      @params[name]
     end
     
     

data/lib/apotomo/widget_shortcuts.rb

@@ -1,17 +1,30 @@
 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.
+    # Shortcut for creating an instance of +class_name+ named +id+.
+    # If +start_state+ is omited, :display is default. Yields self.
+    #
     # Example:
-    #   widget(:form, 'uploads', :build_form) do |form|
-    #     form << widget(:upload_field)
     # 
+    #   widget(:comments_widget, 'post-comments')
+    #   widget(:comments_widget, 'post-comments', :user => @current_user)
+    #
+    # Start state is <tt>:display</tt>, whereas the latter also populates @opts.
+    #
+    #   widget(:comments_widget, 'post-comments', :reload)
+    #   widget(:comments_widget, 'post-comments', :reload, :user => @current_user)
+    #
+    # Explicitely sets the start state.
+    #
     # You can also use namespaces.
     #
     #   widget('jquery/tabs', 'panel')
     def widget(class_name, id, state=:display, *args)
+      if state.kind_of?(Hash)
+        args << state
+        state = :display
+      end
+      
       object = constant_for(class_name).new(parent_controller, id, state, *args)
       yield object if block_given?
       object