Permalink
Browse files

Finished documentation for Sammy.Storage, Sammy.Session, and Sammy.Store

  • Loading branch information...
1 parent 6f4210d commit b88a9dde64631a1a25c558d7e9d81ae4632cb3d5 @quirkey quirkey committed Jan 1, 2010
Showing with 75 additions and 3 deletions.
  1. +75 −3 lib/plugins/sammy.storage.js
@@ -169,7 +169,8 @@
}
});
- // Basic default store. Stores data in a global object. Data is lost on refresh.
+ // Memory ('memory') is the basic/default store. It stores data in a global
+ // JS object. Data is lost on refresh.
Sammy.Store.Memory = function(name) {
this.name = name;
Sammy.Store.Memory.store = Sammy.Store.Memory.store || {};
@@ -191,7 +192,7 @@
}
});
- // .Data stores objects using the jQuery.data() methods. This has the advantadge
+ // Data ('data') stores objects using the jQuery.data() methods. This has the advantadge
// of scoping the data to the specific element. Like the 'memory' store its data
// will only last for the length of the current request (data is lost on refresh/etc).
Sammy.Store.Data = function(name, $element) {
@@ -216,7 +217,7 @@
}
});
- // .LocalStorage makes use of HTML5 DOM Storage, and the window.localStorage
+ // LocalStorage ('local') makes use of HTML5 DOM Storage, and the window.localStorage
// object. The great advantage of this method is that data will persist beyond
// the current request. It can be considered a pretty awesome replacement for
// cookies accessed via JS. The great disadvantage, though, is its only available
@@ -250,6 +251,12 @@
}
});
+ // .SessionStorage ('session') is similar to LocalStorage (part of the same API)
+ // and shares similar browser support/availability. The difference is that
+ // SessionStorage is only persistant through the current 'session' which is defined
+ // as the length that the current window is open. This means that data will survive
+ // refreshes but not close/open or multiple windows/tabs. For more info, check out
+ // the <tt>LocalStorage</tt> documentation and links.
Sammy.Store.SessionStorage = function(name) {
this.name = name;
};
@@ -274,6 +281,20 @@
}
});
+ // .Cookie ('cookie') storage uses browser cookies to store data. JavaScript
+ // has access to a single document.cookie variable, which is limited to 2Kb in
+ // size. Cookies are also considered 'unsecure' as the data can be read easily
+ // by other sites/JS. Cookies do have the advantage, though, of being widely
+ // supported and persistent through refresh and close/open. Where available,
+ // HTML5 DOM Storage like LocalStorage and SessionStorage should be used.
+ //
+ // .Cookie can also take additional options:
+ // +expires_in+:: Number of seconds to keep the cookie alive (default 2 weeks).
+ // +path+:: The path to activate the current cookie for (default '/').
+ //
+ // For more information about document.cookie, check out the pre-eminint article
+ // by ppk: [http://www.quirksmode.org/js/cookies.html]
+ //
Sammy.Store.Cookie = function(name, $element, options) {
this.name = name;
this.$element = $element;
@@ -319,11 +340,53 @@
}
});
+ // Sammy.Storage is a plugin that provides shortcuts for creating and using
+ // Sammy.Store objects. Once included it provides the <tt>store()</tt> app level
+ // and helper methods. Depends on Sammy.JSON (or json2.js).
Sammy.Storage = function(app) {
this.use(Sammy.JSON);
this.stores = this.stores || {};
+ // <tt>store()</tt> creates and looks up existing <tt>Sammy.Store</tt> objects
+ // for the current application. The first time used for a given <tt>'name'</tt>
+ // initializes a <tt>Sammy.Store</tt> and also creates a helper under the store's
+ // name.
+ //
+ // === Example
+ //
+ // var app = $.sammy(function() {
+ // this.use(Sammy.Storage);
+ //
+ // // initializes the store on app creation.
+ // this.store('mystore', {type: 'cookie'});
+ //
+ // this.get('#/', function() {
+ // // returns the Sammy.Store object
+ // this.store('mystore');
+ // // sets 'foo' to 'bar' using the shortcut/helper
+ // // equivilent to this.store('mystore').set('foo', 'bar');
+ // this.mystore('foo', 'bar');
+ // // returns 'bar'
+ // // equivilent to this.store('mystore').get('foo');
+ // this.mystore('foo');
+ // // returns 'baz!'
+ // // equivilent to:
+ // // this.store('mystore').fetch('foo!', function() {
+ // // return 'baz!';
+ // // })
+ // this.mystore('foo!', function() {
+ // return 'baz!';
+ // });
+ // });
+ //
+ // });
+ //
+ // === Arguments
+ //
+ // +name+:: The name of the store and helper. the name must be unique per application.
+ // +options+:: A JS object of options that can be passed to the Store constuctor on initialization.
+ //
this.store = function(name, options) {
// if the store has not been initialized
if (typeof this.stores[name] == 'undefined') {
@@ -355,6 +418,15 @@
});
};
+ // Sammy.Session is an additional plugin for creating a common 'session' store
+ // for the given app. It is a very simple wrapper around <tt>Sammy.Storage</tt>
+ // that provides a simple fallback mechanism for trying to provide the best
+ // possible storage type for the session. This means, <tt>LocalStorage</tt>
+ // if available, otherwise <tt>Cookie</tt>, otherwise <tt>Memory</tt>.
+ // It provides the <tt>session()</tt> helper through <tt>Sammy.Storage#store()</tt>.
+ //
+ // See the <tt>Sammy.Storage</tt> plugin for full documentation.
+ //
Sammy.Session = function(app, options) {
this.use(Sammy.Storage);
// check for local storage, then cookie storage, then just use memory

0 comments on commit b88a9dd

Please sign in to comment.