bowline 0.5.3 → 0.5.4

data/.gitignore

@@ -1 +1,2 @@
 pkg
+rdoc

data/README.txt

@@ -4,7 +4,7 @@ http://github.com/maccman/bowline
   
 = DESCRIPTION
 
-Ruby desktop application framework
+Ruby, HTML and JS desktop application framework.
 
 = FEATURES
 
@@ -12,7 +12,7 @@ Ruby desktop application framework
 * Uses Webkit
 * View in HTML/JavaScript
 * Binding between HTML & Ruby
-* Cross platform (only osx atm)
+* Cross platform (only osx atm ;)
 
 = INTRODUCTION
 
@@ -39,13 +39,22 @@ info@eribium.org
 http://eribium.org
 http://twitter.com/maccman
 
-= INSTALLATION
+= COMMUNITY
+
+http://groups.google.com/group/bowline-dev
+
+= REQUIREMENTS
 
-Install the Titanium SDK:
-  http://www.appcelerator.com/products/download-titanium/download/
+- Mac OSX (both Leopard & Snow Leopard)
+- Ruby 1.9 (Ruby 1.8.6 is supported, but we recommend you use 1.9 since that's the version your application will be using when it's run).
+- Bowline gem
+
+The other required libraries, such as bowline-desktop, are downloaded later by Bowline - you don't need to worry about these.
+
+= INSTALLATION
 
 Install the gem:
->> sudo gem install maccman-bowline --source http://gems.github.com
+>> sudo gem install bowline
 
 = USAGE
 
@@ -56,11 +65,12 @@ or browse the completed version here:
 = GENERATING
 
 Using the bowline-gen binary (installed with Bowline) you can generate the following things:
-  app                              Generates a new application.
-  binder                           Generates a new binder, either a collection one, or a singleton one.
-  helper                           Generates a new helper.
-  migration                        Generates a new database migration.
-  model                            Generates a new model.
+  app       
+  binder    
+  helper    
+  migration 
+  model     
+  window
   
 Run 'bowline-gen --help' for more information.
 
@@ -72,30 +82,24 @@ App console:
 Run application:
 >> script/run
 
-= BINDERS
-
-Binders are the core of Bowline, they're classes that you can bind HTML to.
-Binders contain data. If you modify the binder's data the HTML automatically updates.
-It's a one way relationship though.
+Build package for distribution:
+>> script/build
 
-You can think of binders as similar to controllers in Rails.
+= BINDERS
 
-There are two types of binders, singleton and collection.
-Singleton binders are for a single data entity, such as the current logged in user.
-And it goes without saying that collection binders are for an array of data.
+Binders are the core of Bowline. They're a model abstraction for the view which you can bind HTML to.
+Binders in turn are associated with a Model. When the model gets changed, the binder makes sure that the HTML stays in sync.
 
-You can create a collection binder like this:
->> bowline-gen binder users --type collection
+You can create a binder like this:
+>> bowline-gen binder users
 
 Which will generate code a bit like this:
-  module Binders
-    class Users < Bowline::Collection
-    end
+  class UsersBinder < Bowline::Binders::Base
   end
 
 Now, in the view you can bind HTML to this collection, by
 using the following javascript:
-  $('#users').bowline('users');
+  $('#users').bindto('users');
   
 You should probably become familiar with Chain.js (which bowline uses for binding): http://wiki.github.com/raid-ox/chain.js/
 
@@ -111,7 +115,7 @@ Suffice to say, the HTML looks a bit like this:
 Now, were you to have a user object, you could do something like
 this to update the HTML.
 
-Binders::Users.items = [User.first]
+# TODO
 
 = METHODS IN BINDERS
 
@@ -124,7 +128,7 @@ $('#users').invoke('admins')
 It's the same syntax for invoking instance methods, just called
 on one of the individual users:
 
-$('#users div:first').invoke('instance_method', 'arg1')
+$('#users div:first').invoke('instance_meth', 'arg1')
 
 = HELPERS
 
@@ -136,55 +140,53 @@ $.bowline.helper('name', 'arg1', ['arg2'])
 
 = MODELS
 
-Bowline supports ActiveRecord and the Sqlite3 database.
-The packaging for databases is still in development though.
+Bowline supports ActiveRecord and the Sqlite3 database. 
+The packaging for distributing databases is still in development though.
+Bowline also has a LocalModel class for models held in memory.
 
-= THEMES
+= WINDOWS
 
-The Cappuccino Aristo theme has been specially customized for Bowline, you can see
-examples of it in the Twitter client, and find it here:
-  http://github.com/maccman/aristo
+Bowline lets you control your application's windows. The API is under Bowline::Desktop::Window. 
+There's a generator for creating new windows; they live under app/windows. 
+Every window lives under the MainWindow class. If the MainWindow is closed, the app exits.
   
-= TITANIUM
+= BOWLINE-DESKTOP
 
-Bowline is built on top of Titanium, an open source cross platform framework for desktop apps.
-You can use any of the Titanium api methods in Ruby and JavaScript, like this:
-  Titanium.UI.currentWindow.close
+Bowline-desktop is an abstraction upon wxWidgets for Bowline. It gives your app access to numerous APIs & system features, such as the Clipboard, Dock, Speakers and Windows.
 
-Site: http://www.appcelerator.com/products/titanium-desktop/
-API Docs: http://www.codestrong.com/titanium/api/
+The binary is built in C++, and statically linked with Ruby 1.9 and wxWidgets so it has no local dependencies. Compiling it isn't a requirement to use Bowline, but if you want to extend or contribute to Bowline-desktop, you can find it here:
+http://github.com/maccman/bowline-desktop
 
-= BUILDING
+= DISTRIBUTING
 
-Once your app is complete, you should run the following command
-to make sure all the gems required (including Bowline) have been vendorised:
+Once your app is ready for a release, you should run the following command to make sure all the gems required have been vendorised:
   rake gems:sync
 
 Then, run:
-  rake app
+  ./script/build
 
-You can only build distributions for your local platform, but
-using the Titanium Developer app you can build on all three platforms.
+You can only build distributions for your local platform at the moment, but we're planning to extend this.
+
+= THEMES
+
+The Cappuccino Aristo theme has been specially customized for Bowline, you can see
+examples of it in the Twitter client, and find it here:
+  http://github.com/maccman/aristo
 
 = EXAMPLES
 
 Usage for a collection (of users):
 
-  module Binders
-    class Users < Bowline::Collection
+    class Users < Bowline::Binders::Base
+      bind User
       # These are class methods
       # i.e. methods that appear on
       # users, rather an user
       class << self
-        def index
-          # self.items is a magic variable - 
-          # it'll update the html binders
-          self.items = User.all
-        end
-    
         def admins
           # This just replaces all the listed
           # users with just admins
+          # TODO
           self.items = User.admins.all
         end
       end
@@ -201,7 +203,7 @@ Usage for a collection (of users):
       # an ActiveRecord instance
       # 
       # self.page gives you access to the dom, e.g:
-      #  self.page.alert('hello world')
+      #  self.page.alert('hello world').call
   
       def destroy
         self.item.destroy
@@ -220,7 +222,7 @@ Usage for a collection (of users):
   		jQuery(function($){
   		  $.bowline.ready(function(){
           // Bind the element users to UserBinder
-      	  var users = $('#users').bowline('users', function(){
+      	  var users = $('#users').bindto('users', function(){
       	    var self = $(this);
       	    self.find('.destroy').click(function(){
       	      self.invoke('destroy');
@@ -257,19 +259,17 @@ Usage for a collection (of users):
 
 = Building a basic Twitter client
 
-  Install the Titanium SDK:
-  http://www.appcelerator.com/products/download-titanium/download/
-
   Install the gem:
-  >> sudo gem install maccman-bowline --source http://gems.github.com
+  >> sudo gem install bowline
 
   Run the app/binder generators:
   >> bowline-gen app bowline_twitter
   >> cd bowline_twitter
   >> bowline-gen binder tweets
 
-  Copy tweets.rb from examples to app/binders/tweets.rb
-  Add your Twitter credentials to tweets.rb - in this simple example they're not dynamic.
+  Copy tweets_binder.rb from examples to app/binders/tweets_binder.rb
+  Copy tweet.rb from examples to app/models/tweet.rb
+  Add your Twitter credentials to config/application.yml - in this simple example they're not dynamic.
 
   Copy twitter.html from examples to public/index.html
 

data/Rakefile

@@ -18,4 +18,14 @@ end
 task :write_version do 
   require File.join(File.dirname(__FILE__), *%w[lib bowline])
   File.open('VERSION', 'w') {|f| f.write Bowline::Version::STRING }
+end
+
+require 'rake/rdoctask'
+desc "Generate documentation for Bowline."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "Bowline"
+  rdoc.options << "--line-numbers" << "--inline-source"
+  rdoc.rdoc_files.include("README.txt")
+  rdoc.rdoc_files.include("lib/**/*.rb")
 end

data/TODO

@@ -8,4 +8,6 @@ Investigate thread safety
 
 Load all required JS through Bowline (so you only have to require one JS file)
 
-Add --version to bowline-gen
+Add --version to bowline-gen
+
+Update bowline-twitter

data/VERSION

@@ -1 +1 @@
-0.5.3
+0.5.4

data/assets/bowline.js

@@ -1,3 +1,118 @@
+/*
+  Bowline JavaScript API
+  
+  This library lets you call Ruby methods, and bind up elements.
+  It requires jQuery, Chain.js and json2:
+    http://jquery.com
+    http://github.com/raid-ox/chain.js
+    http://www.JSON.org/json2.js
+  
+  = Functions
+  
+  invoke(klass, method, *args)
+    Invoke a class method on a particular class. Usually
+    used to invoke methods on a binder. The class needs to
+    be exposed to JS (using the Bowline::Desktop::Bridge#js_expose).
+    Usage: 
+      Bowline.invoke('MyClass', 'my_method');
+  
+  instanceInvoke(klass, id, method, *args)
+    Invoke an instance method an a binder.
+    Usually called via the jQuery helper functions.
+    Usage: 
+      Bowline.instanceInvoke('UsersBinder', 1, 'charge!');
+    
+  windowInvoke(method, *args)
+    Invoke class method on this window's class.
+    Usage:
+      Bowline.windowInvoke('close');
+    
+  helper(method, *args)
+    Invoke a method defined in any helper.
+    
+  bindto(element, klass, options = {})
+    Bind a element to a Bowline binder. 
+    Usually called via the jQuery helper functions.
+    Usage:
+      Bowline.bindto('#users', 'UsersBinder');
+    
+    The options can either be a template hash:
+        {
+      		'.name .first': {
+      			style: 'color: blue;',
+      			content: 'First Name: {first}'
+      		},
+      		'.name .last': 'Family Name: {last}',
+      		'.address': function(data, el){
+      			if(!data.address)
+      				el.hide();
+      			return data.address;
+      		},
+      		builder: function(){
+      			var data = this.item();
+      			this.find('.name').click(function(){alert(data.name)});
+      		}
+      	}
+      	
+    Or the options can be a builder function:    	
+      	(function(){
+          this.bind('click', function(){
+        	var data = this.item();
+        	alert(data);
+        })
+        
+    For more documentation, look at the Chain.js library:
+      http://wiki.github.com/raid-ox/chain.js/elementchain
+      
+  = Filtering items
+  
+    $('#users').items('filter', 'value');
+  
+  = Sorting items
+    
+    $('#users').items('sort', 'first_name');
+  
+  = Update events
+  
+    $('#users').update(function(){
+      //...
+    });
+  
+  = JQuery functions
+  
+  These are how you usually bind elements, or invoke a binders class/instance methods.
+  
+  $.fn.bindto(klass, options)
+    Associate an an element with a Bowline binder.
+    Example:
+      $("#users").bindto('UsersBinder');
+  
+  $.fn.invoke(method, *args)
+    Invoke a class/instance method on a Bowline binder. 
+    
+    If called on the bound element, in this example the #users div, then a class method 
+    will be called on the binder.
+    Example:
+      $("#users").invoke("my_class_method", "arg1");
+            
+    If called on a item inside a bound element, an instance method will be called.
+    Example:
+      $("#users").items(10).invoke("my_instance_method");
+      
+  = Debugging
+  
+  Turn on Bowline.trace to show debugging information:
+    Bowline.trace = true
+  
+  = Using other libraries (e.g. Prototype)
+  
+  Although this library requires jQuery, its API is not jQuery
+  specific. It's perfectly feasible to rewrite to use Prototype instead.
+  Additionally, jQuery plays nicely with other libraries using it's noConflict() method. 
+  So you're still free to use other JavaScript libraries without fear of conflicts.
+
+*/
+
 var Bowline = {
   msgs: [],
   callbacks: {},
@@ -54,7 +169,7 @@ var Bowline = {
     Bowline.invoke(args);
   },
   
-  bind: function(el, klass, options){
+  bindto: function(el, klass, options){
     el = jQuery(el);
     el.chain(options);
     el.data('bowline', klass);
@@ -182,10 +297,10 @@ var Bowline = {
     }
   };
   
-  $.fn.bowline = function(){
+  $.fn.bindto = function(){
     var args = $.makeArray(arguments);
     args.unshift(this);
-    Bowline.bind.apply(this, args);
+    Bowline.bindto.apply(this, args);
   };
 })(jQuery);
 

data/bowline.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{bowline}
-  s.version = "0.5.3"
+  s.version = "0.5.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex MacCaw"]
-  s.date = %q{2009-12-20}
+  s.date = %q{2009-12-22}
   s.default_executable = %q{bowline-gen}
   s.description = %q{Ruby/JS GUI framework}
   s.email = %q{alex@leadthinking.com}
@@ -35,9 +35,9 @@ Gem::Specification.new do |s|
      "assets/osx/makeicns",
      "bin/bowline-gen",
      "bowline.gemspec",
-     "examples/account.rb",
      "examples/example.js",
-     "examples/tweets.rb",
+     "examples/tweet.rb",
+     "examples/tweets_binder.rb",
      "examples/twitter.html",
      "examples/users.rb",
      "lib/bowline.rb",
@@ -125,8 +125,8 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.5}
   s.summary = %q{Bowline GUI framework}
   s.test_files = [
-    "examples/account.rb",
-     "examples/tweets.rb",
+    "examples/tweet.rb",
+     "examples/tweets_binder.rb",
      "examples/users.rb"
   ]
 

data/examples/example.js

@@ -1,11 +1,4 @@
-$('#users').bowline('users_binder');
-
-var user = $('#users').items(10);
-user.update({name: 'Alex'}); // will automatiinvokey 
-user.item().errors //=> []
-
-// Deletes item from DOM too
-item.destroy()
+$('#users').bindto('UsersBinder');
 
 // invoke collection method
 // This will invoke UserBinder.admins and fill #users with admins
@@ -15,10 +8,4 @@ $('#users').invoke('admins');
 $('#users').items(10).invoke('charge!');
 
 // invoke charge! on every user
-$('#users').items().invoke('charge!')
-
-// // For binding over a http connection - an async invoke
-// // last argument is a function
-// $('#users').items(10).invoke('charge!', function(){
-//   
-// })
+$('#users').items().invoke('charge!')