Author:: Wen-Tien Chang(mailto:ihower@handlino.com), hlb(mailto:hlb@handlino.com)
Copyright:: Copyright (c) 2007 Handlino Inc.
License:: Distributed under the New BSD License

== Description ==
Spakit is a plugin that makes it very easy to turn your Rails App
Into a "single page application" (SPA).

To enable SPA, simply install the plug-in, create a spakit layout and use Spakit helper.
Don't need modify any model/controller code... ;)

Spakit will send xhr request(i.e. prototype's Ajax.Updater ) with ?layout=spakit,
and controller return HTML with spakit layout. Note that spakit_form_for not support file upload submit.

By the way, Message plugin is another SPA plugin,using different approach.

== Requirements
* Rails 2.0.2

== Install ==
* gem install spakit
* cd /your_app/vendor/plugin/
* gem unpack spakit

== Usage ==

For now, Spakit provide three helper:

* spakit_link_to, just like remote_link_to
* spakit_form_for, just like form_for, but you must specify :url
* spakit_form_tag, just like form_tag

by default spakit will replace HTML element called #content.

== Layout code example ==
You should write flash message here because we often place that in application layout.

# /view/layouts/spakit.rhtml

<p><%= flash[:notice] %></p>
<%= yield %>

== History Bookmarks ==

We recommend Really Simple History(RSH) library to handle browser forward/back.

Example code:

# environment.rb

module SpakitHelper
@@spa_options = {
:update => 'content-region',
:loading => 'SPA.loading',
:complete => 'SPA.complete'
}
end

# application.js
# We use jquery syntax, you can use prototype to define your function.

var $j = jQuery.noConflict();

(function($) {
SPA = {
currentHash: null,
currentLocation: null,
init: function() {
if ( $('#waiting-message').length == 0 ) {
$('<div id="waiting-message"><img src="/images/ajax-loader.gif"></div>').appendTo('#bd');
$('#waiting-message').hide();
}
},
loading: function() {
this.init();
$('#waiting-message').show();
},
hide: function() {
$('#waiting-message').hide();
},
historyChange: function(newLocation, historyData, isFresh) {
if (isFresh == null) {
if (historyStorage.hasKey(newLocation)) {
if (newLocation == "start") {
newLocation = location.pathname;
}

$.ajax({
type: "GET",
url: newLocation,
data: { layout: "spakit" },
beforeSend: function(){ SPA.loading(); },
complete: function(res, status){
if ( status == "success" || status == "notmodified" ) {
$('#content-region').html(res.responseText);
}
SPA.hide();
}
});
}
} else {
/* new data */
dhtmlHistory.add(newLocation, historyData);
}
},
complete: function(newLocation) {
this.historyChange(newLocation, "", true);
this.hide();
}
};

SPA.currentHash = window.location.hash;
if (SPA.currentHash.length) {
if (SPA.currentHash.charAt(0) == '#' && SPA.currentHash.charAt(1) == '/') {
SPA.currentLocation = SPA.currentHash.slice(1);
}
}

$(document).ready(function(){
dhtmlHistory.initialize();
if (SPA.currentLocation) {
if (SPA.currentLocation != '#start') {
window.location.href = SPA.currentLocation;
}
} else {
dhtmlHistory.addListener(SPA.historyChange);
if (dhtmlHistory.isFirstLoad()) {
dhtmlHistory.add("start", "");
}
}
});

})(jQuery);

window.dhtmlHistory.create({
toJSON: function(o) {
return JSON.stringify(o);
},
fromJSON: function(s) {
return JSON.parse(s);
}
});