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

ept · Jan 1, 2010 · b88a9dd · b88a9dd
1 parent 6f4210d
commit b88a9dd
Showing 1 changed file with 75 additions and 3 deletions.
diff --git a/lib/plugins/sammy.storage.js b/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