darwinjs-rails 1.0.1

data/doc/loader.md

@@ -0,0 +1,116 @@
+Darwin.Loader ensure only the needed javascript is executed.
+
+# Autoloading
+
+If you do something like this :
+
+```coffee
+$( '#my_module' ).each( ( i, el ) ->
+  new App.Controllers.MyModule( $(el) )
+)
+```
+
+You may think it's ok even if `#my_module` is only present on a
+single page of your application, because jQuery will simply do
+nothing if it doesn't find the element.
+
+It's not ok. If you do that, DOM will be hit to find the element
+on every single page. Hitting the DOM is expansive, you should not
+do it if it's not necessary. When you'll have 100 controllers in
+your app and DOM hitted 100 times on each page load to find module
+elements, slow js engines will begin to suffer before you actually
+do anything.
+
+Darwin.Loader provides a mean to only load what you need. Add a
+data-module attribute to the target block, and Darwin.Loader will
+do a single DOM request to retrieve '*[data-module'] and initialize
+your controllers :
+
+```html
+  <div id="users" data-module="AdminArea.Users.Show">
+    <ul>
+      <li>John</li>
+      <li>Joe</li>
+    </ul>
+  </div>
+```
+
+is equivalent to :
+
+```coffee
+new App.Controllers.AdminArea.Users.Show( $( '#users' ) )
+```
+
+To start, loader, add this in your application code :
+
+```coffee
+Darwin.Loader.run()
+```
+
+
+# Error handling
+
+Darwin takes error handling seriously. The default behavior is to
+deactivate javascript app on any error occuring in it. If your app
+code produce an error, all its event callbacks are deactivated and
+controllers' destructor methods are called. This is a good thing.
+
+Consider the following :
+
+```html
+<div id="items"></div>
+<a href="#">show more</a>
+```
+
+```coffee
+$( 'a' ).click( ->
+  please_crash()
+  $( '#items' ).load( '/more_items' )
+)
+```
+
+What happens when you click the link ? Nothing. What happens if
+you click again ? And again, and again ? Still nothing. At this
+point if you're a developer, your instinct will suggest you reload
+the page. Other people will get angry because "it does not work" and
+leave your application.
+
+Here is the proper Darwin equivalent :
+
+```html
+<div data-module="ShowMore">
+  <div id="items"></div>
+  <a href="/show_more">show more</a>
+</div>
+```
+
+```coffee
+class App.Views.ShowMore extends Darwin.View
+  @options {
+    link: 'a'
+    items: '#items'
+  }
+
+class App.Controllers.ShowMore extends Darwin.Controller
+  @options {
+    View: App.Views.ShowMore
+
+    events:
+      'Display more items': { el: 'link', type: 'click' }
+  }
+
+  link_clicked: ( $link ) ->
+    please_crash()
+    @view.get( 'items' ).load( "#{$link.attr( 'href' )} #items" )
+```
+
+When you click the first time, error will occurs and nothing
+will happen. If you click a second time, as event callbacks have
+been deactivated, the link will be followed and user won't realize
+something bad happened. That means, by the way, that javascript
+will have been reloaded.
+
+Additionnaly, if you provided an url in the `window.js_exception_url`,
+an ajax request will be fired to report the error.
+
+

data/doc/view.md

@@ -0,0 +1,282 @@
+Darwin.View is the base class for views, which handle all
+DOM traversal and manipulation.
+
+Darwin.View main purpose is to provide a central configuration
+point between your javascript app and your DOM tree. It also
+eases DOM elements caching.
+
+Actually, elements caching is so important that it's the
+default behavior, and you have to explicitely tell you don't
+want caching on some specific selector.
+
+
+# Selectors
+
+The problem that Darwin.View addresses is breaking your js
+application when you alter your DOM structure.
+
+Consider the following :
+
+```html
+<aside id="sidebar">
+  <ul class="users">
+    <li>John</li>
+    <li>Joe</li>
+  </ul>
+  <a class="hide">hide</a>
+</aside>
+
+<article>
+  <h1>Users activity</h1>
+
+  <p>Last week, 402 users registered.</p>
+  <p>2311 has been active is that period.</p>
+</article>
+```
+
+If you want to do special things on users with javascript,
+you'll probably have things like that across your js codebase :
+
+```coffee
+$( '#sidebar .users li' ).hover( do_stuff )
+
+$( '#sidebar a.hide' ).click( ->
+  $( '#sidebar .users' ).hide()
+  $( '#sidebar a.hide' ).hide()
+)
+```
+
+Now, what if you decide user list should be called `#user_list`
+rather than `.users` and should be in the article rather than in
+sidebar ? You have to browse your whole codebase to change selectors,
+possibly missing a few and causing crashes.
+
+Darwin.View acts as a center point of configuration for selectors :
+
+```html
+<div id="page">
+  <aside id="sidebar">
+    <ul class="users">
+      <li>John</li>
+      <li>Joe</li>
+    </ul>
+    <a class="hide">hide</a>
+  </aside>
+  
+  <article>
+    <h1>Users activity</h1>
+  
+    <p>Last week, 402 users registered.</p>
+    <p>2311 has been active is that period.</p>
+  </article>
+</div>
+```
+
+```coffee
+class MyView extends Darwin.View
+  @options {
+    selectors:
+      user_list: 
+        'sel': '#sidebar .users'
+        item: 'li'
+      hide_users: '#sidebar a.hide'
+
+  }
+```
+
+Now, you can use the view to retrieve elements :
+
+```coffee
+view = new MyView( '#page' ) # note : in real case, controller will initialize
+                             # view, no need to do it yourself.
+
+view.get( 'root' )           # return the root element for view
+
+view.get( 'item' ).hover( do_stuff )
+
+view.get( 'hide_users' ).click( ->
+  view.get( 'user_list' ).hide()
+  view.get( 'hide_users' ).hide()
+)
+```
+
+Please note a view is always bound to a specific part of the DOM,
+the element passed at initialization (or the element on which
+the data-module attribute is set, if you use Darwin.Loader's
+autoload). All selectors are relative to that element. You may
+retrieve it using `@get( 'root' )`.
+
+If you decide user list should be in article body, all you
+have to do is to change selectors declaration :
+
+```coffee
+class MyView extends Darwin.View
+  @options {
+    selectors:
+      user_list: 
+        'sel': 'article .users'
+        item: 'li'
+      hide_users: 'article a.hide'
+
+  }
+```
+
+... and the change is reflected on your whole codebase.
+
+
+## Selector declaration
+
+A selector can be either a css selector string or a configuration
+object :
+
+```coffee
+@options {
+  selectors:
+    foo: '#foos .foo'
+    bar: { 'sel': '#bars .bar' }
+}
+```
+
+It is recommanded to put configuration keys (like `sel`, here)
+into a string so syntax highlighting make it easy to see selector
+names (`foo`, `bar`) at one glance.
+
+Selectors may be embedded :
+
+```coffee
+@options {
+  selectors:
+    foo:
+      'sel': '#foos'
+      bar: '#bars'
+}
+```
+
+`#bars` can be accessed with `view.get( 'foo_bar' )`, which will
+translate to `$( '#foos #bars' )`. If the embedded selector name
+is unambiguous, it can be used directly :
+
+```coffee
+class MyView extends Darwin.View
+  @options {
+    selectors:
+      foo:
+        'sel': '#foos'
+        wrong: 'p'
+        bar:
+          'sel': '#bars'
+          wrong: 'a'
+  }
+
+view = new MyView( $( '#page' ) )
+
+view.get( 'bar' )                 # Same as view.get( 'foo_bar' ).
+
+view.get( 'wrong' )               # Will throw ambiguous selector error.
+                                  # Use explicit view.get( 'foo_bar_wrong' )
+                                  # or view.get( 'foo_wrong' )
+```
+
+
+# Caching
+
+The first time you ask view for a selector, it is cached, to avoid
+hitting the DOM again and again when you access elements. This is
+what you want most of the times.
+
+But sometime, you do not want caching. For example, items in a
+list may be added or removed.
+
+You can specify element should not be cached by using the cache option :
+
+```coffee
+@options {
+  selectors:
+    foo: { 'sel': '#foos', 'cache': false }
+}
+```
+
+You may also keep default caching, but empty the cache at a given
+point :
+
+```coffee
+ view.clear_cache( 'foo' ) # removed cache for `foo` selector
+ view.clear_cache()        # empty the whole cache
+```
+
+
+# Dynamic getter
+
+You can also define methods to retrieve element, be it to create
+the element in first place or because you need specific logic.
+Simply declare a method named after your selector and prefixed
+with `get_` :
+
+```coffee
+class MyView extend Darwin.View
+  get_foo: ->
+    @$foo ?= $( '<div id="foo"></div>' ).appendTo( @get( 'root' ) )
+
+my_view = new MyView( $( '#page' ) )
+my_view.get( 'foo' )                 # creates #foo and returns it
+```
+
+You're responsible to cache elements retrieved by getter methods.
+
+
+# Progressive enhancement and graceful degradation
+
+You should build your features so they work without javascript.
+There's a good reason for that : if an error occurs in your
+javascript codebase, events will be deactivated and plain html
+features will ask server to handle the feature.
+
+This means two important things :
+
+* your javascript should prepare DOM on run
+* it should restore its previous state on destruction
+
+Take the following example :
+
+```html
+<div id="page">
+  <form action="/search" method="post">
+    <input type="search" />
+    <input type="submit" />
+  </form>
+</div>
+```
+
+```coffee
+class MyView extends Darwin.View
+  @options {
+    selectors:
+      search_field: 'input[type="search"]'
+      submit: 'input[type="submit"]'
+  }
+
+
+  run: ->
+    @get( 'submit' ).hide()
+
+
+  destructor: ->
+    @get( 'submit' ).show()
+```
+
+When your view is initialized, the submit button will be hidden.
+You probably will handle search field change through ajax
+request in your controller.
+
+If an error occurs, view's destructor method will be called,
+and the submit input will be shown again, so user can continue
+using the feature.
+
+Therefore, it's important any change you make in the run() method
+has a pending teardown in the destructor() method.
+
+As showing and hiding submit buttons is quite common, their
+handling is natively implemented. For this kind of buttons, simply
+add a `fallback-submits` class on them.
+
+

data/lib/darwinjs/rails/engine.rb

@@ -0,0 +1,9 @@
+require 'coffee/rails/engine'
+
+module Darwinjs
+  module Rails
+    class Engine < ::Rails::Engine
+      config.app_generators.javascript_engine :darwinjs
+    end
+  end
+end

data/lib/darwinjs/rails/version.rb

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

data/lib/darwinjs-rails.rb

@@ -0,0 +1,2 @@
+require 'darwinjs/rails/engine'
+require 'darwinjs/rails/version'

data/lib/generators/darwinjs/assets/assets_generator.rb

@@ -0,0 +1,78 @@
+require "rails/generators/named_base"
+
+module Darwinjs
+  module Generators
+    class AssetsGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("../templates", __FILE__)
+
+      def create_module
+        if is_resource?
+          create_resource
+        else
+          create_action( ( class_path + [ file_name ] ).join( '/' ) )
+        end
+      end
+
+      private
+
+      def is_resource?
+        name.underscore != name
+      end
+
+      def create_resource
+        %w[index edit show new form].each do |action|
+          create_action( ( class_path + [ file_name.pluralize, action ] ).join( '/' ) )
+        end
+      end
+
+      def create_action( action )
+        create_namespaces( action )
+        create_controller( action )
+        create_view( action )
+      end
+
+      def create_namespaces( action )
+        current_path = []
+
+        namespaces_for( action ).each do |namespace|
+          current_path << namespace
+          namespace_dir  = current_path.join( '/' )
+          namespace_file = namespace_dir + '.coffee'
+          @namespace = current_path.map( &:camelize ).join( '.' )
+
+          unless File.exists?( controllers_path.join( namespace_file ) )
+            template 'controllers/namespace.coffee', controllers_path.join( namespace_file ).to_s
+          end
+
+          unless File.exists?( views_path.join( namespace_file ) )
+            template 'views/namespace.coffee', views_path.join( namespace_file ).to_s
+          end
+        end
+      end
+
+      def create_controller( action )
+        @js_path = action.split( '/' ).map( &:camelize ).join( '.' )
+        template 'controllers/controller.coffee', controllers_path.join( "#{action}.coffee" )
+      end
+
+      def create_view( action )
+        @js_path = action.split( '/' ).map( &:camelize ).join( '.' )
+        template 'views/view.coffee', views_path.join( "#{action}.coffee" )
+      end
+
+      def namespaces_for( action )
+        parts = action.split( '/' )
+        parts.pop
+        parts
+      end
+
+      def controllers_path
+        @controllers_path ||= ::Rails.root.join( 'app', 'assets', 'javascripts', 'controllers' )
+      end
+
+      def views_path
+        @views_path ||= ::Rails.root.join( 'app', 'assets', 'javascripts', 'views' )
+      end
+    end
+  end
+end

data/lib/generators/darwinjs/assets/templates/controllers/controller.coffee

@@ -0,0 +1,5 @@
+class App.Controllers.<%= @js_path %> extends Darwin.Controller
+  @options {
+    View: App.Views.<%= @js_path %>
+    events: {}
+  }

data/lib/generators/darwinjs/assets/templates/controllers/namespace.coffee

@@ -0,0 +1 @@
+App.Controllers.<%= @namespace %> = {}

data/lib/generators/darwinjs/assets/templates/views/namespace.coffee

@@ -0,0 +1,2 @@
+App.Views.<%= @namespace %> = {}
+

data/lib/generators/darwinjs/assets/templates/views/view.coffee

@@ -0,0 +1,5 @@
+class App.Views.<%= @js_path %> extends Darwin.View
+  @options {
+    selectors: {}
+  }
+

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: darwinjs-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Olivier El Mekki
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: coffee-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: jquery-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !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.
+email:
+- olivier@el-mekki.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/javascripts/darwin.coffee
+- app/assets/javascripts/darwin/base.coffee
+- app/assets/javascripts/darwin/controller.coffee
+- app/assets/javascripts/darwin/loader.coffee
+- app/assets/javascripts/darwin/template.coffee
+- app/assets/javascripts/darwin/view.coffee
+- darwinjs-rails.gemspec
+- doc/base.md
+- doc/controller.md
+- doc/introduction.md
+- doc/loader.md
+- doc/view.md
+- lib/darwinjs-rails.rb
+- lib/darwinjs/rails/engine.rb
+- lib/darwinjs/rails/version.rb
+- lib/generators/darwinjs/assets/assets_generator.rb
+- lib/generators/darwinjs/assets/templates/controllers/controller.coffee
+- lib/generators/darwinjs/assets/templates/controllers/namespace.coffee
+- lib/generators/darwinjs/assets/templates/views/namespace.coffee
+- lib/generators/darwinjs/assets/templates/views/view.coffee
+homepage: https://github.com/oelmekki/darwinjs-rails
+licenses:
+- MIT
+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
+signing_key: 
+specification_version: 3
+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: []
+has_rdoc: