sessionStorage driver and additional methods

README.md

@@ -1,28 +1,83 @@
 # $.store jQuery plugin #
 
-<code>$.store</code> is a simple, yet easily extensible, plugin to persistently store data on the client side of things. It uses <code>window.localStore</code> where available. Older Internet Explorers will use <code>userData</code>. If all fails <code>$.store</code> will save your data to <code>window.name</code>.
+'$.store' is a simple, yet easily extensible, plugin to persistently store data on the client side of things. It uses 'window.localStore' where available. Older Internet Explorers will use 'userData'. If all fails '$.store' will save your data to 'window.name'.
 
-*Note*: The <code>windowName</code> will only do JSON serialization. <code>windowName</code> is not persistent in the sense of making it accross a closed browser window. If you need that ability you should check <code>$.storage.driver.scope == "browser"</code>.
+*Note*: The 'windowName' driver will only do JSON serialization. 'windowName' is not persistent in the sense of making it across a closed browser window. If you need that ability you should check '$.storage.driver.scope == "browser"'.
 
 ## Usage ##
 
-<pre><code>
-//initialize
-$.storage = new $.store();
+	//initialize
+	$.storage = new $.store();
+
+	// save a value
+	$.storage.set( key, value );
+
+	// read a value
+	$.storage.get( key );
+
+	// deletes a value
+	$.storage.del( key );
+
+	// delete all values
+	$.storage.flush();
 
-// save a value
-$.storage.set( key, value );
+	// get the number of stored entries
+	$.storage.length();
+
+	// get a key by index (order is not guaranteed, use for iterating through keys)
+	$.storage.key( index );    
+
+## Adding Serializers ##
 
-// read a value
-$.storage.get( key );
+You can easily add your own serializers to the stack. Make sure to add them before initializing the '$.store'.
 
-// deletes a value
-$.storage.del( key );
+*Note:* Serializers do not apply to the 'windowName' storage driver.
 
-// delete all values
-$.storage.flush();
-</code></pre>
+	$.store.serializers.yaddayadda = {
+		ident: "$.store.serializers.yaddayadda",
+		init: function( encoders, decoders )
+		{
+			// register your serializer with en/decoder stack
+			encoders.unshift( "yaddayadda" );
+			decoders.push( "yaddayadda" );
+		},
+
+		isYaddaYadda: function( value )
+		{
+			// determine if value should be processed by this serializer
+			return true;
+		},
+
+		encode: function( value )
+		{
+			// check if the value can be encoded
+			if( !value || value._serialized || !this.isYaddaYadda( value ) )
+				return value;
+
+			// prepare serialized-data-wrapper
+			var _value = { _serialized: this.ident, value: value };
+
+			// work your magic
+			_value.value = "serializedVersionOf data";
+
+			return value;
+		},
+
+		decode: function( value )
+		{
+			// check if the value can be decoded
+			if( !value || !value._serialized || value._serialized != this.ident )
+				return value;
+
+			// work your magic
+			value.value = "unserializedVersionOf data";
+
+			return this.isYaddaYadda( value.value ) ? value.value : undefined;
+		}
+	};
 
 ## License ##
 
-$.store is published under the [MIT license](http://www.opensource.org/licenses/mit-license.php).
+'$.store' is published under the [MIT license][].
+
+[MIT license]: http://www.opensource.org/licenses/mit-license.php

index.html

@@ -60,23 +60,17 @@
 		document.write( '<p>Initialized $.storage with driver ' + $.storage.driver.ident + '</p>' );
 	</script>
 
-	<h1>$.store</h1>
-
-	<p>
-		<code>$.store</code> is a simple, yet easily extensible, plugin to persistently store data on the client side of things.
-		It uses <code>window.localStore</code> where available. Older Internet Explorers will use <code>userData</code>.
-		If all fails <code>$.store</code> will save your data to <code>window.name</code>.
-	</p>
-
-	<p>
-		Note: The <code>windowName</code> will only do JSON serialization. <code>windowName</code> 
-		is not persistent in the sense of making it accross a closed browser window. If you need
-		that ability you should check <code>$.storage.driver.scope == "browser"</code>.
-	</p>
-
-	<h2>Usage</h2>
-
-<pre>//initialize
+<h1>$.store jQuery plugin</h1>
+
+<p><code>$.store</code> is a simple, yet easily extensible, plugin to persistently store data on the client side of things. It uses <code>window.localStore</code> where available. Older Internet Explorers will use <code>userData</code>. If all fails <code>$.store</code> will save your data to <code>window.name</code>.</p>
+
+<p>The optional <code>cookie</code> driver requires the <a href="https://github.com/carhartl/jquery-cookie"><code>$.cookie</code></a> plugin.</p>
+
+<p><em>Note</em>: The <code>windowName</code> driver will only do JSON serialization. <code>windowName</code> is not persistent in the sense of making it across a closed browser window. If you need that ability you should check <code>$.storage.driver.scope == "browser"</code>.</p>
+
+<h2>Usage</h2>
+
+<pre><code>//initialize
 $.storage = new $.store();
 
 // save a value
@@ -89,16 +83,16 @@ <h2>Usage</h2>
 $.storage.del( key );
 
 // delete all values
-$.storage.flush();</pre>
-	
-	<h2>Adding Serializers</h2>
-	
-	<p>
-		You can easily add your own serializers to the stack.
-		Make sure to add them before initializing the <code>$.store</code>.
-		Note: Serializers do not apply to the <code>windowName</code> storage driver.
-	</p>
-<pre>$.store.serializers.yaddayadda = {
+$.storage.flush();
+</code></pre>
+
+<h2>Adding Serializers</h2>
+
+<p>You can easily add your own serializers to the stack. Make sure to add them before initializing the <code>$.store</code>.</p>
+
+<p><em>Note:</em> Serializers do not apply to the <code>windowName</code> storage driver.</p>
+
+<pre><code>$.store.serializers.yaddayadda = {
   ident: "$.store.serializers.yaddayadda",
   init: function( encoders, decoders )
   {
@@ -139,8 +133,12 @@ <h2>Adding Serializers</h2>
 
     return this.isYaddaYadda( value.value ) ? value.value : undefined;
   }
-};</pre>
+};
+</code></pre>
+
+<h2>License</h2>
 
+<p><code>$.store</code> is published under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p>
 
 </body>
 </html>