bowline 0.5.3 → 0.5.4

data/examples/tweet.rb

@@ -0,0 +1,35 @@
+class Tweet < Bowline::LocalModel
+  class << self
+    def poll
+      destroy_all
+      populate(timeline)
+    end
+    
+    def timeline
+      twitter.friends_timeline.collect {|t|
+        t.delete('user')
+        t.to_hash
+      }
+    end
+    
+    def update(status)
+      twitter.update(status)
+    end
+
+    private
+      def twitter
+        httpauth = Twitter::HTTPAuth.new(
+          AppConfig.username, 
+          AppConfig.password
+        )
+        Twitter::Base.new(httpauth)
+      end
+  end
+end
+
+Thread.new do
+  loop do
+    Tweet.poll
+    sleep 60
+  end
+end

data/examples/tweets_binder.rb

@@ -0,0 +1,6 @@
+class TweetsBinder < Bowline::Binders::Base
+  bind Tweet
+  def self.update(status)
+    klass.update(status)
+  end
+end

data/examples/twitter.html

@@ -6,18 +6,16 @@
   <link rel="stylesheet" href="stylesheets/application.css" type="text/css" charset="utf-8">
 	<script src="javascripts/jquery.js" type="text/javascript" charset="utf-8"></script>
 	<script src="javascripts/jquery.chain.js" type="text/javascript" charset="utf-8"></script>
-  <script src="javascripts/jquery.bowline.js" type="text/javascript" charset="utf-8"></script>
+	<script src="javascripts/json2.js" type="text/javascript" charset="utf-8"></script>
+  <script src="javascripts/bowline.js" type="text/javascript" charset="utf-8"></script>
   <script src="javascripts/application.js" type="text/javascript" charset="utf-8"></script>
   <script type="text/javascript" charset="utf-8">
     jQuery(function($){
-      $.bowline.ready(function(){
-        var tweets = $('#tweets').bowline('tweets');
-        tweets.invoke('index');
+      var tweets = $('#tweets').bindto('tweets');
 
-        $('#updateSubmit').click(function(){
-          tweets.invoke('update', $('#updateText').val());
-          return false;
-        });
+      $('#updateSubmit').click(function(){
+        tweets.invoke('update', $('#updateText').val());
+        return false;
       });
     });
   </script>

data/examples/users.rb

@@ -1,12 +1,7 @@
 module Binders
-  class Users < Bowline::Binders::Collection    
-    class << self
-      # self.items is a special method
-      # Basically it'll update users on the client side
-      def index
-        self.items = User.all
-      end
- 
+  class Users < Bowline::Binders::Base
+    bind User    
+    class << self 
       def admins
         self.items = User.admins.all
       end
@@ -14,23 +9,22 @@ module Binders
   
     def update(attrs)
       if @item.update_attributes(attrs)
-        flash[:notice] = "Successfully updated"
+        page.flash("Successfully updated").call
       else
-        flash[:notice] = "Errors updating users"
+        page.flash_error("Errors updating users").call
       end
     end
  
     def highlight
       # Calls $('user_1').highlight()
-      self.element.highlight
+      self.element.highlight.call
     end
   
-    # Overrides charge on user
     def charge!
-      # calls charge! on model (i.e. do sql commit )
+      # calls charge! on model (i.e. do SQL commit )
       self.item.charge!
       # Now gui stuff
-      flash[:notice] = "Successfully charged"
+      page.flash("Charged!")
       highlight
     end
   end

data/lib/bowline/binders.rb

@@ -1,23 +1,87 @@
 module Bowline
   module Binders
+    # Binders are a central part of Bowline. They perform two main functions:
+    #   1) Bind a model to the view, so any changes to the model get automatically
+    #      reflected in the view.
+    #   2) View abstraction of the model. You can define view specific class & instance
+    #      methods, and easily call them from bound JavaScript objects.
+    # 
+    # To use a binder, you first need to bind it to a model using the bind method.
+    # Example:
+    #   class UsersBinder < Bowline::Binders::Base
+    #     bind User
+    #   end
+    # 
+    # Once a class is bound, any updates to the model automatically update any bound HTML.
+    # The class names in the HTML are tied to the model's attribute names.
+    # You can bind HTML using the bowline.js bindup function.
+    # Example:
+    #   <div id="users">
+    #     <div class="item">
+    #       <span class="name"></span>
+    #     </div>
+    #   </div>
+    #   <script>
+    #     $("#users").bindup('UsersBinder');
+    #   </script>
+    # 
+    # =Class methods
+    # 
+    # You can define class methods on your binder, and call them using JavaScript
+    # using the invoke function on the bound HTML element.
+    # Example:
+    #   <script>
+    #     var users = $("#users").bindup('UsersBinder');
+    #     users.invoke("method_name", "arg1", "arg2")
+    #   </script>
+    # 
+    # =Instance methods
+    # 
+    # You can call your binders instance method from JavaScript by calling the invoke
+    # function on the generated HTML elements. Your binder's instance methods have access
+    # to an 'element' variable, which is the jQuery element, and a 'item' variable, which 
+    # is the bound model's instance record.
+    # 
+    # Example:
+    #   class UsersBinder < Bowline::Binders::Base
+    #     bind User
+    #     def charge!
+    #       #...
+    #     end
+    #   end
+    # 
+    #   <script>
+    #     $('#users').items(10).invoke('charge!');
+    #   </script>
+    #
+    # For more documentation on Bowline's JavaScript API, see bowline.js
     class Base
       extend Bowline::Watcher::Base
       extend Bowline::Desktop::Bridge::ClassMethods
       js_expose
       
       class << self
+        # An array of window currently bound.
         def windows
           @windows ||= []
         end
         
-        # Called by JS when first bound
-        def setup(window)
+        # Called by a window's JavaScript whenever that window is bound to this Binder.
+        # This method populates the window's HTML with all bound class' records.
+        # Override this if you don't want to send all the class' records to the window.
+        # Example:
+        #   def setup(window)
+        #     super(window, last_10_tweets)
+        #   end  
+        def setup(window, items = all)
           self.windows << window
-          self.items = all
+          window.bowline.populate(
+            name, items.to_js
+          ).call
           true
         end
         
-        def js_invoke(window, method, *args)
+        def js_invoke(window, method, *args) #:nodoc:
           if method == :setup
             setup(window)
           else
@@ -29,19 +93,28 @@ module Bowline
           self.new(id).send(meth, *args)
         end
         
+        # Calls .find on the klass sent to the bind method.
+        # This is used internally, to find records when the page
+        # invoke instance methods.
         def find(id)
           klass.find(id)
         end
-
+        
+        # Calls .all on the klass sent to the bind method.
+        # This method is called internally by the setup method.
         def all
           klass.all
         end
         
-        def items=(items) #:nodoc:
+        # Set the binder's items. This will replace all items, and update the HTML.
+        def items=(items)
           bowline.populate(name, items.to_js).call
         end
         
-        def created(item) #:nodoc:
+        # Add a new item to the binder, updating the HTML.
+        # This method is normally only called internally by 
+        # the bound class's after_create callback.
+        def created(item)
           bowline.created(
             name, 
             item.id, 
@@ -49,7 +122,10 @@ module Bowline
           ).call
         end
         
-        def updated(item) #:nodoc:
+        # Update an item on the binder, updating the HTML.
+        # This method is normally only called internally by 
+        # the bound class's after_update callback.
+        def updated(item)
           bowline.updated(
             name, 
             item.id, 
@@ -57,7 +133,10 @@ module Bowline
           ).call
         end
         
-        def removed(item) #:nodoc:
+        # Remove an item from the binder, updating the HTML.
+        # This method is normally only called internally by 
+        # the bound class's after_destroy callback.
+        def removed(item)
           bowline.removed(
             name, 
             item.id
@@ -65,41 +144,45 @@ module Bowline
         end
         
         protected
-          # Associate the binder with a model 
-          # to setup callbacks so changes to the
-          # model are automatically reflected in
-          # the view. Usage:
-          #   expose Post
+          # Associate the binder with a model to setup callbacks so 
+          # changes to the model are automatically reflected in the view.
+          # Example:
+          #   bind Post
           #
-          # When the exposed class is created/updated/deleted
+          # When the bound class is created/updated/deleted
           # the binder's callbacks are executed and the view
           # updated accordingly.
-          #  
-          # klass needs to respond to:
-          #  * all
-          #  * find(id)
-          #  * after_create(method)
-          #  * after_update(method)
-          #  * after_destroy(method)
+          # 
+          # Classes inheriting fromActiveRecord and Bowline::LocalModel are 
+          # automatically compatable, but if you're using your own custom model
+          # you need to make sure it responds to the following methods:
+          #  * all                    - return all records
+          #  * find(id)               - find record by id
+          #  * after_create(method)   - after_create callback
+          #  * after_update(method)   - after_update callback
+          #  * after_destroy(method)  - after_destroy callback
           #
-          # klass instance needs to respond to:
-          #   * id
+          # The klass' instance needs to respond to:
+          #   * id      - returns record id
+          #   * to_js   - return record's attribute hash
           #
-          # You can override .to_js on the model instance
-          # in order to return specific attributes for the view
-          def expose(klass)
+          # You can override the to_js method on the model instance
+          # in order to return specific attributes for the view.
+          def bind(klass)
             @klass = klass
             @klass.after_create(method(:created))
             @klass.after_update(method(:updated))
             @klass.after_destroy(method(:removed))
           end
           
-          # Returns class set by the 'expose' method
+          # Returns class set by the 'bind' method
           def klass
-            @klass || raise("klass not set - see expose method")
+            @klass || raise("klass not set - see bind method")
           end
           
-          # JavaScript proxy to the page:
+          # JavaScript proxy to the page. 
+          # See Bowline::Desktop::Proxy for more information.
+          # Example:
           #   page.myFunc(1,2,3).call
           def page
             Bowline::Desktop::Proxy.new(
@@ -107,14 +190,18 @@ module Bowline
             )
           end
           
-          # JavaScript proxy to the Bowline object:
+          # JavaScript proxy to the Bowline object.
+          # See Bowline::Desktop::Proxy for more information.
+          # Example:
           #   bowline.log("msg").call
           def bowline
             page.Bowline
           end
       
-          # Javascript proxy to jQuery:
-          #   jquery.getJSON("http://example.com")
+          # Javascript proxy to jQuery.
+          # See Bowline::Desktop::Proxy for more information.
+          # Example:
+          #   jquery.getJSON("http://example.com").call
           def jquery
             page.jQuery
           end
@@ -125,7 +212,8 @@ module Bowline
           end
           
           # Trigger events on all elements
-          # bound to this binder:
+          # bound to this binder.
+          # Example:
           #   trigger(:reload, {:key => :value})
           def trigger(event, data = nil)
             bowline.trigger(
@@ -152,14 +240,13 @@ module Bowline
                 name.to_s
           end
       end
-    
+      
+      # jQuery element object
       attr_reader :element
-      attr_reader :item
       
-      # Instance of an element on the view.
-      # 
-      # item.destroy
-      # element.highlight.call
+      # Instance of the bound class' record
+      attr_reader :item
+
       def initialize(id, *args) #:nodoc:
         @element = self.class.bowline.element(
                       self.class.name, id
@@ -168,7 +255,8 @@ module Bowline
       end
       
       protected
-        # Trigger jQuery events on this element:
+        # Trigger jQuery events on this element.
+        # Example:
         #   trigger(:highlight)
         def trigger(event, data = nil)
           element.trigger(
@@ -184,7 +272,7 @@ module Bowline
     
         # Shortcut methods
     
-        # See self.class.js
+        # See self.class.page
         def page
           self.class.page
         end

data/lib/bowline/dependencies/lib/dependencies.rb

@@ -1,4 +1,5 @@
-module Dependencies; end
+module Dependencies #:nodoc: all
+end
 
 Dir[File.join(File.dirname(__FILE__), 'dependencies', '*.rb')].each do |file|
   require file

data/lib/bowline/dependencies/lib/ext/rubygems.rb

@@ -22,7 +22,7 @@ Gem.pre_install_hooks.push(proc do |installer|
   end
 end)
 
-class ::Gem::Uninstaller
+class ::Gem::Uninstaller #:nodoc:
   def self._with_silent_ui
 
     ui = Gem::DefaultUserInteraction.ui
@@ -64,7 +64,7 @@ Gem.post_install_hooks.push(proc do |installer|
   )
 end)
 
-class ::Gem::DependencyInstaller
+class ::Gem::DependencyInstaller #:nodoc:
   alias old_fg find_gems_with_sources
 
   def find_gems_with_sources(dep)
@@ -78,7 +78,7 @@ class ::Gem::DependencyInstaller
   end
 end
 
-class ::Gem::SpecFetcher
+class ::Gem::SpecFetcher #:nodoc:
   alias old_fetch fetch
   def fetch(*args) # in rubygems 1.3.2 fetch takes 4 parameters
     dependency, all, matching_platform, prerelease = *args
@@ -102,7 +102,7 @@ class ::Gem::SpecFetcher
   end
 end
 
-class ::Gem::Specification
+class ::Gem::Specification #:nodoc:
   def recursive_dependencies(from, index = Gem.source_index)
     specs = self.runtime_dependencies.map do |dep|
       spec = index.search(dep).last

data/lib/bowline/desktop.rb

@@ -4,19 +4,28 @@ module Bowline
     extend Bowline::Watcher::Base
     watch :on_tick, :on_idle
     
+    ##
+    # :singleton-method: on_tick(method = nil, &block)
+    # A Watcher event method that gets called every few microseconds,
+    # inside the application's main thread.
+    # Example:
+    #   on_tick { puts "App tick" }
+    
+    # Return true if we're currently 
+    # being executed by bowline-desktop.
     def enabled?
       $0 == "bowline"
     end
     module_function :enabled?
     
-    def idle
+    def idle #:nodoc:
       watcher.call(:on_idle)
     rescue => e
       log_error e
     end
     module_function :idle
 
-    def tick
+    def tick #:nodoc:
       watcher.call(:on_tick)
     rescue => e
       log_error e