eyeballs 0.3.7 → 0.4.1

data/CHANGELOG

@@ -1,3 +1,9 @@
+Tue Jul 6 2010
+- - - - - - - -
+- Housekeeping, add adapters, modules and drivers directories and relevant sub-directories
+- Add routing
+- use "meetings#index" style data-bind shortcuts instead of "meetings/index"
+
 Thu Jun 17 2010
 - - - - - - - -
 - Add "prefix" to Rails find method

data/Gemfile

@@ -0,0 +1,13 @@
+source :rubygems
+
+gem 'sinatra'
+gem 'thor'
+gem 'activesupport'
+
+group :development do
+  gem 'jeweler'
+end
+
+group :test do
+  gem 'rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,47 @@
+--- 
+dependencies: 
+  thor: 
+    group: 
+    - :default
+    version: ">= 0"
+  rspec: 
+    group: 
+    - :test
+    version: ">= 0"
+  sinatra: 
+    group: 
+    - :default
+    version: ">= 0"
+  jeweler: 
+    group: 
+    - :development
+    version: ">= 0"
+  activesupport: 
+    group: 
+    - :default
+    version: ">= 0"
+specs: 
+- activesupport: 
+    version: 2.3.8
+- json_pure: 
+    version: 1.4.3
+- gemcutter: 
+    version: 0.5.0
+- git: 
+    version: 1.2.5
+- rubyforge: 
+    version: 2.0.4
+- jeweler: 
+    version: 1.4.0
+- rack: 
+    version: 1.2.1
+- rspec: 
+    version: 1.3.0
+- sinatra: 
+    version: "1.0"
+- thor: 
+    version: 0.13.7
+hash: 17f409790dfc3ab7e279201874a3aab85e4c7c95
+sources: 
+- Rubygems: 
+    uri: http://gemcutter.org

data/README.md

@@ -6,15 +6,16 @@ eyeballs.js is a slim javascript library designed to sit on top of a javascript
 The goals are:
 
   * Organisation of client-side web app code using the Model-View-Controller pattern.
-  * Simple model implementation for client-side form validation.
-  * Rapid development of javascript actions using strong conventions.
+  * Simple model implementation for handling non event-related concerns.
+  * Simple routing layer for hash-tag change based navigation, preserving the back-button
+  * Rapid development of javascript apps using strong conventions.
   * Easing the pain of building fast, responsive interfaces.
   * Exploring the possibilities of offline web apps.
 
 The implementation is owes a lot to Ruby on Rails, but also attempts to be idiomatic javascript.
 
 Overview
-========
+--------
 
 eyeballs.js can sit on top of an already implemented web app with a well thought out object model. It can also be used to build standalone javascript apps, backed by HTML5 local storage or something like CouchDB.
 
@@ -22,14 +23,20 @@ eyeballs.js models are not necessarily one-to-one mapped to server side models u
 
 Finally, eyeballs.js is still a bit of an experiment. It's a quick implementation of a crazy idea to help make javascript code a little bit more organised.
 
+eyeballs.js is supposed to be both agnostic and modular. The code is broken down into modules, drivers and adapters.
+
+*Modules* add various parts of functionality, for example the code that powers the individual model, controller, routing and validation layers.
+*Drivers* add support for underlying javascript frameworks. Features that rely on event handling etc. are part of driver logic.
+*Adapters* provide an API to various persistence layers, eg. HTML5 Local Storage, a REST interface or a CouchDB instance.
+
 Getting Started
-===============
+---------------
 
 eyeballs.js is packaged into modules, according to dependencies.
 
-The main lib, o\_O.js, has no dependencies and lets you use eyeballs.js models standalone.
+The main library has no dependencies and lets you use eyeballs.js models standalone.
 
-Standalone, o\_O.js doesn't do much: it provides the o\_O() function for initializing models and some validations.
+Standalone, eyeballs.js doesn't do much: it provides the o\_O() function for initializing models and some validations.
 
 At a very minimum, you should choose an adapter. There are a few to choose from:
 
@@ -38,7 +45,7 @@ At a very minimum, you should choose an adapter. There are a few to choose from:
   - **o\_O.couchdb** - persist records to a local CouchDB instance, for building MVC CouchApps, for example.
   - **o\_O.rails** - An adapter for persisting models to a backend powered by Rails, or using Rails-style RESTful routing.
 
-Finally, you need a controller. The first release of eyeballs.js includes a controller initializer for jQuery. This adapter happens to depend on jQuery.livequery, for reasons of magic.
+Finally, you need a controller. The first release of eyeballs.js includes a controller as part of the jQuery driver. This adapter also depends on jQuery.livequery.
 
 You can also use a javascript templating language. Mustache.js fits this need quite nicely.
 
@@ -51,17 +58,23 @@ Wrapping that all up, to use eyeballs.js with the Rails adapter and jQuery:
     <!-- Mustache for templating -->
     <script src="mustache.js"></script>
     
-    <!-- eyeballs.js -->
+    <!-- eyeballs.js basic -->
     <script src="o_O.js"></script>
-    <script src="jquery.o_O.js"></script>
+    <script src="modules/o_O.model.js"></script>
+    <script src="modules/o_O.validations.js"></script>
+    
+    <!-- eyeballs.js jquery driver for controller logic -->
+    <script src="drivers/jquery/modules/o_O.controller.js"></script>
+    <script src="drivers/jquery/modules/o_O.support.js"></script>
+    <script src="drivers/jquery/modules/o_O.routes.js"></script>
     
-    <!-- Rails adapter -->
-    <script src="o_O.rails.js"></script>
+    <!-- REST adapter -->
+    <script src="drivers/jquery/adapters/o_O.rest.js"></script>
 
 Badabing, badaboom! You're now ready to start creating some models and controllers.
 
 Generators
-==========
+----------
 
 If you install the eyeballs.js Ruby gem, you can use the eyeballs command to generate eyeballs.js apps, models and controllers:
 
@@ -89,7 +102,7 @@ This will generate a `posts.html`, a `post.js` and a `posts_controller.js`.
 If the generator detects a "public" directory when you run it, it will install into public/javascripts.
 
 Models
-======
+------
 
 You define a model by passing a name and function to the eyeballs ( o_O ) function (pronounced 'eep eep'). As inspired by Rails, model definitions are capitalised. Note, however, that the new prefix is not used.
 
@@ -181,7 +194,7 @@ Finding, saving, updating and deleting. With callbacks? Easy peasy:
 There's a strong emphasis on callbacks: since any persisting to backends should be done asynchronously.
 
 Controllers
-===========
+-----------
 
 An eyeballs.js controller is also initialized with the eyeballs function, by passing a string name and an object containing the controller actions.
 
@@ -196,6 +209,36 @@ An eyeballs.js controller is also initialized with the eyeballs function, by pas
 
 Again, this looks nice and familiar. Dead, dead simple.
 
+### Calling Controller Actions & Binding Events ###
+
+There are several ways to bind events to controller actions.
+
+#### Calling Directly ####
+
+The simplest way to call controller actions is to bind them directly. From the above example, you can simply call:
+
+    PostsController.new()
+
+...once you have initialized your controller.
+
+#### Routing ####
+
+You can use the eyeballs.js router to bind events to changes in the URL hash. This is particularly effective for graceful degradation, as well as preserving the back button history.
+
+Your `config/routes.js` file would look something like this:
+
+    o_O.routes.draw(function(map){
+      map.match('/posts/new/', {to: 'posts#new'})
+    })
+
+You can now bind this to particular links, by adding the `data-ajax-history` attribute to your `a` elements:
+
+    <a href="/posts/new" data-ajax-history="true">Click Me!</a>
+    
+This link will now call `PostsController.new()` when it is clicked.
+
+#### Binding actions to events ####
+
 To bind events to these controller actions, use the data-controller and data-action attributes:
 
     <a href="/posts/new" data-controller="posts" data-action="new">Click me!</a>
@@ -231,7 +274,9 @@ Finally, in shorthand only, you can bind multiple events to a single element:
 Isn't that cool?
     
 Putting it all together
-=======================
+-----------------------
+
+TODO: The demo app isn't working right now. There should be a generator to generate a new demo app after each release.
 
 There's a small demo app included in this package, a simple app for adding personal reviews. It's a simple Sinatra app, so you can run it with:
 
@@ -290,12 +335,12 @@ That's all for now!
     
 
 Running the tests
-=================
+-----------------
 
 eyeballs.js uses QUnit for in-browser testing. Just load the files in the test directory in any browser to run them.
 
 About me
-========
+--------
 
 I'm Paul Campbell. I'm an avid web developer. Follow my ramblings at [http://www.pabcas.com](http://www.pabcas.com)
 

data/Rakefile

@@ -27,7 +27,7 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|
     s.name = "eyeballs"
-    s.version = "0.3.7"
+    s.version = "0.4.1"
     s.author = "Paul Campbell"
     s.email = "paul@rslw.com"
     s.homepage = "http://www.github.com/paulca/eyeballs.js"

data/dist/jquery/jquery.ba-hashchange.js

@@ -0,0 +1,244 @@
+/*!
+ * jQuery hashchange event - v1.2 - 2/11/2010
+ * http://benalman.com/projects/jquery-hashchange-plugin/
+ * 
+ * Copyright (c) 2010 "Cowboy" Ben Alman
+ * Dual licensed under the MIT and GPL licenses.
+ * http://benalman.com/about/license/
+ */
+
+// Script: jQuery hashchange event
+//
+// *Version: 1.2, Last updated: 2/11/2010*
+// 
+// Project Home - http://benalman.com/projects/jquery-hashchange-plugin/
+// GitHub       - http://github.com/cowboy/jquery-hashchange/
+// Source       - http://github.com/cowboy/jquery-hashchange/raw/master/jquery.ba-hashchange.js
+// (Minified)   - http://github.com/cowboy/jquery-hashchange/raw/master/jquery.ba-hashchange.min.js (1.1kb)
+// 
+// About: License
+// 
+// Copyright (c) 2010 "Cowboy" Ben Alman,
+// Dual licensed under the MIT and GPL licenses.
+// http://benalman.com/about/license/
+// 
+// About: Examples
+// 
+// This working example, complete with fully commented code, illustrate one way
+// in which this plugin can be used.
+// 
+// hashchange event - http://benalman.com/code/projects/jquery-hashchange/examples/hashchange/
+// 
+// About: Support and Testing
+// 
+// Information about what version or versions of jQuery this plugin has been
+// tested with, what browsers it has been tested in, and where the unit tests
+// reside (so you can test it yourself).
+// 
+// jQuery Versions - 1.3.2, 1.4.1, 1.4.2pre
+// Browsers Tested - Internet Explorer 6-8, Firefox 2-3.7, Safari 3-4, Chrome, Opera 9.6-10.1.
+// Unit Tests      - http://benalman.com/code/projects/jquery-hashchange/unit/
+// 
+// About: Known issues
+// 
+// While this jQuery hashchange event implementation is quite stable and robust,
+// there are a few unfortunate browser bugs surrounding expected hashchange
+// event-based behaviors, independent of any JavaScript window.onhashchange
+// abstraction. See the following examples for more information:
+// 
+// Chrome: Back Button - http://benalman.com/code/projects/jquery-hashchange/examples/bug-chrome-back-button/
+// Firefox: Remote XMLHttpRequest - http://benalman.com/code/projects/jquery-hashchange/examples/bug-firefox-remote-xhr/
+// WebKit: Back Button in an Iframe - http://benalman.com/code/projects/jquery-hashchange/examples/bug-webkit-hash-iframe/
+// Safari: Back Button from a different domain - http://benalman.com/code/projects/jquery-hashchange/examples/bug-safari-back-from-diff-domain/
+// 
+// About: Release History
+// 
+// 1.2   - (2/11/2010) Fixed a bug where coming back to a page using this plugin
+//         from a page on another domain would cause an error in Safari 4. Also,
+//         IE6/7 Iframe is now inserted after the body (this actually works),
+//         which prevents the page from scrolling when the event is first bound.
+//         Event can also now be bound before DOM ready, but it won't be usable
+//         before then in IE6/7.
+// 1.1   - (1/21/2010) Incorporated document.documentMode test to fix IE8 bug
+//         where browser version is incorrectly reported as 8.0, despite
+//         inclusion of the X-UA-Compatible IE=EmulateIE7 meta tag.
+// 1.0   - (1/9/2010) Initial Release. Broke out the jQuery BBQ event.special
+//         window.onhashchange functionality into a separate plugin for users
+//         who want just the basic event & back button support, without all the
+//         extra awesomeness that BBQ provides. This plugin will be included as
+//         part of jQuery BBQ, but also be available separately.
+
+(function($,window,undefined){
+  '$:nomunge'; // Used by YUI compressor.
+  
+  // Method / object references.
+  var fake_onhashchange,
+    jq_event_special = $.event.special,
+    
+    // Reused strings.
+    str_location = 'location',
+    str_hashchange = 'hashchange',
+    str_href = 'href',
+    
+    // IE6/7 specifically need some special love when it comes to back-button
+    // support, so let's do a little browser sniffing..
+    browser = $.browser,
+    mode = document.documentMode,
+    is_old_ie = browser.msie && ( mode === undefined || mode < 8 ),
+    
+    // Does the browser support window.onhashchange? Test for IE version, since
+    // IE8 incorrectly reports this when in "IE7" or "IE8 Compatibility View"!
+    supports_onhashchange = 'on' + str_hashchange in window && !is_old_ie;
+  
+  // Get location.hash (or what you'd expect location.hash to be) sans any
+  // leading #. Thanks for making this necessary, Firefox!
+  function get_fragment( url ) {
+    url = url || window[ str_location ][ str_href ];
+    return url.replace( /^[^#]*#?(.*)$/, '$1' );
+  };
+  
+  // Property: jQuery.hashchangeDelay
+  // 
+  // The numeric interval (in milliseconds) at which the <hashchange event>
+  // polling loop executes. Defaults to 100.
+  
+  $[ str_hashchange + 'Delay' ] = 100;
+  
+  // Event: hashchange event
+  // 
+  // Fired when location.hash changes. In browsers that support it, the native
+  // window.onhashchange event is used (IE8, FF3.6), otherwise a polling loop is
+  // initialized, running every <jQuery.hashchangeDelay> milliseconds to see if
+  // the hash has changed. In IE 6 and 7, a hidden Iframe is created to allow
+  // the back button and hash-based history to work.
+  // 
+  // Usage:
+  // 
+  // > $(window).bind( 'hashchange', function(e) {
+  // >   var hash = location.hash;
+  // >   ...
+  // > });
+  // 
+  // Additional Notes:
+  // 
+  // * The polling loop and Iframe are not created until at least one callback
+  //   is actually bound to 'hashchange'.
+  // * If you need the bound callback(s) to execute immediately, in cases where
+  //   the page 'state' exists on page load (via bookmark or page refresh, for
+  //   example) use $(window).trigger( 'hashchange' );
+  // * The event can be bound before DOM ready, but since it won't be usable
+  //   before then in IE6/7 (due to the necessary Iframe), recommended usage is
+  //   to bind it inside a $(document).ready() callback.
+  
+  jq_event_special[ str_hashchange ] = $.extend( jq_event_special[ str_hashchange ], {
+    
+    // Called only when the first 'hashchange' event is bound to window.
+    setup: function() {
+      // If window.onhashchange is supported natively, there's nothing to do..
+      if ( supports_onhashchange ) { return false; }
+      
+      // Otherwise, we need to create our own. And we don't want to call this
+      // until the user binds to the event, just in case they never do, since it
+      // will create a polling loop and possibly even a hidden Iframe.
+      $( fake_onhashchange.start );
+    },
+    
+    // Called only when the last 'hashchange' event is unbound from window.
+    teardown: function() {
+      // If window.onhashchange is supported natively, there's nothing to do..
+      if ( supports_onhashchange ) { return false; }
+      
+      // Otherwise, we need to stop ours (if possible).
+      $( fake_onhashchange.stop );
+    }
+    
+  });
+  
+  // fake_onhashchange does all the work of triggering the window.onhashchange
+  // event for browsers that don't natively support it, including creating a
+  // polling loop to watch for hash changes and in IE 6/7 creating a hidden
+  // Iframe to enable back and forward.
+  fake_onhashchange = (function(){
+    var self = {},
+      timeout_id,
+      iframe,
+      set_history,
+      get_history;
+    
+    // Initialize. In IE 6/7, creates a hidden Iframe for history handling.
+    function init(){
+      // Most browsers don't need special methods here..
+      set_history = get_history = function(val){ return val; };
+      
+      // But IE6/7 do!
+      if ( is_old_ie ) {
+        
+        // Create hidden Iframe after the end of the body to prevent initial
+        // page load from scrolling unnecessarily.
+        iframe = $('<iframe src="javascript:0"/>').hide().insertAfter( 'body' )[0].contentWindow;
+        
+        // Get history by looking at the hidden Iframe's location.hash.
+        get_history = function() {
+          return get_fragment( iframe.document[ str_location ][ str_href ] );
+        };
+        
+        // Set a new history item by opening and then closing the Iframe
+        // document, *then* setting its location.hash.
+        set_history = function( hash, history_hash ) {
+          if ( hash !== history_hash ) {
+            var doc = iframe.document;
+            doc.open().close();
+            doc[ str_location ].hash = '#' + hash;
+          }
+        };
+        
+        // Set initial history.
+        set_history( get_fragment() );
+      }
+    };
+    
+    // Start the polling loop.
+    self.start = function() {
+      // Polling loop is already running!
+      if ( timeout_id ) { return; }
+      
+      // Remember the initial hash so it doesn't get triggered immediately.
+      var last_hash = get_fragment();
+      
+      // Initialize if not yet initialized.
+      set_history || init();
+      
+      // This polling loop checks every $.hashchangeDelay milliseconds to see if
+      // location.hash has changed, and triggers the 'hashchange' event on
+      // window when necessary.
+      (function loopy(){
+        var hash = get_fragment(),
+          history_hash = get_history( last_hash );
+        
+        if ( hash !== last_hash ) {
+          set_history( last_hash = hash, history_hash );
+          
+          $(window).trigger( str_hashchange );
+          
+        } else if ( history_hash !== last_hash ) {
+          window[ str_location ][ str_href ] = window[ str_location ][ str_href ].replace( /#.*/, '' ) + '#' + history_hash;
+        }
+        
+        timeout_id = setTimeout( loopy, $[ str_hashchange + 'Delay' ] );
+      })();
+    };
+    
+    // Stop the polling loop, but only if an IE6/7 Iframe wasn't created. In
+    // that case, even if there are no longer any bound event handlers, the
+    // polling loop is still necessary for back/next to work at all!
+    self.stop = function() {
+      if ( !iframe ) {
+        timeout_id && clearTimeout( timeout_id );
+        timeout_id = 0;
+      }
+    };
+    
+    return self;
+  })();
+  
+})(jQuery,this);