darwinjs-rails 1.1 → 1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7bd0c876edd561b19225af8ae36ccc113c469ee1
+  data.tar.gz: 5f343991cd9087f3b576447814be7adf2fe4971f
+SHA512:
+  metadata.gz: d9f4f59df36f7e34893245fefbd42ccf4e1faee5378c51884774c6e972471f9a94dd9327ba4d40872a02ce6b52d282d09e031cc988f56ee5188d06d549291211
+  data.tar.gz: d5dc3e60ca31e95052a011dd28d5d8203fa3a29ffc2be155a5a9fd54610e3eb25a5ae9952894cef9bf616699c91914f8176f748ee3775c7d718667e2ede044ab

data/README.md

@@ -23,6 +23,8 @@ Or install it yourself as:
 
 ## Getting Started
 
+### Autoloader
+
 First, as one time configuration, add autoloader in your
 application.coffee file :
 
@@ -36,11 +38,14 @@ $(->
 )
 ```
 
+
+### Generator
+
 You can now generate a javascript module using the provided
 generator :
 
 ```
-$ rails generate darwin:assets users/index
+$ rails generate darwinjs:assets users/index
 
       create  app/assets/javascripts/controllers/users.coffee
       create  app/assets/javascripts/views/users.coffee
@@ -70,28 +75,34 @@ A module is composed of two files :
 * a controller that handles events
 * a view that handles DOM manipulation
 
-Here is a typical view :
+
+### Controller
+
+The minimal controller you could write is as this :
 
 ```coffee
-class App.Views.Users.Index extends Darwin.View
-  @options {
-    selectors:
-      show_users: 'a#show_users'
-      user_block: '#users'
-      user:
-        'sel': '.user'
-        more: '.more a'
-        delete: 'a[data-method="delete"]'
-  }
+class App.Controllers.MyModule extends Darwin.Controller
+  run: ->
+    alert( 'hello' )
+```
 
-  show_info_for( $link ) ->
-    $link.next( '.info' ).show()
+And bind it to your html file :
 
-  remove_user_for( $link ) ->
-    $link.parent().remove()
+```html
+<div id="my-block" data-module="MyModule"></div>
 ```
 
-And the corresponding controller :
+With just that, you've already leveraged an important performance tweak from
+Darwin over `if $('#my_block').length then alert( 'hello' )` : instead of
+querying the dom on every page of your application to find `#my_block`, a
+single query will be issued to retrieve `*[data-module]` and initialize their
+module. Just think of how many DOM queries that returns nothing you fire on
+your typical page. `$('#not-existing')` does not do nothing, it browses the
+whole DOM to retrieve a non-existing element. That's a performance issue.
+
+But a controller can do way more than that. Its whole purpose is to encapsulate
+interruptions - events and requests.
+
 
 ```coffee
 class App.Controllers.Users.Index extends Darwin.Controller
@@ -120,23 +131,89 @@ class App.Controllers.Users.Index extends Darwin.Controller
       )
 ```
 
-As you see, a view acts as single point of configuration for selectors.
-Any change made then reflect to the whole javascript codebase.
+Events declaration are grouped in the option hash, with a human readable
+description, so that any developer can understand at a glance what the
+controller is doing. An event declaration is typically made of a descriptive
+string and of configuration object :
+
+```coffee
+'Description': { el: 'element_name', type: 'event_type' }
+```
+
+The callback method name is inferred from event configuration, using
+`<element_name>_<event_type>(ed|d)`. The element (extended with jQuery) is
+passed as first argument, and the raw event is passed as second.
+
+Beside that, declaring events that way rather than directly with jQuery has a
+massive advantage : all callback functions are wrapped in a function that will
+prevent them to run if a crash occurs. It means that if you have a `<a
+href="/foo"></a>` with a click event on it and a crash occurs, clicking it
+again will not trigger event, and link will be followed. This ensure you can
+have fallback features to handle javascript errors and reload the page.
+
+
+### View
+
+Finally, views are meant for all DOM manipulation and acts as a single point of
+configuration for selectors. In previous controller example, we've used element
+names "show_user", "user_more", "user_delete", "user_block", etc. Very often in
+a module, you will refer an element more than one time. It means that if your
+html change, you've got to track all selectors used to find what you have to
+change.
 
-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
-lines of the controller file.
+This is not a problem with Darwin, as selectors are all configured in the same
+place, without any repeatition :
 
-But there is more happening under the hood, here. First, all you DOM
-elements retrieved by view selectors are cached. Upon further call
-they are retrieved without hitting the DOM again, which is very
-costly in term of performances.
+```coffee
+class App.Views.Users.Index extends Darwin.View
+  @options {
+    selectors:
+      show_users: 'a#show_users'
+      user_block: '#users'
+      user:
+        'sel': '.user'
+        more: '.more a'
+        delete: 'a[data-method="delete"]'
+  }
+
+  show_info_for( $link ) ->
+    $link.next( '.info' ).show()
+
+  remove_user_for( $link ) ->
+    $link.parent().remove()
+```
+
+The `selectors` options hash list all selectors used by module. They can be
+declared right away or through a 'sel' key, which then allow to use nested
+selectors. This system also offer a performance bonus : all elements retrieved
+with these selectors are cached by default, because it's the desired behavior,
+most of the time (you can pass option `cache: false` to a specific selector not
+to cache its result). Selectors can be used with `get()` view method :
+`@get('user_more')`.
+
+Beside selectors configuration, views are responsible for DOM manipulation. It
+means that controllers call views upon interuptions to alter page content (like
+the two methods in previous view, used by previous controller). It also means
+that views are responsible for setting up and tearing down the page, reflecting
+progressive enhancement and graceful degradation :
+
+```coffee
+class App.Views.MyModule extends Darwin.View
+  @options {
+    selectors:
+      submit: 'input[type="submit"]'
+  }
+
+  run: ->
+    @get( 'submit' ).hide()
+
+
+  destructor: ->
+    @get( 'submit' ).show()
+```
 
-Furthermore, all event callbacks are wrapped so that they do not
-execute if an error occured. In case of error, events are simply
-deactivated and any link is followed, reloading the page and letting
-server side handle what has to be done, so your user doesn't even
-notice something got wrong.
+As you would expect, `run()` is called on dom ready event, and `destructor()`
+is called when a crash occurs.
 
 Ready for more ? See [introduction](doc/introduction.md).
 

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

@@ -71,5 +71,5 @@ class Darwin.Base
 
   trigger: ( event_name, params... ) ->
     if @_bound[ event_name ]
-      for own callback in @_bound[ event_name ]
+      for callback in @_bound[ event_name ]
         callback( params... )

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

@@ -52,9 +52,12 @@ class Darwin.Controller extends Darwin.Base
             if el == 'root'
               sel = 'root'
             else
-              sel = ( @view.selectors[ el ] or @view._find_alternate_name( el ) ).sel
+              sel = ( @view.selectors[ el ] or @view._find_alternate_name( el ) )?.sel
 
-            $target = $target.parents( sel ).first() unless $target.is( sel )
+              if sel
+                $target = $target.parents( sel ).first() unless $target.is( sel )
+              else
+                $target = @view.get( el )
 
           args = [ $target, event ]
           args.push arguments[i] for i in [1..(arguments.length - 1)] if arguments.length > 1

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

@@ -6,20 +6,26 @@ errors_got = 0
 loader = Darwin.Loader =
   run: ->
     loader.module_roots().each( ( i, $module ) =>
-      $module     = $( $module )
-      module_name = loader.compute_name( $module.attr( 'data-module' ) )
-      path        = $module.attr( 'data-module' ).split( '.' )
-      module      = App.Controllers
-      module      = module[ path.shift() ] while path.length
-
-      if module
-        controllers[ module_name ]    = new module( $module )
-        controllers[ module_name ].id = module_name
-      else
-        throw new Error( "Can't find module #{$module.attr( 'data-module' )}" )
+      $module = $( $module )
+      loader.load_module( $module.attr( 'data-module' ), $module )
     )
 
 
+  load_module: ( pathname, $root ) ->
+    module_name = loader.compute_name( pathname )
+    path        = pathname.split( '.' )
+    module      = App.Controllers
+    module      = module[ path.shift() ] while path.length
+
+    if module
+      controllers[ module_name ]    = new module( $root )
+      controllers[ module_name ].id = module_name
+    else
+      throw new Error( "Can't find module #{pathname}" )
+
+    controllers[ module_name ]
+
+
   module_roots: ->
     $( '*[data-module]' )
 

data/lib/darwinjs/rails/version.rb

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

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: darwinjs-rails
 version: !ruby/object:Gem::Version
-  version: '1.1'
-  prerelease: 
+  version: '1.2'
 platform: ruby
 authors:
 - Olivier El Mekki
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-03 00:00:00.000000000 Z
+date: 2013-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: coffee-rails
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -46,7 +41,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: jquery-rails
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -54,7 +48,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -62,7 +55,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -70,7 +62,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -78,17 +69,15 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Javascript framework with progressive enhancement in mind.
@@ -126,27 +115,26 @@ files:
 homepage: https://github.com/oelmekki/darwinjs-rails
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.0.10
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Darwin lets create complex javascript interfaces that do not expect they
   own the application and that degrade gracefully when an error occurs
 test_files: []