ajax 0.1.3 → 0.1.4

data/README.rdoc

@@ -2,7 +2,7 @@
 
 <b>A Ruby on Rails plugin to augment a traditional Rails application with a completely AJAX frontend, while transparently handling issues important to both the enterprise and end users, such as testing, SEO and browser history.</b>
 
-The Ajax philosophy is that you should not have to develop for AJAX:  Your code shouldn't change; your tests shouldn't change; and the way Google sees your site shouldn't change.  (Coming soon, this link {AJAX site crawling specification}[http://code.google.com/web/ajaxcrawling/docs/getting-started.html] may obviate that.)
+The Ajax philosophy is that you shouldn't have to develop for AJAX:  Your code shouldn't change; your tests shouldn't change; and the way Google sees your site shouldn't change.
 
 The beauty of Ajax is that your Rails application only ever sees traditional requests, so it does not have to be "Ajax aware".
 
@@ -10,8 +10,6 @@ Ajax is being used live in production on altnet.com[http://altnet.com], if you w
 
 == Install
 
-After installing, create layouts in <tt>app/views/layouts/ajax/</tt> that mimic your existing layouts.  See <b>Request Handling -> Layouts</b>.
-
 === Rails 3
 
 1. Add the gem to your <tt>Gemspec</tt>
@@ -47,20 +45,31 @@ After installing, create layouts in <tt>app/views/layouts/ajax/</tt> that mimic
 
 === Sample Output
 
-   $ rake ajax:install
-   created: app/controllers/ajax_controller.rb
-   created: app/views/ajax/framework.html.erb
-   created: config/initializers/ajax.rb
-   created: public/javascripts/ajax.js
-   created: public/javascripts/jquery.address-1.2rc.js
-   created: public/javascripts/jquery.address-1.2rc.min.js
-   created: public/javascripts/jquery.json-2.2.min.js
-   created: public/images/loading-icon-small.gif
-
-   $ rake ajax:install
-   skipped: app/controllers/ajax_controller.rb exists!
-   skipped: app/views/ajax/framework.html.erb exists!
-   ...
+  $ rake ajax:install
+  created: app/controllers/ajax_controller.rb
+  created: app/views/ajax/framework.html.erb
+  created: config/initializers/ajax.rb
+  created: public/javascripts/ajax.js
+  created: public/javascripts/jquery.address-1.2rc.js
+  created: public/javascripts/jquery.address-1.2rc.min.js
+  created: public/javascripts/jquery.json-2.2.min.js
+  created: public/images/ajax-loading.gif
+
+  $ rake ajax:install
+  skipped: app/controllers/ajax_controller.rb exists!
+  skipped: app/views/ajax/framework.html.erb exists!
+  ...
+
+=== Post Install
+
+1. Create layouts in <tt>app/views/layouts/ajax/</tt> that mimic your existing layouts.  See <b>Request Handling -> Layouts</b>.
+2. Instantiate an instance of the Ajax class in <tt>application.js</tt>.  For example:
+
+      window.ajax = new Ajax({
+        default_container: '#main',
+        enabled: true,
+        lazy_load_assets: false
+      });
    
 == Introduction
 
@@ -156,6 +165,10 @@ Please browse the {API documentation at rDoc.info}[http://rdoc.info/projects/kjv
 
 It is important to be able to disable the plugin when you don't want it interfering, like when you are testing.  You will also want to ensure that your site's JavaScript still works when the plugin is disabled.
 
+<b>If Ajax is disabled</b>, your site will act like a traditional Rails application.  Because each request will be a traditional request, <b>callbacks specified in the Ajax-Info header will not be parsed by the browser, and so will not execute.</b>
+
+<b>Callbacks added directly to the <tt>window.ajax</tt> instance will still be executed, and they will execute immediately.</b>
+
 To disable the plugin in your environment file:
   
   # config/environments/test.rb
@@ -252,40 +265,118 @@ See {ajax/two_column.html.haml}[http://gist.github.com/373133#file_two_column.ht
 
 == Lazy-loading Assets
 
+<b>KJV 2010-04-22:</b>  Browser support for callbacks (specifically the problem of calling them only *after* all assets have loaded) is patchy/inconsistent at this time so lazy-loading is not recommended.  It has been disabled by default.  Once all browsers can be supported this may change.
+
+<b>The recommended way of dynamically enabling/disabling lazy loading:</b>
+
+  # environment/initializer
+  Ajax.lazy_load_assets = false # or true
+
+  # application layout (HAML example)
+  :javascript
+    var AJAX_LAZY_LOAD_ASSETS = #{Ajax.lazy_load_assets?};
+
+  if !Ajax.lazy_load_assets
+    include_all_assets
+  end
+
+  # application.js
+  window.ajax = new Ajax({
+    lazy_load_assets: window.AJAX_LAZY_LOAD_ASSETS !== undefined ? window.AJAX_LAZY_LOAD_ASSETS : false
+  });
+
 Use <code>ajax_header :assets { :stylesheets => [], :javascripts => [] }</code> to define assets that a page depends on.  These assets will be loaded before the response content is inserted into the DOM.
 
-Assets that have already been loaded are not loaded again, so it is safe to always include the assets header.
+1. Assets that have already been loaded are not loaded again
+2. Assets that are loaded, remain loaded (watch out for CSS conflicts and JS memory leaks)
+3. If lazy-loading assets is disabled, assets in the <tt>Ajax-Info</tt> header are ignored, but callbacks are still executed.
 
-If you need to perform operations on the new content, or instantiate objects defined in the dependent assets, use <b>JavaScript Callbacks</b>.
+Often you will need to perform some DOM manipulations on the newly inserted content, or instantiate JavaScript objects that are defined in a lazy-loaded JS file.  To execute some JavaScript after all assets have been loaded and the new content has been inserted, use <b>JavaScript Callbacks</b>.
 
-== <a name="callbacks">JavaScript Callbacks</a>
+== JavaScript Callbacks
 
-To add a JavaScript callback(s) that will be executed <b>after any assets in <tt>Ajax-Info['assets']</tt> have been loaded</b> you can pass it in the header with the following.  These callbacks are executed in the global scope:
+JavaScript callbacks can be added to the response and will be executed after any assets in <tt>Ajax-Info['assets']</tt> have been loaded.  (If lazy loading assets is disabled, they are executed immediately.)
 
-  ajax_header, :callbacks, 'window.player.init();'
-  
-Alternatively you may want to bind callbacks directly to the <tt>window.ajax</tt> object in your view:
+You can bind callbacks directly to the <tt>window.ajax</tt> object in your view, for example, in HAML we could have:
+
+  :javascript
+    window.ajax.onLoad(function() {
+      window.juggernaut = new window.Juggernaut(#{juggernaut_options.to_json});
+      window.liveFeed.init();
+    });
 
-  # app/views/activity/recent.html.haml
-  window.ajax.onLoad('window.juggernaut = new Juggernaut(#{juggernaut_options.to_json}); window.liveFeed.init();');
-  window.ajax.prependOnLoad("$(document).trigger('player.init');");
+    window.ajax.prependOnLoad(function() {
+      $(document).trigger('player.init');
+    });
   
-When we add the juggernaut callback it must be a string because Juggernaut is defined in one of the assets that hasn't been loaded yet.
+In the <tt>onLoad</tt> callback I'm scoping everything to <tt>window</tt> to <b>avoid scoping issues</b> in different browsers.
 
-<tt>window.ajax.prependOnLoad</tt> adds the callback to the front of the queue.  Callbacks can also be functions, for example:
+<b><tt>window.ajax.prependOnLoad</tt><b> adds the callback to the front of the queue.
+
+Alternatively callbacks can be passed as a list of Strings in the <tt>Ajax-Info</tt> header using the <tt>ajax_header</tt> helper:
+
+  ajax_header, :callbacks, 'window.player.init();'
+
+These callbacks are executed in the global scope.  This method of adding callbacks is not recommended for two reasons:
+
+1. Safari has trouble with some String callbacks.
+2. If Ajax is disabled, these callbacks will not be executed, because the <tt>Ajax-Info</tt> header will not be set.
+
+   However, callbacks added directly to the <tt>window.ajax</tt> instance will still be executed, and they will execute immediately, so your code continues to work as expected.
+
+== JavaScript Gotchas
+
+Most of the problems you will likely encounter from a change to Ajax will be JavaScript related.  These problems become more noticeable for the following reasons:
+
+1. JavaScript that has been loaded, remains loaded for a very long time.  This can lead to:
+   1. Memory leaks
+   2. Callbacks executing ad infinitum, likely on content that has since been replaced.
+2. Inconsistent browser handling of JavaScript returned via AJAX:
+   1. JavaScript in AJAX response is executed in local scope
+   1. Safari {scoping issues}[http://forum.jquery.com/topic/dealing-with-globaleval-and-safari-suggestion-for-a-better-approach]
+   3. {Inconsistent support for <tt>script.onload</tt>}[http://unixpapa.com/js/dyna.html]
+3. Badly written JavaScript libraries
+
+To ease some of the pain, observe some of the following advice:
+
+1. Never use {<tt>document.write</tt>}[http://javascript.crockford.com/script.html]
+2. Use <tt>window</tt> to avoid scoping issues.
+3. Modify your third-party JavaScript libraries to also assign classes etc to <tt>window</tt>.
+4. Use jQuery {live events}[http://api.jquery.com/live/]
+5. Dynamically turn off repeating callbacks e.g.
+
+    function my_repetitive_callback() {
+      if ($(selector).size() == 0) {
+        // Turn off the interval
+        if (object.interval_id !== undefined) {
+          clearInterval(object.interval_id);
+          object.interval_id = undefined;
+        }
+      } else {
+        $(selector).do().some().jquery().kung().foo();
+      }
+    }
+
+    // Start the interval.  Do this whenever a page is rendered
+    // that has content we want to work with.  This will start
+    // the interval running.  When we change the page, the
+    // content will disappear and the interval will turn itself off.
+    object.interval_id = setInterval(my_repetitive_callback, 5000);
+
+== Testing
+
+* We use RSpec
+* See <tt>Ajax::Spec::Helpers</tt> and <tt>Ajax::Spec::Extension</tt> {in the rdocs}[http://rdoc.info/projects/kjvarga/ajax]
+* Copy <tt>ajax/spec/integration/ajax_spec.rb</tt> into your project to ensure that the Ajax integration always works.
 
-  window.ajax.onLoad(function() {
-    alert('All your asset are ours!');
-  });
-  
 == Contributions
 
 Contributions are welcome.  Please fork the project and send me a pull request with your changes and Spec tests.
 
 == Useful Resources
 
-* AjaxPatters[http://ajaxpatterns.org/Unique_URLs] useful discussion of techniques for maintaining state using JavaScript to poll for changes to <tt>window.location.hash</tt>.
-* link jQuery Address[http://www.asual.com/jquery/address/] JavaScript library for managing the URL.
-* SWFAddress[http://www.asual.com/swfaddress/] deep linking solution for Flash.
+* {AJAX site crawling specification}[http://code.google.com/web/ajaxcrawling/docs/getting-started.html].
+* AjaxPatters[http://ajaxpatterns.org/] useful discussion of AJAX-related problems and their solutions.
+* {jQuery Address}[http://www.asual.com/jquery/address/] JavaScript library for managing the URL and deep-linking.
 
 Copyright (c) 2010 Karl Varga, released under the MIT license

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/lib/ajax/helpers/url_helper.rb

@@ -5,36 +5,40 @@ module Ajax
       # Return a boolean indicating whether the given URL points to the
       # root path.
       def url_is_root?(url)
-        !!(URI.parse(url).path =~ %r[^\/?$])
+        !!(encode_and_parse_url(url).path =~ %r[^\/?$])
       end
 
       # The URL is hashed if the fragment part starts with a /
       #
       # For example, http://lol.com#/Rihanna
       def is_hashed_url?(url)
-        !!(URI.parse(url).fragment =~ %r[^\/])
+        !!(encode_and_parse_url(url).fragment=~ %r[^\/])
       end
-
+      
       # Return a hashed URL using the fragment of <tt>url</tt>
       def hashed_url_from_fragment(url)
-        url_host(url) + ('/#/' + (URI.parse(url).fragment || '')).gsub(/\/\//, '/')
+        url_host(url) + ('/#/' + (encode_and_parse_url(url).fragment || '')).gsub(/\/\//, '/')
       end
 
       # Return a traditional URL from the fragment of <tt>url</tt>
       def traditional_url_from_fragment(url)
-        url_host(url) + ('/' + (URI.parse(url).fragment || '')).gsub(/\/\//, '/')
+        url_host(url) + ('/' + (encode_and_parse_url(url).fragment || '')).gsub(/\/\//, '/')
       end
 
       # Return a hashed URL formed from a traditional <tt>url</tt>
       def hashed_url_from_traditional(url)
-        uri = URI.parse(url)
+        uri = encode_and_parse_url(url)
         hashed_url = url_host(url) + ('/#/' + (uri.path || '')).gsub(/\/\//, '/')
         hashed_url += ('?' + uri.query) unless uri.query.nil?
         hashed_url
       end
 
       protected
-
+      
+      def encode_and_parse_url(url)
+        URI.parse(URI.encode(url).gsub("%23", "#"))
+      end
+       
       def url_host(url)
         if url.match(/^(\w+\:\/\/[^\/]+)\/?/)
           $1

data/public/javascripts/ajax.js

@@ -176,50 +176,77 @@ var AjaxAssets = function(array, type) {
  *
  * Options:
  *    <tt>enabled</tt>  boolean indicating whether the plugin is enabled.
- *      This must be set if you are using Ajax callbacks in your code,
- *      and you want them to still fire if Ajax is not enabled.
+ *      Callbacks that you set in the Ajax-Info header or directly on
+ *      this instance will still be executed.  They will not be queued,
+ *      the will be executed immediately.
  *
  *    <tt>default_container</tt>  string jQuery selector of the default
  *      container element to receive content.
  *
+ *    <tt>lazy_load_assets</tt>  boolean indicating whether to enable
+ *      lazy loading assets.  If this is disabled, callbacks will be
+ *      executed immediately.
+ *
+ *    <tt>show_loading_image</tt> (default true) boolean indicating whether
+ *      to show the loading image.
+ *
+ *    <tt>loading_image</tt>  (optional) string jQuery selector of an
+ *      existing image to show while pages are loading.  If not set the default
+ *      selector is: img#ajax-loading
+ *
+ *    <tt>loading_image_path</tt> (optional) string full path to the loading
+ *      image.  Used to append an image tag to the body element
+ *      if an existing image is not found.  Default: /images/ajax-loading.gif
+ *
+ *      To customize image handling, override the <tt>showLoadingImage</tt> and
+ *      <tt>hideLoadingImage</tt> methods.
+ *
  * Callbacks:
  *
- * Callbacks can be specified using Ajax-Info{ callbacks: 'javascript to eval' },
- * or by adding callbacks directly to the Ajax instance:
+ * Callbacks can be specified using Ajax-Info{ callbacks: 'javascript to eval.' },
+ * or by adding callbacks directly to the Ajax instance.
+ *
+ * 'onLoad' callbacks are executed once new content has been inserted into the DOM,
+ * and after all assets have been loaded (if using lazy-loading). I.e. "on page load".
+ *
+ * For example:
  *
  *    window.ajax.onLoad(function() { doSomething(args); });
  *
- * Order of execution:
+ * To add a callback to the front of the queue use:
  *
+ *    window.ajax.prependOnLoad(function() { doSomething(args); });
  *
+ * KJV 2010-04-22: I've experienced problems with Safari using String callbacks.  YMMV.
+ * Browser support for callbacks is patchy at this time so lazy-loading is
+ * not recommended.
  */
 var Ajax = function(options) {
   var self = this;
-
-  self.enabled = true;
-  self.default_container = undefined;
-  self.loaded_by_framework = false;
-  self.loading_icon = $('#loading-icon-small');
-  self.javascripts = undefined;
-  self.stylesheets = new AjaxAssets([], 'css');
-  self.callbacks = [];
-  self.loaded = false;
-  self.lazy_load_assets = false;
-  
-  // For initial position of the loading icon.  Often the mouse does not
-  // move so position it by the link that was clicked.
-  self.last_click_coords = undefined;
-
-  // Parse options
-  self.options = options;
-  self.default_container = options.default_container;
-  if (options.enabled !== undefined) {
-    self.enabled = options.enabled;
-  }
-  if (options.lazy_load_assets !== undefined) {
-    self.lazy_load_assets = options.lazy_load_assets;
-  }
   
+  /**
+   * Options
+   */
+  self.options = {
+    enabled: true,
+    default_container: undefined,
+    loaded_by_framework: false,
+    show_loading_image: true,
+    loading_image: 'img#ajax-loading',
+    loading_image_path: '/images/ajax-loading.gif',
+    javascripts: undefined,
+    stylesheets: new AjaxAssets([], 'css'),
+    callbacks: [],
+    loaded: false,
+    lazy_load_assets: false,
+
+    // For initial position of the loading icon.  Often the mouse does not
+    // move so position it by the link that was clicked.
+    last_click_coords: undefined
+  };
+  jQuery.extend(self.options, options);
+  jQuery.extend(self, self.options);
+
   // Initialize on DOM ready
   $(function() { self.init() });
 
@@ -234,10 +261,6 @@ var Ajax = function(options) {
     $.address.history(true);
     $.address.change = self.addressChanged;
 
-    // Insert loading image
-    var image = '<img src="/images/loading-icon-small.gif" id="loading-icon-small" alt="Loading..." />'
-    $(image).hide().appendTo($('body'));
-
     // Bind a live event to all ajax-enabled links
     $('a[data-deep-link]').live('click', self.linkClicked);
 
@@ -328,9 +351,9 @@ var Ajax = function(options) {
       beforeSend: self.setRequestHeaders,
       success: self.responseHandler,
       complete: function(XMLHttpRequest, responseText) {
-        // Stop watching the mouse position and scroll to the top of the page.
-        $(document).unbind('mousemove', self.updateImagePosition).scrollTop(0);
-        $('#loading-icon-small').hide();
+        // Scroll to the top of the page.
+        $(document).scrollTop(0);
+        self.hideLoadingImage();
         self.loaded = true;
       },
       error: function(XMLHttpRequest, textStatus, errorThrown) {
@@ -504,11 +527,30 @@ var Ajax = function(options) {
     return data;
   };
 
+  /**
+   * Hide the loading image.
+   *
+   * Stop watching the mouse position.
+   */
+  self.hideLoadingImage = function() {
+    if (!self.show_loading_image) { return; }
+    $(document).unbind('mousemove', self.updateImagePosition);
+    $(self.loading_image).hide();
+  };
+
   /**
    * Show the loading image.
    */
   self.showLoadingImage = function() {
-    var icon = $('#loading-icon-small');
+    if (!self.show_loading_image) { return; }
+
+    var icon = $(self.loading_image);
+
+    // Create the image if it doesn't exist
+    if (icon.size() == 0)  {
+      $('<img src="'+ self.loading_image_path +'" id="ajax-loading" alt="Loading..." />').hide().appendTo($('body'));
+      icon = $(self.loading_image);
+    }
 
     // Follow the mouse pointer
     $(document).bind('mousemove', self.updateImagePosition);
@@ -540,7 +582,7 @@ var Ajax = function(options) {
    * Update the position of the loading icon.
    */
   self.updateImagePosition = function(e) {
-    $('#loading-icon-small').css({
+    $(self.loading_image).css({
       zIndex:   99,
       position: 'absolute',
       top:      e.pageY + 14,
@@ -548,7 +590,6 @@ var Ajax = function(options) {
     });
   };
 
-
   /**
    * onLoad
    *
@@ -625,4 +666,26 @@ var Ajax = function(options) {
   self.teaser = function(callback) {
     return new String(callback).slice(0,50);
   };
+
+  /**
+   * Escape all special jQuery CSS selector characters in *selector*.
+   * Useful when you have a class or id which contains special characters
+   * which you need to include in a selector.
+   */
+  self.escapeSelector = (function() {
+    var specials = [
+      '#', '&', '~', '=', '>',
+      "'", ':', '"', '!', ';', ','
+    ];
+    var regexSpecials = [
+      '.', '*', '+', '|', '[', ']', '(', ')', '/', '^', '$'
+    ];
+    var sRE = new RegExp(
+      '(' + specials.join('|') + '|\\' + regexSpecials.join('|\\') + ')', 'g'
+    );
+
+    return function(selector) {
+      return selector.replace(sRE, '\\$1');
+    }
+  })();
 };

data/rails/install.rb

@@ -8,7 +8,7 @@ AJAX_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
   public/javascripts/jquery.address-1.2rc.js
   public/javascripts/jquery.address-1.2rc.min.js
   public/javascripts/jquery.json-2.2.min.js
-  public/images/loading-icon-small.gif
+  public/images/ajax-loading.gif
 ].each do |file|
   if File.exist?(File.join(Rails.root, file))
     puts "skipped: #{file} exists!"

data/spec/ajax/helpers_spec.rb

@@ -16,6 +16,11 @@ context 'Ajax::UrlHelpers' do
       Ajax.hashed_url_from_traditional('/Beyonce').should == '/#/Beyonce'
     end
 
+    it "should handle special characters" do
+      Ajax.hashed_url_from_traditional('/beyoncé').should == '/#/beyonc%C3%A9'
+      Ajax.hashed_url_from_traditional('/red hot').should == '/#/red%20hot'
+    end
+    
     DOMAINS.each do |domain|
       it "should work for domain #{domain}" do
         Ajax.hashed_url_from_traditional("http://#{domain}/playlists").should == "http://#{domain}/#/playlists"
@@ -28,6 +33,11 @@ context 'Ajax::UrlHelpers' do
       Ajax.hashed_url_from_fragment('/Beyonce#/Akon').should == '/#/Akon'
       Ajax.hashed_url_from_fragment('/Beyonce#Akon').should == '/#/Akon'
     end
+    
+    it "should handle special characters" do
+      Ajax.hashed_url_from_fragment('/#/beyoncé').should == '/#/beyonc%C3%A9'
+      Ajax.hashed_url_from_fragment('/#/red hot').should == '/#/red%20hot'
+    end
 
     it "should handle no fragment" do
       Ajax.hashed_url_from_fragment('/Beyonce').should == '/#/'
@@ -46,6 +56,7 @@ context 'Ajax::UrlHelpers' do
     it "should detect root urls" do
       Ajax.url_is_root?('/#/Beyonce?query2').should be(true)
       Ajax.url_is_root?('/').should be(true)
+      Ajax.url_is_root?('/#/beyoncé'). should be(true)
     end
 
     it "should detect non-root urls" do
@@ -55,6 +66,10 @@ context 'Ajax::UrlHelpers' do
     it "should support full URLs" do
       Ajax.is_hashed_url?('http://musicsocial.com.local/#/playlists').should be(true)
     end
+    
+    it "should support special characters" do
+      Ajax.is_hashed_url?('http://musicsocial.com.local/#/beyoncé').should be(true)
+    end
   end
 
   describe "(boolean) is_hashed_url?" do
@@ -88,7 +103,12 @@ context 'Ajax::UrlHelpers' do
     end
 
     it "should handle no fragment" do
-      Ajax.traditional_url_from_fragment('/Beyonce').should == '/'
+      Ajax.traditional_url_from_fragment('/Beyonce#/beyoncé').should == '/beyonc%C3%A9'
+      Ajax.traditional_url_from_fragment('/#/red hot').should == '/red%20hot'
+    end
+    
+    it "should handle special characters" do
+      Ajax.traditional_url_from_fragment('/Beyonce#/Akon').should == '/Akon'
     end
 
     DOMAINS.each do |domain|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ajax
 version: !ruby/object:Gem::Version 
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors: 
 - Karl Varga
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-21 00:00:00 -07:00
+date: 2010-04-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -53,8 +53,7 @@ files:
 - lib/rack-ajax.rb
 - lib/rack-ajax/decision_tree.rb
 - lib/rack-ajax/parser.rb
-- public/images/loading-icon-large.gif
-- public/images/loading-icon-small.gif
+- public/images/ajax-loading.gif
 - public/javascripts/ajax.js
 - public/javascripts/jquery.address-1.1.js
 - public/javascripts/jquery.address-1.1.min.js