darwinjs-rails 1.0.1 → 1.1

data/README.md

@@ -26,7 +26,11 @@ Or install it yourself as:
 First, as one time configuration, add autoloader in your
 application.coffee file :
 
-```
+```coffee
+#= require 'darwin'
+#= require_tree ./views
+#= require_tree ./controllers
+
 $(->
   Darwin.Loader.run()
 )
@@ -69,7 +73,7 @@ A module is composed of two files :
 Here is a typical view :
 
 ```coffee
-class App.Views.Users.Index extends Darwin.Controller
+class App.Views.Users.Index extends Darwin.View
   @options {
     selectors:
       show_users: 'a#show_users'
@@ -117,7 +121,7 @@ class App.Controllers.Users.Index extends Darwin.Controller
 ```
 
 As you see, a view acts as single point of configuration for selectors.
-Any change needed then reflect to the whole javascript codebase.
+Any change made then reflect to the whole javascript codebase.
 
 In the same way, controller acts as a single point of configuration
 for events. You can tell what a module does looking at the first
@@ -136,6 +140,116 @@ notice something got wrong.
 
 Ready for more ? See [introduction](doc/introduction.md).
 
+
+## Philosophy
+
+If I had to choose a catchphrase for darwin, it probably would be :
+
+    Darwin knows client side isn't server side.
+
+
+### You don't execute any code
+
+There is something very cool with server generated pages : if it works for
+you, it works for everyone. If something goes wrong, you probably receive
+mail about the exception (you do, right ?). We have all of this for free,
+because there is a single or a small set of machines doing the work.
+
+Now, consider who is doing the work with a javascript codebase. It's your
+visitors. That's really cool : charge on server is lowered and you don't
+need to wait for the network to do stuff.
+
+But you have as much execution environments as you have visitors. We could
+even say you have as much execution environments as you have visits, because
+you can't expect your visitor to have a stable and coherent environment.
+What's the state of memory usage of your visitor ? Is his bandwith saturated
+by multiple parallel downloads ? What extensions his browser is running ?
+
+And now, the true question : what happens to your page when an error occurs ?
+
+Links having "#" as href are a plea : if your javascript crashed, they will
+simply do nothing. Think of what people do when they click a link that does
+nothing. If you're a developer, you probably will instinctively reload the
+page. If you're a lambda user, you probably get frustrated, yell "it doesn't
+work !" and go somewhere else. How do we solve that ?
+
+Darwin suggest that we do so through progessive enhancement and graceful
+degradation. Your application should work perfectly without javascript. When
+javascript runs, it enhances your interface to add all its cool features.
+If something wrong occurs, interface is reverted back to its initial state,
+and event callbacks are deactivated, so that feature works again and
+promises made to user are fullfilled. I call that server side fallback.
+
+
+### Your js application is an interactive presenter
+
+On server side, we like to think about our application as a collection of
+resources. Resources on the lower level are mapped to database tables.
+Then we have model that abstracts operations on table data. Then we have
+controllers that map requests on resources. And finally, we have views
+that handles presenting our UI.
+
+Should we use this same approach for client side ? In a previous version,
+darwin did have a Model class. This turned out to be unintuitive and globally
+useless : most operations on data (computation, translations, etc) are
+already done by the server side. The model class was only called by
+controllers to fire requests and then immediately pass data as callback.
+Well, `$.getJSON` and `$.post` handle that pretty well. And since you conceived
+your application through progressive enhancement and graceful degration,
+chances are there's a form somewhere containing all the data and ready to
+be serialized when lot of "model" data have to be saved.
+
+But anyway, this does even not makes sense. Your server side app is built
+around a database. Your client side app is built around html data. It's
+a presenter that handles user feedback.
+
+What we really need is a layer that handles DOM manipulation, and a layer
+that handles interruptions (events and requests). They are the view layer
+and the controller layer.
+
+A view handles DOM manipulation. It abstracts selectors so that if anything
+change in your HTML, you won't have to change it all over your codebase,
+but just in one place. This acts as a single point of configuration for
+retrieving DOM elements. In a view, you add all methods that do
+special DOM manipulation, and especialy the setup (progressive enhancement)
+and tear down (graceful degradation) code.
+
+A controller handles events and requests. A configuration method is
+used at the top of controller with descriptive comment keys, so that
+you can see at a glance what controller does. Callback names are infered
+from event descriptions, and they are all deactivated if a crash occurs.
+
+Thus, view handles the presenter part, and controller handles interactivity.
+
+
+### You may have several features on a page
+
+Again, on server side, we love to think of application in terms of resources.
+But on client side, it's difficult to stick to that pattern : we often
+use a composition of resources to provide a feature. You may have a list
+of users who you want to be able to create / edit / update / delete and
+you can stick to single resource feature. But you may also want to display
+a list of customer - a special kind of user - and to display for each their
+last purchases. Now, you also want to do nifty javascript stuff on those
+purchases, which are an other resource.
+
+Instead of having a big javascript controller that handles things pretty
+unrelated, darwin let you decompose a page in features with modules.
+
+A module is a controller and a view bound to a subset of your html page.
+The root element acts as a sandbox for your module : controller and view
+can't access anything outside it. So you can have a module on the whole
+page if it's a single feature page, or you can sandbox your module to a
+given part of the DOM and have multiple modules, you can even have a
+module sandboxed to a part of the DOM which is contained in the root element
+of an other module. This ensures your modules respect single responsibility
+principle.
+
+And of course, modules are able to communicate with each other if needed,
+through class events : any controller or view can fire and bind events,
+just like you would do with a DOM element.
+
+
 ## Contributing
 
 1. Fork it

data/app/assets/javascripts/darwin/controller.coffee

@@ -56,7 +56,10 @@ class Darwin.Controller extends Darwin.Base
 
             $target = $target.parents( sel ).first() unless $target.is( sel )
 
-          callback( $target, event )
+          args = [ $target, event ]
+          args.push arguments[i] for i in [1..(arguments.length - 1)] if arguments.length > 1
+
+          callback( args... )
 
     definition.stop = true if definition.type == 'click' and ! definition.stop?
 

data/darwinjs-rails.gemspec

@@ -18,9 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'railties', '~> 3.2'
-  spec.add_dependency 'coffee-rails', '~> 3.2'
-  spec.add_dependency 'jquery-rails', '~> 2.2'
+  spec.add_dependency 'railties', '~> 4.0'
+  spec.add_dependency 'coffee-rails', '~> 4.0'
+  spec.add_dependency 'jquery-rails', '~> 3.0'
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
 end

data/doc/introduction.md

@@ -46,7 +46,7 @@ controllers/, as controllers depend on views.
 You can easily create a module using the generator provided :
 
 ```
-$ rails generate darwin admin_area/users/index
+$ rails generate darwinjs:assets admin_area/users/index
 
       create  app/assets/javascripts/controllers/admin_area.coffee
       create  app/assets/javascripts/views/admin_area.coffee

data/lib/darwinjs/rails/version.rb

@@ -1,5 +1,5 @@
 module Darwinjs
   module Rails
-    VERSION = "1.0.1"
+    VERSION = "1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: darwinjs-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-20 00:00:00.000000000 Z
+date: 2013-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: coffee-rails
   requirement: !ruby/object:Gem::Requirement
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: jquery-rails
   requirement: !ruby/object:Gem::Requirement
@@ -50,7 +50,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -58,7 +58,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement