ajax 0.1.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 [name of plugin creator]
+
+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.rdoc

@@ -0,0 +1,291 @@
+= Ajax
+
+<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 beauty of Ajax is that your Rails application only ever sees traditional requests, so it does not have to be "Ajax aware".
+
+Ajax is being used live in production on altnet.com[http://altnet.com], if you would like to try it out (as of May 1st 2010 or thereabouts).
+
+== 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>
+
+     gem 'ajax'
+
+2. <tt>bundle install</tt>
+3. <tt>rake ajax:install</tt>
+    
+=== Rails 2.x.x
+
+<b> As a Gem</b>
+
+1. Add the gem as a dependency in your <tt>config/environment.rb</tt>
+
+     config.gem 'ajax'
+
+2. <tt>rake gems:install</tt>
+
+3. Add to your <tt>Rakefile</tt>
+
+     begin
+       require 'ajax/tasks'
+     rescue Exception => e
+       puts "Warning, couldn't load gem tasks: #{e.message}! Skipping..."
+     end
+
+4. <tt>rake ajax:install</tt> to install required files.  This command is safe to run multiple times.  It will skip existing files.
+
+<b> As a Plugin</b>
+
+  ./script/plugin install http://github.com/kjvarga/ajax.git
+
+=== 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!
+   ...
+   
+== Introduction
+
+Ajax handles these common problems:
+
+* SEO/Crawlability/Google Analytics support
+* Browser History
+* Bookmarkability / Deep-linking
+* Redirects
+* Cookies
+* Lazy-loaded Assets
+* Activating Tabs
+* Request Rewriting & Redirecting
+
+Ajax converts a traditional Rails application to use a completely AJAX frontend.
+
+What do I mean by "completely AJAX"?  Everyone uses AJAX.  What we mean when we say "completely AJAX" is that the main page is only loaded once.  Every link now loads content via AJAX.
+
+But if we do that, the URL will never change and we will have no history, because that is how browsers determine history.  It turns out the only way to change the URL without causing the browser to issue a new request, is to modify the named anchor - or "hashed" - part of the URL.  
+
+So now your traditional links auto-magically load content via AJAX into a page container and update the browser URL with the new URL.  You have all the benefits of AJAX as well as history and link bookmarkability.
+
+Where before you would have seen something like <tt>http://example.com/the-beatles/history</tt>, now you would see <tt>http://example.com/#/the-beatles/history</tt>.  Notice the <tt>#/</tt>?
+
+=== How does it work?
+
+Ajax comprises Rack middleware, Rails integrations and some JavaScript libraries to handle everything from redirecting and rewriting incoming requests, to managing the response headers and content, to handling the browser URL, JavaScript callbacks and client-side events.
+
+Browsers do not send the hashed part of the the URL with page requests, so to an AJAX-ed application, all requests look like they are for root.
+
+In order to load the correct page we must first render a framework page with accompanying JavaScript.  The JS examines the URL and then issues another request to the server for the hashed part (which may still be <tt>/</tt> if the user requested the home page).
+
+=== An Example User Interaction
+
+1. User pastes http://example.com/#/beyonce/albums into a browser.
+2. Server receives request for http://example.com/ and renders the framework page.
+4. AJAX request for http://example.com/beyonce/albums is initiated by client-side JavaScript, and received by the server.
+5. Server renders http://example.com/beyonce/albums.
+6. Response headers are processed and the response inserted into the page container.
+
+=== Request Handling
+
+<b>Ajax uses a custom HTTP header <tt>Ajax-Info</tt> to pass JSON back and forth between the client and server.</b>  The client sends information about the state of the container, and the server sends new information back.
+
+By default the current layout is sent in the <tt>Ajax-Info</tt> header.  This can be useful for determining which assets to include, or layout to render in your response.
+
+<b><tt>Ajax-Info</tt> headers with special meaning:</b>
+
+[title]      Sets the page title.
+[tab]        jQuery selector, triggers the <tt>activate</tt> event on matched element(s).
+[container]  jQuery selector, the container to receive the content (default:  <tt>default_container</tt>).
+[assets]     Hash of JavaScript and CSS assets to load <tt>{ :javascripts => [], :stylesheets => [] }</tt>
+[callbacks]  List of string callbacks to execute after assets have finished loading.
+
+=== Robots and External APIS
+
+<b>We detect robots by their User-Agent strings.</b>  If a robot is detected the Ajax handling is bypassed and the robot sees the traditional Rails application.
+
+By default any AJAX or non-GET requests pass through unmodified.
+
+If you need to expose external APIs you can do so using a regular expression that is matched against incoming URLs.
+
+== Compatibility
+
+You must be running <b>jQuery 1.4.2</b> to use this plugin.  Sorry, Prototype users.
+
+The following JavaScript libraries are required and included in the plugin:
+
+* {jQuery Address 1.2RC}[http://www.asual.com/jquery/address/]
+* jQuery JSON 2.2
+
+=== Ruby and Rails:
+
+  * Rails 2.3.4 running Ruby 1.8.7 and Ruby 1.9
+  * Rails 2.3.5 running Ruby 1.8.7 and Ruby 1.9
+  
+=== Browsers:
+
+(See {jQuery address supported browsers}[http://www.asual.com/jquery/address/docs/].)
+
+  * Internet Explorer 6.0+
+  * Mozilla Firefox 1.0+
+  * Safari 1.3+
+  * Opera 9.5+
+  * Chrome 1.0+
+  * Camino 1.0+
+
+= Documentation
+
+Please browse the {API documentation at rDoc.info}[http://rdoc.info/projects/kjvarga/ajax]
+
+== Configuration
+
+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.
+
+To disable the plugin in your environment file:
+  
+  # config/environments/test.rb
+  Ajax.enabled = false
+
+If you need to, you can check the state of the plugin with:
+
+  Ajax.is_enabled?
+
+Other onfiguration goes in <tt>config/initializers/ajax.rb</tt> such as indicating which links to except from the request processing.  See <b>Excepted Links</b>.
+
+== Ajax Layouts
+
+Typically AJAX content does not render a layout because we just want to update a fragment of a page.  Automatically turning off layouts when rendering AJAX is one option, but what about when we do want to use a layout?
+
+My solution is to first look in <tt>app/views/layouts/ajax/</tt> for a layout with the same name as the default layout for the current action.  If a layout is found, we use it, otherwise the default layout is used.
+
+In your Ajax layouts you can define callbacks, tabs to activate or the container to receive content.
+
+For example, our layouts:
+
+  layouts/
+    _assets.html.haml
+    ajax/
+      application.html.haml
+      single_column.html.haml
+      two_column.html.haml
+    application.html.haml
+    single_column.html.haml
+    two_column.html.haml
+
+Gists
+* {ajax/application.html.haml}[http://gist.github.com/373133#file_application.html.haml]
+* {ajax/two_column.html.haml}[http://gist.github.com/373133#file_two_column.html.haml]
+
+== Link Handling
+
+<b>All links which are rendered using the <tt>link_to</tt> (or any other url) helper method automatically include a <tt>data-deep-link</tt> attribute</b> containing the path from the link's HREF.
+
+The Ajax JavaScript class listens for clicks on any link with a <tt>data-deep-link</tt> attribute and loads the link's content using AJAX.
+
+Should you need to, you can set this attribute on a link by passing in HTML options to <tt>link_to</tt>:
+
+  link_to odd_url, {}, { :data-deep-link => '/even/odder/url' }
+
+To manually mark a link as traditional, pass <tt>:traditional => true</tt> or <tt>:data-deep-link => nil</tt>.
+
+=== Excepted Links
+
+<b>Excepted links bypass Ajax request and link handling.</b>  I call these traditional links.
+
+Links can be excepted by passing in strings or regular expressions to <tt>Ajax.exclude_paths()</tt>.  Only pass the path and not the full URL.  The path will be modified to match against other paths as well as against full URLs:
+
+  # config/initializers/ajax.rb
+  Ajax.exclude_paths %w[ /login /logout /signup /altnet-pro /my-account/edit /user-session/new ]
+  Ajax.exclude_paths [%r[\/my-account\/.*]]
+  
+Typically, we except pages that require HTTPS, like signup forms, because including secure forms on an insecure page often triggers a browser warning.
+
+Excepted links when rendered do not contain the <tt>data-deep-link</tt> attribute if they are rendered with the <tt>link_to</tt> (or any other url) helper method.
+
+== Rails Helpers
+
+Use the <tt>ajax_header</tt> helper in your controllers or views to add data to the <tt>Ajax-Info</tt> header.  Values are converted to JSON before being sent over the wire.  Internally this function uses <tt>Ajax.set_header</tt>.
+
+You can use <tt>Ajax.get_header</tt> to inspect <tt>Ajax-Info</tt> header values.  See the <b>In Views</b> example.
+
+=== In Controllers
+
+In controllers, <tt>ajax_header</tt> uses an <tt>after_filter</tt> to add content to the response.  It therefore accepts passing a block instead of a static value, as well as <tt>:only</tt> and <tt>:except</tt> modifiers, e.g:
+
+  # app/controllers/application_controller.rb
+  ajax_header :title { dynamic_page_attribute(:page_title) || "Music @ Altnet" }  
+  ajax_header :assets do
+    { :stylesheets => [current_controller_stylesheet] }
+  end
+  
+  # app/controllers/browse_controller.rb
+  ajax_header :tab, '#header .nav li:contains(Music)', :only => [:music, :artists, :albums, :tracks, :new_releases]
+  ajax_header :tab, '#header .nav li:contains(Playlists)',  :only => :playlists
+  ajax_header :tab, '#header .nav li:contains(DJs)', :only => :djs
+
+  # app/controllers/activity_controller.rb
+  ajax_header :tab, '#header .nav li:contains(Realtime)'
+  ajax_header :assets, { :javascripts => javascript_files_for_expansion(:juggernaut_jquery) }
+  
+Array and Hash values are merged so you can call <tt>ajax_header</tt> multiple times.  For example, the asset Hash and Array values will be merged.
+
+=== In Views
+
+The syntax is similar to the controller version, except that we do not use an <tt>after_filter</tt>, so you cannot pass a block or <tt>:only</tt> and <tt>:except</tt> modifiers.
+
+See {ajax/two_column.html.haml}[http://gist.github.com/373133#file_two_column.html.haml] for an example.
+
+== Lazy-loading Assets
+
+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.
+
+If you need to perform operations on the new content, or instantiate objects defined in the dependent assets, use <b>JavaScript Callbacks</b>.
+
+== <a name="callbacks">JavaScript Callbacks</a>
+
+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:
+
+  ajax_header, :callbacks, 'window.player.init();'
+  
+Alternatively you may want to bind callbacks directly to the <tt>window.ajax</tt> object in your view:
+
+  # 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');");
+  
+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.
+
+<tt>window.ajax.prependOnLoad</tt> adds the callback to the front of the queue.  Callbacks can also be functions, for example:
+
+  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.
+
+Copyright (c) 2010 Karl Varga, released under the MIT license

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'rubygems'
+gem 'rspec', '1.3.0'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ajax"
+    gem.summary = %Q{A framework to augment a traditional Rails application with a completely AJAX frontend.}
+    gem.description = %Q{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.}
+    gem.email = "kjvarga@gmail.com"
+    gem.homepage = "http://github.com/kjvarga/ajax"
+    gem.authors = ["Karl Varga"]
+    gem.files =  FileList["[A-Z]*", "{app,config,lib,public,rails,spec,tasks}/**/*"]
+    gem.test_files = []
+    gem.add_development_dependency "rspec"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+desc 'Default: run spec tests.'
+task :default => :spec
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/ajax/**/*_spec.rb', 'spec/rack-ajax/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+#task :spec => :check_dependencies
+
+desc 'Generate documentation for the ajax plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Ajax'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('app/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.2

data/app/controllers/ajax_controller.rb

@@ -0,0 +1,3 @@
+class AjaxController < ApplicationController
+  unloadable
+end

data/app/views/ajax/framework.html.erb

@@ -0,0 +1,7 @@
+<script type="text/javascript">
+  $(function() {
+    if (window.ajax !== undefined) {
+      window.ajax.loaded_by_framework = true;
+    }
+  });
+</script>

data/config/initializers/ajax.rb

@@ -0,0 +1,14 @@
+# Default Ajax initialization file
+
+# Configure paths that will bypass Ajax handling:
+#
+#   Ajax.exclude_paths %w[ /login /logout /signup /user-session/new ]
+#   Ajax.exclude_paths [%r[\/my-account\/.*]]
+
+# If you use a custom <tt>Rack::Ajax.decision_tree</tt>, include your 
+# parser extensions in the Rack::Ajax::Parser module.
+#
+# The extensions define custom methods that are used in the
+# <tt>Rack::Ajax.decision_tree</tt>.
+#
+#   Rack::Ajax::Parser.send(:include, Rack::Ajax::Parser::Extensions)

data/lib/ajax.rb

@@ -0,0 +1,79 @@
+require 'ajax/helpers'
+
+module Ajax
+  include Ajax::Helpers
+  
+  class << self
+    attr_writer :logger
+  end
+
+  # Return a logger instance.
+  #
+  # Use the Rails logger by default, assign nil to turn off logging.
+  # Dummy a logger if logging is turned off of if Ajax isn't enabled.
+  def self.logger
+    if !@logger.nil? && is_enabled?
+      @logger
+    else
+      @logger = Class.new { def method_missing(*args); end; }.new
+    end
+  end
+
+  # Return a boolean indicating whether the plugin is enabled.
+  #
+  # Enabled by default.
+  def self.is_enabled?
+    @enabled.nil? ? true : !!@enabled
+  end
+
+  # Set to false to disable this plugin completely.
+  #
+  # ActionController and ActionView helpers are still mixed in but
+  # they are effectively disabled, which means your code will still
+  # run.
+  def self.enabled=(value)
+    @enabled = !!value
+  end
+
+  # Return a boolean indicating whether the plugin is being mock tested.
+  #
+  # Mocking forces the environment to be returned after Ajax processing
+  # so that we can introspect it and verify that the correct actions were
+  # taken.
+  def self.is_mocked?
+    @mocked ||= false
+  end
+
+  # Set to true to enable mocking testing the plugin.
+  #
+  # Integration tests will return the result of the URL rewriting in a
+  # special response.  Redirects will be indicated using standard responses.
+  #
+  # Use this to test the handling of URLs in various states and with different
+  # HTTP request methods.
+  def self.mocked=(value)
+    @mocked = !!value
+  end
+
+  # Installs Ajax for Rails.
+  #
+  # This method is called by <tt>init.rb</tt>, which is run by Rails on startup.
+  #
+  # Customize rendering.  Include custom headers and don't render the layout for AJAX.
+  # Insert the Rack::Ajax middleware to rewrite and handle requests.
+  # Add custom attributes to outgoing links.
+  def self.install_for_rails
+    if defined?(Rails)
+      Ajax.logger = Rails.logger
+
+      # Customize rendering.  Include custom headers and don't render the layout for AJAX.
+      ::ActionController::Base.send(:include, Ajax::ActionController)
+
+      # Insert the Rack::Ajax middleware to rewrite and handle requests
+      ::ActionController::Dispatcher.middleware.insert_before(Rack::Head, Rack::Ajax)
+
+      # Add custom attributes to outgoing links
+      ::ActionView::Base.send(:include, Ajax::ActionView)
+    end
+  end
+end