darwinjs-rails 1.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in darwinjs-rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Olivier El Mekki
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# Darwinjs
+
+Darwin is a javascript framework for people that take error
+handling seriously and want to achieve it through progressive
+enhancement and graceful degradation.
+
+Darwin will also let developer write clean and encapsulated
+code that encourages self documentation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'darwinjs-rails'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install darwinjs-rails
+
+## Getting Started
+
+First, as one time configuration, add autoloader in your
+application.coffee file :
+
+```
+$(->
+  Darwin.Loader.run()
+)
+```
+
+You can now generate a javascript module using the provided
+generator :
+
+```
+$ rails generate darwin:assets users/index
+
+      create  app/assets/javascripts/controllers/users.coffee
+      create  app/assets/javascripts/views/users.coffee
+      create  app/assets/javascripts/controllers/users/index.coffee
+      create  app/assets/javascripts/views/users/index.coffee
+```
+
+This will create your controller and your view in the `users` namespace.
+
+Now add a `data-module` attribute in your users index view to
+autoload your module :
+
+```erb
+<div id="users" data-module="User.Index">
+  <ul>
+  <% @users.each do |user| %>
+    <%= render 'user', user: user %>
+  <% end %>
+  </ul>
+</div>
+```
+
+This will automatically initialize your module.
+
+A module is composed of two files :
+
+* a controller that handles events
+* a view that handles DOM manipulation
+
+Here is a typical view :
+
+```coffee
+class App.Views.Users.Index extends Darwin.Controller
+  @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()
+```
+
+And the corresponding controller :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Toggle user block':      { el: 'show_users', type: 'click' }
+      'Show user info':         { el: 'user_more', type: 'click' }
+      'Delete user on server':  { el: 'user_delete', type: 'click' }
+  }
+
+
+  show_users_clicked: ->
+    @view.get( 'user_block' ).fadeIn()
+
+
+  user_more_clicked: ( $link ) ->
+    @view.show_info_for( $link )
+
+  
+  user_delete_clicked: ( $link ) ->
+    if confirm( 'Really delete user ?' )
+      $.get( $link.attr( 'href' ), =>
+        @view.remove_user_for( $link )
+      )
+```
+
+As you see, a view acts as single point of configuration for selectors.
+Any change needed 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
+lines of the controller file.
+
+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.
+
+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.
+
+Ready for more ? See [introduction](doc/introduction.md).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

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

@@ -0,0 +1,75 @@
+# Documentation is in /doc/base.md
+#
+reserved_keywords = [ 'extended', 'included' ]
+
+class Darwin.Base
+  @options: ( options ) ->
+    parent_options = @__super__.constructor._options
+
+    if parent_options?
+      @_options = $.extend true, {}, parent_options, options
+    else
+      @_options = options
+
+
+  @extend: ( obj ) ->
+    for key, value of obj when key not in reserved_keywords
+      @[ key ] = value
+
+    obj.extended?.apply(@)
+    @
+
+
+  @include: ( obj ) ->
+    for key, value of obj when key not in reserved_keywords
+      @::[ key ] = value
+
+    obj.included?.apply(@)
+    @
+
+
+  constructor: ( options ) ->
+    @_bound = {}
+
+    @options = $.extend( {}, @constructor._options, options )
+
+    if @options.dependencies?
+      for own name, dependency of @options.dependencies
+        @[ name ] = dependency
+
+
+  bind: ( event_name, callback ) ->
+    @_bound[ event_name ] ?= []
+    @_bound[ event_name ].push( callback )
+
+
+  on: ( event_name, callback ) ->
+    @bind( event_name, callback )
+
+
+  one: ( event_name, callback ) ->
+    callback = =>
+      @unbind event_name, callback
+
+    @bind event_name, callback
+
+
+  unbind: ( event_name, callback ) ->
+    if @_bound[ event_name ]
+      if callback
+        $.each @_bound[ event_name ], ( i, bound ) ->
+          if bound == callback
+            delete @_bound[ event_name ][ i ]
+
+      else
+        delete @_bound[ event_name ]
+
+
+  unbind_all: ->
+    @_bound = {}
+
+
+  trigger: ( event_name, params... ) ->
+    if @_bound[ event_name ]
+      for own callback in @_bound[ event_name ]
+        callback( params... )

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

@@ -0,0 +1,125 @@
+# Documentation is in /doc/controller.md
+#
+class Darwin.Controller extends Darwin.Base
+  @options {
+    events: {}
+    View: Darwin.View
+    failsafe: true
+  }
+
+
+  constructor: ( root, options ) ->
+    super options
+
+    @root = root.get(0)
+
+    if @root
+      @_dom_bound = []
+      @$root      = $( @root )
+      @view       = new @options.View @$root
+
+      @bind_dom_events() unless exports?
+      @view.run()
+      @run() unless exports?
+    else
+      throw new Error( 'Controller initialized without any element' )
+
+
+  run: ->
+
+
+  bind_dom_events: ->
+    @bind_dom_event( event, name ) for own name, event of @options.events
+
+
+  bind_dom_event: ( definition, name ) ->
+    unless definition.el?
+      throw new Error( "No el key for event : #{name or 'manually bound event'}" )
+
+    unless definition.type?
+      throw new Error( "No type key for event : #{name or 'manually bound event'}" )
+
+
+    wrap = ( callback, stop ) =>
+      ( event ) =>
+        unless ( window.crashed and @options.failsafe is true )
+          event.preventDefault() if stop
+          $target = $( event.target )
+
+          if definition.ensure_element isnt false
+            el = if definition.delegate? then definition.delegate else definition.el
+            
+            if el == 'root'
+              sel = 'root'
+            else
+              sel = ( @view.selectors[ el ] or @view._find_alternate_name( el ) ).sel
+
+            $target = $target.parents( sel ).first() unless $target.is( sel )
+
+          callback( $target, event )
+
+    definition.stop = true if definition.type == 'click' and ! definition.stop?
+
+    switch true
+      when !! definition.controller_method
+        method_name = definition.controller_method
+        if @[ method_name ]
+          method = $.proxy( @[ method_name ], this )
+        else
+          throw new Error( "Undefined method for controller : #{method_name}" )
+
+      when !! definition.view_method
+        method_name = definition.view_method
+        if @view[ method_name ]
+          method = $.proxy( @view[ method_name ], @view )
+        else
+          throw new Error( "Undefined method for view : #{method_name}" )
+
+      else
+        method_name = "#{definition.delegate or definition.el}_#{definition.type}#{if definition.type.match( /e$/ ) then 'd' else 'ed' }"
+        if @[ method_name ]
+          method = $.proxy( @[ method_name ], this )
+        else
+          throw new Error( "Undefined method for controller : #{method_name}" )
+
+    $element = @view.get( definition.el )
+
+
+    if definition.delegate
+      delegate_to = @view.selectors[ definition.delegate ] or @view._find_alternate_name( definition.delegate )
+
+      if definition.cancel_delay and definition.cancel_delay > 0
+        callback = ( event ) =>
+          window.clearTimeout @[ '_' + method_name + '_timeout' ]
+          wrapped = wrap( method, definition.stop )
+          @[ '_' + method_name + '_timeout' ] = window.setTimeout( ( -> ( wrapped event ) ), definition.cancel_delay )
+      else
+        callback = wrap method, definition.stop
+
+      throw new Error "Selector not found : #{definition.delegate}" unless delegate_to
+      $element.delegate delegate_to.sel, definition.type, callback
+      @_dom_bound.push { el: $element, delegate: delegate_to.sel, type: definition.type, callback: callback }
+    else
+      if definition.cancel_delay and definition.cancel_delay > 0
+        callback = ( event ) =>
+          window.clearTimeout @[ '_' + method_name + '_timeout' ]
+          wrapped = wrap( method, definition.stop )
+          @[ '_' + method_name + '_timeout' ] = window.setTimeout( ( -> ( wrapped event ) ), definition.cancel_delay )
+      else
+        callback = wrap method, definition.stop
+
+      $element.bind definition.type, callback
+      @_dom_bound.push { el: $element, type: definition.type, callback: callback }
+
+
+  destructor: ->
+    @view._destructor()
+    for bound in @_dom_bound
+      if bound.delegate
+        bound.el.undelegate bound.delegate, bound.type, bound.callback
+      else
+        bound.el.unbind bound.type, bound.callback
+
+    delete Darwin.Loader.controllers()[ @id ]
+
+

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

@@ -0,0 +1,54 @@
+# Documentation is in /doc/loader.md
+#
+controllers = {}
+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_roots: ->
+    $( '*[data-module]' )
+
+
+  compute_name: ( module_path ) ->
+    name = module_path.replace( /\./g, '_' ).toLowerCase()
+
+    if controllers[ name ]
+      i = 1
+
+      for own controller_name, controller of controllers
+        i++ if controller_name.indexOf( name ) isnt -1
+
+      name = "#{name}_#{i}"
+
+    name
+
+  controllers: ->
+    controllers
+
+window.onerror = ( error, url, lineno ) =>
+  if url && url.match( /https?:\/\/.*?assets/ )
+    @crashed = true
+    console?.log( "Error on #{url}, line #{lineno}" )
+    errors_got += 1
+
+    if window.js_exception_url and errors_got <= 5
+      $.post( window.js_exception_url, js_error: { error: error, url: url, lineno: lineno, page_url: window.location.href } )
+
+    for own controller_name, controller of controllers
+      controller.destructor() if controller.options.failsafe is true
+  error

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

@@ -0,0 +1,43 @@
+#= require './base'
+
+class Darwin.Template extends Darwin.Base
+  @_cached: {}
+  
+  @options {
+    dependencies:
+      Mustache: window.Mustache
+  }
+
+  constructor: ( @template ) ->
+    super
+
+    @retrieve_template_from_dom() unless @retrieve_template_from_memory()
+
+
+  retrieve_template_from_memory: ->
+    if Templates?[ @template ]
+      @template = Templates[ @template ]
+      true
+    else
+      false
+
+  retrieve_template_from_dom: ->
+    name = @template.replace( '#', '' )
+
+    if Darwin.Template._cached[ name ]
+      @template = Darwin.Template._cached[ name ]
+    else
+      $template = $( "script##{name}_template[type=\"text/mustache\"]" )
+
+      unless $template.length
+        throw new Error( "can't find template #{name}" )
+
+      @template = $template.html()
+      Darwin.Template._cached[ name ] = @template
+
+
+  render: ( data ) ->
+    $( @render_to_string(data ) )
+    
+  render_to_string: (data) ->
+    Mustache.render( @template, data )

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

@@ -0,0 +1,108 @@
+# Documentation is in /doc/view.md
+#
+class Darwin.View extends Darwin.Base
+  _cached: {}
+
+  constructor: ( @$root, options ) ->
+    super options
+    @_flatten_selectors()
+    @$root.find( '.fallback-submits' ).hide()
+
+
+  run: ->
+
+
+  get: ( selector_name ) ->
+    if @[ "get_#{selector_name}" ]
+      @[ "get_#{selector_name}" ]()
+    else
+      @[ "$#{selector_name}" ] or @_find_element( selector_name )
+
+
+  _destructor: ->
+    @$root.find( '.fallback-submits' ).show()
+    @destructor()
+
+
+  destructor: ->
+
+
+  clear_cache: ( selector_name ) ->
+    if selector_name
+      delete @[ "$#{selector_name}" ]
+    else
+      @clear_cache( selector_name ) for own selector_name, _ of @_cached
+      @_cached = {}
+
+
+  _find_element: ( selector_name ) ->
+    definition = @selectors[ selector_name ] or @_find_alternate_name( selector_name )
+    if definition
+      $base  = if definition.within? then @get( definition.within ) else @$root
+      $found = $base.find definition.sel
+
+      unless definition.cache is false
+        @[ "$#{selector_name}" ] = $found
+        @_cached[ selector_name ] = true
+
+      $found
+    else
+      $element = @$root.find( "##{selector_name}" )
+      if $element.get(0)
+        @[ "$#{selector_name}" ] = $element
+        @_cached[ selector_name ] = true
+        $element
+      else
+        throw new Error "Selector not found : #{selector_name}"
+
+
+  _flatten_selectors: ->
+    selectors = {}
+    walk = ( values, name, parent_names ) ->
+      selector_key = ''
+
+      if name
+        if parent_names
+          selector_key += "#{parent_name.short}_" for parent_name in parent_names
+
+        selector_key += name
+        selectors[ selector_key ] = {}
+
+      if typeof values == 'string'
+        selectors[ selector_key ] = { sel: values }
+      else
+
+        for own attr, value of values
+          if $.inArray( attr, [ 'cache', 'sel', 'within' ] ) isnt -1
+            selectors[ selector_key ][ attr ] = value
+          else
+            parents = $.merge [], ( parent_names or [] )
+            parents.push({ short: name, long: selector_key }) if name
+            walk value, attr, parents
+
+        if name and not values.sel
+          selectors[ selector_key ].sel = "##{name}"
+
+      if parent_names and parent_names.length
+        selectors[ selector_key ].within = parent_names[ parent_names.length - 1 ].long
+
+      selectors[ selector_key ].alternate_name = name if name
+
+    walk @options.selectors
+    @selectors = selectors
+
+
+  _find_alternate_name: ( name ) ->
+    definitions = []
+
+    for selector, definition of @selectors
+      definitions.push( definition ) if definition.alternate_name == name
+
+    if definitions.length
+      if definitions.length > 1
+        throw new Error "Multiple definitions for #{name}"
+      else
+        definitions[0]
+    else
+      null
+

data/app/assets/javascripts/darwin.coffee

@@ -0,0 +1,16 @@
+#= require_self
+#= require './darwin/base'
+#= require './darwin/loader'
+#= require './darwin/template'
+#= require './darwin/view'
+#= require './darwin/controller'
+#
+# Documentation is in /doc/introduction.md
+#
+
+window.Darwin = {}
+
+window.App =
+  Views:        {}
+  Controllers:  {}
+  Helpers:      {}

data/darwinjs-rails.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'darwinjs/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "darwinjs-rails"
+  spec.version       = Darwinjs::Rails::VERSION
+  spec.authors       = ["Olivier El Mekki"]
+  spec.email         = ["olivier@el-mekki.com"]
+  spec.description   = %q{Javascript framework with progressive enhancement in mind.}
+  spec.summary       = %q{Darwin lets create complex javascript interfaces that do not expect they own the application and that degrade gracefully when an error occurs}
+  spec.homepage      = "https://github.com/oelmekki/darwinjs-rails"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  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_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end