darwinjs-rails 1.0.1

data/doc/base.md

@@ -0,0 +1,147 @@
+Darwin.Base is the common parent of all Darwin classes.
+
+You can use it as well in any of your lib classes to
+benefits of its features :
+
+* option pattern
+* class events
+* mixins
+
+
+# Option pattern
+
+Any class inheriting from Darwin.Base can declare options
+that propagate to children classes, but not to parent classes,
+much like rails' `#class_attribute`. Observe the following :
+
+```coffee
+class MyParentClass extends Darwin.Base
+  @options {
+    foo: 'Foo'
+  }
+
+class MyChildClass extends MyParentClass
+  @options {
+    foo: 'overriden foo'
+    bar: 'bar'
+  }
+
+class MyOtherChildClass extends MyParentClass
+  @options {
+    bar: 'other bar'
+  }
+
+new MyParentClass().options.foo       # => 'Foo'
+new MyChildClass().options.foo        # => 'overriden foo'
+new MyOtherChildClass().options.foo   # => 'Foo'
+new MyChildClass().options.bar        # => 'bar'
+new MyParentClass().options.bar       # => undefined
+```
+
+Additionnaly, options can be overriden at initialization time :
+
+```coffee
+new MyChildClass( bar: 'hello' ).options.bar  # => 'hello'
+```
+
+If you override the constructor methods, don't forget to accept
+options parameter and call super with it :
+
+```coffee
+class MyClass extends Darwin.Base
+  constructor: ( options ) ->
+    super( options )
+    # do stuff
+```
+
+
+# Class events
+
+With jQuery, you can only bind and fire events on DOM elements.
+
+Darwin.Base provides a mean to attach events on classes :
+
+```coffee
+class MyClass extends Darwin.Base
+  @options {
+    my_name: 'Joe'
+  }
+
+  say_hi: ->
+    @trigger( 'said', "Hi, my name is #{@options.my_name}." )
+
+my_instance = new MyClass()
+my_instance.on( 'said', ( message ) -> ( console.log( message ) ) )
+my_instance.say_hi() # logs : Hi, my name is Joe.
+```
+
+This allows to easily encapsulate features in classes and have them
+to communicate.
+
+
+# Mixins
+
+A feature that coffeescript lacks of is the ability to include or
+extend mixins. Darwin.Base provides that :
+
+```coffee
+InstanceMethods =
+  do_something: ->
+    console.log 'I did something.'
+
+  do_nothing: ->
+    console.log 'I swear I did nothing.'
+
+
+ClassMethods =
+  foo: ->
+    console.log 'foo'
+
+  bar: ->
+    console.log 'bar'
+    
+
+class MyClass extends Darwin.Base
+  @include InstanceMethods
+  @extend  ClassMethods
+  
+my_instance = new MyClass()
+my_instance.do_something()  # logs : 'I did something.'
+MyClass.foo()               # logs : 'foo'
+```
+
+Just like ruby modules, special methods allow you to
+operate after module is included or extended :
+
+```coffee
+InstanceMethods =
+  included: ->
+    @extend ClassMethods
+
+  do_something: ->
+    console.log 'I did something.'
+
+  do_nothing: ->
+    console.log 'I swear I did nothing.'
+
+
+ClassMethods =
+  extended: ->
+    console.log 'extended'
+
+  foo: ->
+    console.log 'foo'
+
+  bar: ->
+    console.log 'bar'
+    
+
+class MyClass extends Darwin.Base
+  @include InstanceMethods
+  
+my_instance = new MyClass() # logs : 'extended'
+my_instance.do_something()  # logs : 'I did something.'
+MyClass.foo()               # logs : 'foo'
+```
+
+

data/doc/controller.md

@@ -0,0 +1,266 @@
+Darwin.Controller handles everything event or request related.
+
+This is the main entry point for all feature. A Controller
+typically initialize a View and bind events to its selectors
+(though you may use a controller without any View if you need
+to).
+
+# Basic usage
+
+Here is a typical controller example :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Toggle user block': { el: 'user_trigger', type: 'click' }
+      'Delete user': { el: 'user_block', delegate: 'delete_user', type: 'click' }
+  }
+
+
+  user_trigger_clicked: ->
+    if @view.users_shown()
+      @view.hide_users()
+    else
+      @view.show_users()
+
+  
+  delete_user_clicked: ( $link ) ->
+    if confirm( 'Really delete user ?' )
+      $.get( $link.attr( 'href' ), =>
+        @view.remove_user( $link )
+      )
+```
+
+All you need to add in your html to use it is a data-module attribute :
+
+```html
+<div id="users_index" data-module="Users.Index">
+  <-- ... -->
+</div>
+```
+
+`options.View` declares which view you will use. View is automatically
+initialized at controller initialization.
+
+`options.events` declares which events are handled by the controller.
+You should use this rather than binding events manually for x reasons :
+
+* It offers a central configuration point, so other developers can see
+  at a glance what controller do.
+* It plays well with view selectors, so that you don't have to change
+  every single file if your DOM structure change.
+* Most important, callbacks are wrapped so they are disabled if an error
+  occurs on page.
+
+Event declaration keys are arbitrary strings. This should act as a
+documentation for your controller. Most of the time, knowning the element
+on which the callback is bound and the event type is useless to understand
+what it's supposed to do :
+
+```coffee
+{ el: 'user_trigger', type: 'click' }
+```
+
+Ok, something happens on user_trigger's click, but what does it do ?
+
+```coffee
+'Toggle user block': { el: 'user_trigger', type: 'click' }
+```
+
+Now, it's clearer.
+
+Callback method names are automatically computed after element and
+event type, so `{ el: 'user_trigger', type: 'click' }` will call the
+`user_trigger_clicked` method. Every callback is passed the element
+as first parameter and the event object as second parameter :
+
+```coffee
+user_trigger_clicked: ( $trigger, event ) ->
+```
+
+Note that if you use delegation, delegated element name will be used
+instead of element name :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Delete user': { el: 'user_block', delegate: 'delete_user', type: 'click' }
+  }
+
+
+  delete_user_clicked: ( $link ) ->
+```
+
+# Event declaration options
+
+Here are all options allowed in event declaration :
+
+## el
+
+A view selector name. Element will be retrieved using `@view.get( <name> )`.
+
+## type
+
+The event on which to bind the callback. This can be any jQuery event the
+element responds to. So, if you have a plugin that trigger a custom `display`
+event on element, you can use it there.
+
+## delegate
+
+Use delegation instead of static binding. The selector name
+is retrieved from view, just as `el`.
+
+Delegation not only let bind events on element that are not
+in the page when callback is bound, but also let bind a single
+event instead of hundredth. You probably should use it as much
+as possible.
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Delete user': { el: 'user_block', delegate: 'delete_user', type: 'click' }
+  }
+
+
+  delete_user_clicked: ( $link ) ->
+```
+
+This binds a single callback to handle as many users you want,
+and also handle users you've added in the list after controller
+initialization.
+
+## controller_method
+
+Use a custom method name rather than automatically computed one.
+You may use this, for example, if you want to use the same callback
+for two events.
+
+Sometime, automatically computed name will just not do it. For example,
+Darwin.Controller does not use any special inflection other than
+adding a 'd' rather than 'ed' for words that end with 'e'. So,
+here are the computed method names :
+
+```coffee
+{ el: 'foo', type: 'click' }  # => foo_clicked
+{ el: 'foo', type: 'change' } # => foo_changed
+{ el: 'foo', type: 'show' }   # => foo_showed
+```
+
+For proper english, you can use `controller_method` :
+
+```coffee
+'Update page title': { el: 'foo', type: 'show', controller_method: 'foo_shown' }
+```
+
+## view_method
+
+If your callback simply call a view method, you don't need
+to create a controller method for that :
+
+```coffee
+foo_clicked: ->
+  @view.show_something()
+```
+
+Instead, you can declare this method in event definition :
+
+```coffee
+'Show something': { el: 'foo', type: 'click', view_method: 'show_something' }
+```
+
+`controller_method` and `view_method` are mutually exclusive.
+
+## stop
+
+By default, any click event calls `event.preventDefault()` and
+`event.stopPropagation()`, because it's what we need most of the time.
+
+You may not want that, for example, when you want to ask a confirmation
+to user. In that case, you can declare `stop: false` :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Delete user': { el: 'delete_user', type: 'click', stop: false }
+  }
+
+
+  delete_user_clicked: ( $link, event ) ->
+    event.preventDefault() unless confirm( 'seriously ?' )
+```
+
+Reversively, you can force stopping on other events :
+
+```coffee
+'Troll ie users': { el: 'user_checkbox', type: 'change', stop: true }
+```
+
+## cancel_delay
+
+Sometime, you want to wait for a short time on an event before
+executing its callback, and potentialy cancel it if the same
+event occurs.
+
+You will use that typically on an ajax autocomplete search box :
+when user press a key, you wait for 500ms before firing the request
+to see if she did not added an other letter. You can use cancel_delay
+for that :
+
+```coffee
+'Autocomplete search': { el: 'search_input', type: 'change', cancel_delay: 500 }
+```
+
+cancel_delay value is in milliseconds.
+
+
+## ensure_element
+
+To preserve `this` context as being the controller, event binding
+use event.target to retrieve element on which event occurs. This
+has implications. If you have :
+
+```html
+<a href="/do_stuff"><img src="my_image.jpg"></a>
+```
+
+and you bind event on the link, `event.target` may be the image
+element if you clicked on it. Darwin is aware of that on will
+always retrieve the element you asked when passing it to callback.
+
+But sometime, you may just want to have that target element.
+You can achieve this using `ensure_element` :
+
+```coffee
+'Remove clicked element': { el: 'my_block', type: 'click', ensure_element: false }
+```
+
+You probably should use delegation to filter what you want
+more precisely, though.
+
+
+# Progressive enhancement and graceful degradation
+
+Like Darwin.View, Darwin.Controller has a `run()` and
+a `destructor()` method.
+
+You may, for example, use `run()` to instantiate plugins.
+Put their teardown calls in `destructor()`.
+
+If you override `destructor()`, don't forget to call `super`,
+as controller destruction already handle a lot of stuff under
+the hood, like calling its view destructor, unbinding events
+and removing references to controller.
+
+

data/doc/introduction.md

@@ -0,0 +1,228 @@
+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.
+
+
+# Module
+
+At the core of darwin is the concept of module : a module
+is a specific feature, bound to a specific block of your
+page. This block will be the root of your feature and will
+act as a sandbox. Of course, you may decide to have the whole
+page content except layout as root, or you can choose to
+have a lot of modules which will speak to each other via
+events and callbacks. You can even have modules inside
+modules : that's up to you, darwin will support you anyway.
+
+A module is made of a controller and an optional (but almost
+always present) view. Controllers are declared on 
+`App.Controllers` and views are declared on `App.Views`. You
+can (and are expected to) create namespaces within those.
+
+The suggested file structure is this one :
+
+```
+app/assets/javascripts/
+  controllers/
+    users.coffee        # declare namespace : App.Controllers.Users = {}
+    users/
+      index.coffee      # Controller for index action
+      show.cofee        # Controller for show action
+      followers.coffee  # Controller for the "followers" block
+  views/
+    users.coffee        # declare namespace : App.Views.Users = {}
+    users/
+      index.coffee      # View for index action
+      show.cofee        # View for show action
+      followers.coffee  # View for the "followers" block
+```
+
+Your application.coffee file should `require_tree` views/ before
+controllers/, as controllers depend on views.
+
+You can easily create a module using the generator provided :
+
+```
+$ rails generate darwin admin_area/users/index
+
+      create  app/assets/javascripts/controllers/admin_area.coffee
+      create  app/assets/javascripts/views/admin_area.coffee
+      create  app/assets/javascripts/controllers/admin_area/users.coffee
+      create  app/assets/javascripts/views/admin_area/users.coffee
+      create  app/assets/javascripts/controllers/admin_area/users/index.coffee
+      create  app/assets/javascripts/views/admin_area/users/index.coffee
+```
+
+You can also create modules for an whole CRUD resource using camelcase
+form :
+
+```
+$ rails g darwinjs:assets AdminArea::Contact
+      create  app/assets/javascripts/controllers/admin_area.coffee
+      create  app/assets/javascripts/views/admin_area.coffee
+      create  app/assets/javascripts/controllers/admin_area/contacts.coffee
+      create  app/assets/javascripts/views/admin_area/contacts.coffee
+      create  app/assets/javascripts/controllers/admin_area/contacts/index.coffee
+      create  app/assets/javascripts/views/admin_area/contacts/index.coffee
+      create  app/assets/javascripts/controllers/admin_area/contacts/edit.coffee
+      create  app/assets/javascripts/views/admin_area/contacts/edit.coffee
+      create  app/assets/javascripts/controllers/admin_area/contacts/show.coffee
+      create  app/assets/javascripts/views/admin_area/contacts/show.coffee
+      create  app/assets/javascripts/controllers/admin_area/contacts/new.coffee
+      create  app/assets/javascripts/views/admin_area/contacts/new.coffee
+      create  app/assets/javascripts/controllers/admin_area/contacts/form.coffee
+      create  app/assets/javascripts/views/admin_area/contacts/form.coffee
+  ```
+
+Module can be autoloaded, using the `data-module` attribute :
+
+```
+<div id="users" data-module="Users.Index">
+...
+</div>
+```
+
+This will instantiate `App.Controllers.Users.Index` (which in turn
+instantiates its view).
+
+To learn more about autoloader, see [Loader](loader.md).
+
+
+# Controller
+
+A controller will handle anything event or request specific.
+An option set let you define all your events so you can see
+at one glance what the controller is about. See the
+options.events block here :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Toggle user block':      { el: 'user_trigger', type: 'click' }
+      'Show user info':         { el: 'user_more_trigger', type: 'click' }
+      'Delete user on server':  { el: 'user_delete', type: 'click' }
+  }
+
+
+  user_trigger_clicked: ->
+    if @view.users_shown()
+      @view.hide_users()
+    else
+      @view.show_users()
+
+
+  user_more_trigger_clicked: ( $link ) ->
+    @view.show_info_for( $link )
+
+  
+  user_delete_clicked: ( $link ) ->
+    if confirm( 'Really delete user ?' )
+      $.get( $link.attr( 'href' ), =>
+        @view.remove_user( $link )
+      )
+```
+
+Such self documentation will make sure any developer coming after
+you will understand immediately what the controller is about.
+
+As you probably noticed, callback names are automatically computed
+to match your event declaration, so `{ el: user_trigger, type: click}`
+call a `user_trigger_clicked` callback. Two parameters are passed
+to your callback : the jquery extended element and the event object.
+
+As most of the time, you want to stop an event after a click, this
+also is the default. So :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    View: App.Views.Users.Index
+
+    events:
+      'Toggle user block': { el: 'user_trigger', type: 'click' }
+  }
+
+  user_trigger_clicked: ( $link )->
+    @view.show_user( $link )
+```
+
+Is equivalent to, without darwin :
+
+```
+  $('.user_trigger' ).click( ( event ) ->
+    $link = $(this)
+    event.preventDefault()
+    show_user( $link )
+  )
+```
+
+Read about [Controller](controller.md) to learn more.
+
+# View
+
+A view handle everything DOM related. Its main purpose is
+to act as central point of configuration for selectors and
+to do DOM manipulation :
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    selectors:
+      close: 'a.close'
+      show_more: '.content .more a'
+      users:
+        'sel': '#users'
+        delete: 'a[data-method="delete"]'
+  }
+```
+
+Now, everywhere in your view methods, you can use `@get( 'close' )`
+to retrieve your close element. In controllers, you can use
+`@view.get( 'close' )` as well. This has two benefits :
+
+1. You have a single point of configuration. If you decide to
+change your DOM, you only have to change configuration here and
+it is reflected on your whole module.
+2. All elements are cached by default. Don't worry anymore about
+DOM hitting performances.
+
+A view is also responsible for setup / teardown your DOM, via
+its `run()` and `destructor()` method. `run()` is called when
+module is initialized ; `destructor()` is called when an error
+occurs (or you manually destruct the module).
+
+```coffee
+class App.Controllers.Users.Index extends Darwin.Controller
+  @options {
+    selectors:
+      submits: 'input[type="submit"]'
+  }
+
+  run: ->
+    @get( 'submits' ).hide()
+
+
+  destructor: ->
+    @get( 'submits' ).show()
+```
+
+So, `run()` is for progressive enhancement, and `destructor()` is
+for graceful degradation.
+
+This will ensure your featureis still # usable even if a
+javascript error occurs.
+
+To learn more about views, see [View](view.md).
+
+
+Finaly, Darwin add some sugar to coffeescript (namely: options pattern,
+mixins and class events). See [Base](base.md), darwin's base class to
+learn more.
+
+