handlers-js 0.0.1

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+src/handlers.js
+spec/javascripts/HandlersSpec.js
+spec/javascripts/TriggerSpec.js

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+before_install:
+ - gem install bundler
+ - npm install coffee-script
+ - "export DISPLAY=:99.0"
+ - "sh -e /etc/init.d/xvfb start"
+
+rvm:
+  - 1.9.3
+
+branches:
+  only:
+    - master
+
+notifications:
+  email:
+    recipients:
+      - handlers@erichmenge.com

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Erich Menge
+
+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,107 @@
+# Handlers-js [![Build Status](https://travis-ci.org/erichmenge/handlers-js.png?branch=master)](https://travis-ci.org/erichmenge/handlers-js)
+
+Handlers-js provides an easy to use, dead simple, unobtrusive Javascript modularization through the Rails asset pipeline.
+
+What's that mean? That means all you need to do is register your handler, and then call it with `data-handler="MyHandler"` on your HTML tags.
+
+## Features
+
+* Works "out of the box" with Turbolinks
+* Easy setup with pjax
+* Isolation. Code isn't executed where it doesn't belong. No worrying about code leaking by binding to different styles and element IDs.
+* Consistent patterns.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'handlers-js'
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+CoffeeScript is provided via the asset pipeline. A single class called `Handlers` is created.
+Your asset manifest should look something like this:
+
+```
+//= require turbolinks
+//= require handlers
+//= require_tree .
+```
+
+**IMPORTANT** If you're using Turbolinks, make sure it is included first so that Handlers-js knows about it.
+
+Now, simply create your CoffeeScript files like so:
+
+```
+Handlers.register 'TypeAhead', class
+  constructor: (el) ->
+    url       = $(el).data('typeahead-url')
+    property  = $(el).data('typeahead-property')
+    value     = $(el).data('typeahead-value')
+
+    $(el).typeahead
+      source: (typeahead, query) ->
+        $.ajax
+          dataType: 'json'
+          url: url + query
+          success: (data) ->
+            typeahead.process(data)
+      property: property
+      onselect: (val) ->
+        $(el).val(val.name)
+        $(el).closest('form').submit()
+
+  destroy: ->
+    doSomeCleanup()
+```
+
+Then, in your HTML:
+
+```
+<span data-handler="TypeAhead" data-typeahead-url="..." data-typeahead-property="..." data-typeahead-value="...">
+  ...
+</span>
+```
+
+Need to use more than one Handler on a particular element? No problem. They are comma separated.
+
+```
+<span data-handler="TypeAhead,SomethingSpecial" ...></span>
+```
+
+### If you're not using Turbolinks
+
+If you're not using Turbolinks, fear not. Handlers are still easy to use.
+
+Handlers responds to three triggers:
+
+* handlers:pageChanged  - pageChanged should be triggered when the page is loaded for the first time, this will load any handler found on the page.
+* handlers:pageUpdating - This should be triggered when the page is changing, it must be passed the scope it should perform on
+* handlers:pageUpdated  - This should be triggered when the page change is complete, it must be passed the scope it should perform on
+
+A pjax example:
+
+``` main.coffee
+
+$(document).on 'pjax:start', ->
+  $(document).trigger 'handlers:pageUpdating', '[data-pjax-container]'
+
+$(document).on 'pjax:end', ->
+  $(document).trigger 'handlers:pageUpdated', '[data-pjax-container]'
+
+$ ->
+  $(document).trigger 'handlers:pageChanged'
+```
+
+
+## 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,17 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'jasmine'
+  load 'jasmine/tasks/jasmine.rake'
+rescue LoadError
+  task :jasmine do
+    abort "Jasmine is not available. In order to run jasmine, you must: (sudo) gem install jasmine"
+  end
+end
+
+task :build_js do
+  `coffee -o src -c lib/assets/javascripts/handlers.coffee`
+  `coffee -c spec/javascripts`
+end
+
+task :default => [:build_js, 'jasmine:ci']

data/handlers-js.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |gem|
+  gem.name          = "handlers-js"
+  gem.version       = "0.0.1"
+  gem.authors       = ["Erich Menge"]
+  gem.email         = ["erich.menge@me.com"]
+  gem.description   = %q{Easy, modular UJS for your Rails apps}
+  gem.summary       = %q{Easy, modular UJS for your Rails apps}
+  gem.homepage      = "https://github.com/erichmenge/handlers-js"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('jasmine')
+end

data/lib/assets/javascripts/handlers.coffee

@@ -0,0 +1,46 @@
+class @Handlers
+  @handlers = {}
+
+  @register: (handler, registered_class) ->
+    throw "No constructor on " + handler unless registered_class.constructor
+    @handlers[handler] = registered_class
+
+  @instantiate: (handlers, element) ->
+    handlers = handlers.replace(/\s/g, '').split(',')
+    element.handlers = []
+    $.each handlers, (index, handler) =>
+      if @handlers[handler]
+        instance = new @handlers[handler](element)
+        element.handlers.push instance
+      else
+        throw "Unknown handler " + handler
+
+  @destroy: (instances) ->
+    $.each instances, (index, instance) ->
+      instance.destroy() if instance.destroy
+
+  @unregister_all: ->
+    @handlers = {}
+
+$(document).on 'handlers:pageChanged', ->
+  $('[data-handler]').each ->
+    Handlers.instantiate $(this).attr('data-handler'), this
+
+$(document).on 'handlers:pageUpdated', (event, scope) ->
+  $(scope).find('[data-handler]').each ->
+    Handlers.instantiate $(this).attr('data-handler'), this
+
+$(document).on 'handlers:pageUpdating', (event, scope) ->
+  $(scope).find('[data-handler]').each ->
+    Handlers.destroy @handlers if @handlers
+    delete @handlers if @handlers
+
+if typeof(Turbolinks) != undefined
+  $(document).on 'page:fetch', ->
+    $(document).trigger 'handlers:pageUpdating', 'body'
+
+  $(document).on 'page:change', ->
+    $(document).trigger 'handlers:pageUpdated', 'body'
+
+  $ ->
+    $(document).trigger 'handlers:pageChanged'

data/lib/handlers-js.rb

@@ -0,0 +1,5 @@
+module Handlers
+  module Rails
+    class Engine < ::Rails::Engine; end
+  end
+end

data/spec/javascripts/HandlersSpec.coffee

@@ -0,0 +1,56 @@
+describe "Handlers", =>
+  el = null
+
+  beforeEach =>
+    el = {}
+
+  afterEach =>
+    Handlers.unregister_all()
+
+  it "should be defined", ->
+    expect(Handlers).toBeDefined()
+
+  it "should register a handler", ->
+    Handlers.register 'Foo', class
+    expect(Handlers.handlers['Foo']).toBeDefined()
+
+  describe  "multiple handlers", ->
+
+    beforeEach ->
+      Handlers.register 'Foo', class
+      Handlers.register 'Bar', class
+
+    afterEach ->
+      expect(Handlers.handlers['Foo']).toBeDefined()
+      expect(Handlers.handlers['Bar']).toBeDefined()
+
+    it "should instantiate them", ->
+      expect(-> Handlers.instantiate('Foo, Bar', el)).not.toThrow()
+
+    it "should allow spaces", ->
+      expect(-> Handlers.instantiate('Foo, Bar', el)).not.toThrow()
+
+  it "should attach to an element", ->
+    Handlers.register 'Foo', class
+    expect(el.handlers).not.toBeDefined()
+    expect(-> Handlers.instantiate('Foo', el)).not.toThrow()
+    expect(el.handlers).toBeDefined()
+
+  it "should throw if the handler isn't known", ->
+    expect(-> Handlers.instantiate('Foo', el)).toThrow()
+
+  it "should destroy if the destroy function is available", ->
+    Handlers.register 'Foo', class
+      constructor: (el) ->
+      destroy: ->
+
+    Handlers.instantiate('Foo', el)
+    spyOn(el.handlers[0], 'destroy')
+    Handlers.destroy(el.handlers)
+    expect(el.handlers[0].destroy).toHaveBeenCalled()
+
+  it "should not throw if there is not a destructor", ->
+    Handlers.register 'Foo', class
+    Handlers.instantiate 'Foo', el
+    expect(-> Handlers.destroy(el.handlers)).not.toThrow()
+

data/spec/javascripts/TriggerSpec.coffee

@@ -0,0 +1,51 @@
+describe 'Triggers', =>
+  beforeEach =>
+    $('body').append('<span style="display: none"; id="foospan" data-handler="Foo"></span>')
+    Handlers.register 'Foo', class
+      constructor: (el) ->
+        @el = $(el)
+        $(el).html('filled')
+      destroy: ->
+        @el.html("destroyed")
+
+  afterEach =>
+    $('#foospan').remove()
+    Handlers.unregister_all
+
+  describe 'When the page changes', ->
+    it 'should trigger the event', ->
+      $(document).trigger 'handlers:pageChanged'
+      expect($('#foospan').html()).toEqual "filled"
+
+  describe 'When page is updated', ->
+    it 'should trigger the event', ->
+      $(document).trigger 'handlers:pageUpdated', 'body'
+      expect($('#foospan').html()).toEqual "filled"
+
+    it 'should maintain scope', ->
+      $('#foospan').html('')
+      $('body').append(
+        '<span style="display: none"; id="onlyscope">
+          <span style="display: none"; id="scopedspan" data-handler="Foo"></span>
+        </span>'
+      )
+      $(document).trigger 'handlers:pageUpdated', '#onlyscope'
+      expect($('#foospan').html()).toEqual ""
+      expect($('#scopedspan').html()).toEqual "filled"
+
+  describe 'When page is changing', ->
+    it 'should destroy', ->
+      $(document).trigger('handlers:pageChanged')
+      $(document).trigger('handlers:pageUpdating', 'body')
+      expect($('#foospan').html()).toEqual "destroyed"
+
+    it 'should maintain scope', ->
+      $('body').append(
+        '<span style="display: none"; id="onlyscope">
+          <span style="display: none"; id="scopedspan" data-handler="Foo"></span>
+        </span>'
+      )
+      $(document).trigger('handlers:pageChanged')
+      $(document).trigger('handlers:pageUpdating', '#onlyscope')
+      expect($('#foospan').html()).toEqual "filled"
+      expect($('#scopedspan').html()).toEqual "destroyed"

data/spec/javascripts/support/jasmine.yml

@@ -0,0 +1,75 @@
+# src_files
+#
+# Return an array of filepaths relative to src_dir to include before jasmine specs.
+# Default: []
+#
+# EXAMPLE:
+#
+# src_files:
+#   - lib/source1.js
+#   - lib/source2.js
+#   - dist/**/*.js
+#
+src_files:
+    - src/jquery-1.8.3.js
+    - src/handlers.js
+
+# stylesheets
+#
+# Return an array of stylesheet filepaths relative to src_dir to include before jasmine specs.
+# Default: []
+#
+# EXAMPLE:
+#
+# stylesheets:
+#   - css/style.css
+#   - stylesheets/*.css
+#
+stylesheets:
+
+# helpers
+#
+# Return an array of filepaths relative to spec_dir to include before jasmine specs.
+# Default: ["helpers/**/*.js"]
+#
+# EXAMPLE:
+#
+# helpers:
+#   - helpers/**/*.js
+#
+helpers:
+  - 'helpers/**/*.js'
+# spec_files
+#
+#  Return an array of filepaths relative to spec_dir to include.
+# Default: ["**/*[sS]pec.js"]
+#
+# EXAMPLE:
+#
+# spec_files:
+#   - **/*[sS]pec.js
+#
+spec_files:
+  - '**/*[sS]pec.js'
+
+# src_dir
+#
+# Source directory path. Your src_files must be returned relative to this path. Will use root if left blank.
+# Default: project root
+#
+# EXAMPLE:
+#
+# src_dir: public
+#
+src_dir:
+
+# spec_dir
+#
+# Spec directory path. Your spec_files must be returned relative to this path.
+# Default: spec/javascripts
+#
+# EXAMPLE:
+#
+# spec_dir: spec/javascripts
+#
+spec_dir: