jsper by rob.mcvey

Documentation

View Documentation

About

jsper is a native implementation of HTML5 storage (localStorage and sessionStorage) that degrades quite gracefully all the way back to IE6 by using cookies. This is not a milestone, others have done this. What I've done differently is:

• created a better api to access localStorage using simple get, set methods
• provide automatic serialization/deserialization of storage items, i.e. what you put in is what you get back
• provide iterators
• all non-getter methods are chainable, and most methods are overloaded and accept callbacks
• i allow you to manually switch storage engines (if supported by the browser) and retrieve info about what engine is currently in use

Browser Support

jsper has been unit tested in IE6,7,8/Firefox 2,3,4/Chrome/Safari

Getting started and Notes

This is the entirety of the setup process:

<script type="text/javascript" src="/path/to/jsper.js"></script>

Note: if you are using with jquery and want to access through jquery, replace jsper.method with $.jsper.method (or jQuery.jsper.method if you prefer)

################ HOLA ##################
If you are wanting to experiment with jsper, open firebug or the console and follow along with the examples; jsper is included in this page. :) #######################################

New Client-side Shopping Cart Example

View Shopping Cart Example

Getting and Setting

Setters

jsper.set('foo', {bar:'baz',boz:{bez:'biz'}});

jsper.set('arr', ['a', 'b', 'c', 'd']);

jsper.set('message', 'hello world!');

//setting multiple items at the same time
var obj = {
	line1:"This makes things",
	line2:"a bit easier"
};

jsper.set( obj );

Getters

var an_obj = jsper.get('foo');

// will log an object
console.log(an_obj);

var obj_stored = jsper.raw_value('foo');

// log string representation of object
console.log(obj_stored);

// everything in the current storage engine
var all = jsper.all();

console.log(all);

// retrieve two keys
var two_keys = jsper.get(['key1', 'key2']);

var link = "<a href='http://www.badsite.com'>Bad link</a>";
jsper.set('link', link);

// pass a callback to the get method
var stripped = jsper.get('link', function(data){
    return data.replace(/<.*?>/g, '');
});

console.log(stripped);

Iterating

var scores = [0, 5, 10, 15, 20];

jsper.set('scores', scores);

var total = 0;

jsper.each('scores', function(score){
    total += score;
});

console.log(total);

Overloaded Methods

var multiple_keys = {
   first:['a', 'b', 'c'],
   second:['d','e','f']
};

//set multiple keys at the same time
jsper.set(multiple_keys);

console.log(jsper.get('first'));//returns: array [a, b, c]

var first_and_second = jsper.get(['first','second']);
// or
jsper.each(['first', 'second'], function(data, index){
   console.log(" %s", data);//output: a b c d e f
});

Engines

// retrieve current storage engine
console.log(jsper.storage_engine);

// switch engines and set a value
jsper.force_engine('sessionStorage');
jsper.set('logged_in', true);
jsper.set('username', 'john.smith');

console.log('username: %s from storage: %s', jsper.get('username'), jsper.storage_engine);

// or the more succinct
var output = jsper.force_engine('cookie').set(
	{logged_in:true, username:'john.smith'}
).get(['logged_in', 'username']);

console.log('username: %s from storage: %s', output[1], jsper.storage_engine);

Removing Items

jsper.set('my_array', ['a','b','c','e','d']);
jsper.set('my_object', {a:'foo', b:{c:'bar', d:'baz'}});

//remove the third element from the array
jsper.remove_item('my_array', 3);

//remove the b key from my_object
jsper.remove_item('my_object', 'b');

console.log(jsper.get('my_array'));//a b c d

// view all items stored in current engine
console.log(jsper.all());

// remove the entire key
jsper.remove('my_array');

//remove all items stored in current engine
jsper.clear();

console.log(jsper.all());

Install

Download the jsper script from the links below and include it in your page like so:

	<script type="text/javascript" src="/path/to/jsper.js"></script>

License

Licensed under GNU Lesser Public License

Authors

rob.mcvey contact me @ jsperjs(at)gmail dot com

Portions of the cookie storage engine and the entirety of JSON parsing are respectively from:

• The Wojo Group The Wojo Group@github
• and Douglas Crockford's JSON2 class

Dependencies

jsper has no dependencies on other libraries as it is written in PAJ™ (read more about PAJ); if it is loaded after jquery, it will assign itself to the jquery object through jQuery.jsper

Download

You can download this project in either zip or tar formats.

You can also clone the project with Git by running:

$ git clone git://github.com/rmcvey/jsper