The jStore jQuery Plugin allows users to access a number of different client-side storage engines through a single, convenient interface. jStore can manage a number of different storage engines at once, allowing for the possibility of different storage engines performing different tasks on a single page. See Supported Browsers for more information on specific limitations of available storage engines.
For this quick example, I will demonstrate usage of jStore using the Flash storage engine, since it's supported on the largest range of browsers.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
<script type="text/javascript" src="script/jquery.jstore-all-min.js"></script>
<script type="text/javascript">
// First, we must tell jStore where to find the HTML file which embeds our flash script.
// If you move the jStore.swf or jStore.Flash.html files out of their default directories (document root),
// use this variable to define where to access the .html file. Within the .html file, you can set up the
// path to the .swf file.
// Then, set up the default engine we wish to use.
jQuery.extend(jQuery.jStore.defaults, {
project: 'demo-guide',
engine: 'flash',
flash: 'jStore.Flash.html'
})
// Next, we need to wait for jStore to prepare the storage engine
jQuery.jStore.ready(function(engine){
jQuery.jStore.flashReady(function(){
// Finally, we need to wait for the storage engine to be ready.
// Once this function is called, you can use the jStore interface synchronously
engine.ready(function(){
var engine = this,
counter = (engine.get('counter') || 0)*1, original = counter;
counter++; // Incrememnt the counter
alert('Original Value: ' + original + "\n"
+ 'New Value: ' + counter + "\n"
+ 'Setting Value: ' + engine.set('counter', counter) + "\n"
+ 'Fetching Value: ' + engine.get('counter'));
if (counter == 5){
var lastValue = engine.rem('counter'); // Clear the value
alert('Resetting Counter at ' + counter); // Alert the last value of the counter
}
})
})
});
// Once the engine is prepared, we can do whatever we need with it
jQuery('a').click(function(){
jQuery.jStore.set('link_title', jQuery(this).attr('title'));
// And, if you find it necessary, you can access the storage engine in a jQuery chain.
// Storing values will allow you to keep chaining, but requesting a variable will return
// that value, stopping the chain.
jQuery(this).css('display', 'block').store('myval', 30).attr('href', '#').store('myval');
return false;
});
// Finally, we trigger jStore's load function. This is a new step in the
// activation procedure of jStore, since Version 1.1
$(function(){
jQuery.jStore.load();
});
</script>
</head>
<body>
<a title="jstore" href="test.x">Click Me</a>
</body>
</html>
In the above example, we are setting our default project and engine for jStore to use. This is an optional way of defining the type of storage engine to use. If you don't define any of these default options, jStore will automatically attempt to find the most compatible storage engine available to your browser. Check out the jStore API for more info.
jStore provides a number of accessible methods for managing data.
jQuery.jStore.store('myvariable', 'Some Value'); // Will set the variable, and return the value
jQuery.jStore.set('myvariable', 'Some Value'); // New as of 1.2
jQuery('#someelement').store('myvariable', 'Some Value'); // Will set the variable, and return the jQuery Object
jQuery('#someelement').setStore('myvariable', 'Some Value'); // New as of 1.2
jQuery.jStore.store('myvariable'); // Returns the value, or null if no matching variable is found
jQuery.jStore.get('myvariable'); // New as of 1.2
jQuery('#someelement').store('myvariable'); // Returns the value, or null if no matching variable is found
jQuery('#someelement').getStore('myvariable'); // New as of 1.2
jQuery.jStore.remove('myvariable'); // Removes the variable from storage, and returns the last value
jQuery('#someelement').removeStore('myvariable'); // Removes the variable from storage, and returns the jQuery Object
jStore provides a few user-configurable settings which define global properties used by jStore
jQuery.jStore.defaults.[VARIABLE_NAME]
These properties should be treated as Read-Only. If you attempt to manually set any of these, you could render jStore inoperable.
jQuery.jStore.[VARIABLE_NAME]
jQuery.jStore.ready( function(engine) )A callback function which is fired when jStore has successfully prepared a storage engine.
jStore.ready will not fire until the user calls jQuery.jStore.load() and loads either a user-defined default engine, or an automatically detected best-use engine.
When jStore is ready, it does NOT mean the engine is ready.
jQuery.jStore.flashReady( function() )A callback function which is fired when jStore has been notified by Flash that it is ready for data transaction.
When jStore is flash ready, it does NOT mean the flash engine is ready.
jQuery.jStore.fail( function(engine) )A callback function which is fired when jStore attempts to load an engine after including any third party scripts. If an engine fails to initialize after its dependencies are loaded, it will trigger this callback, instead of throwing an exception.
Currently, only the Google Gears engine can trigger this callback, as it is the only engine with a third party library include.
jQuery.jStore.use( engine, project, [identifier] )A method for instanciating additional storage engines which jStore can manage.
jQuery.jStore.use('gears', 'display-prefs', 'my-web-app'); // Create a new Storage Engine
jQuery.jStore.Instances['my-web-app.display-prefs.gears']; // Access the Engine by it's JRI
jQuery.jStore.setCurrentEngine( [jri] )A method for setting the default storage engine to use.
jQuery.jStore.store('myvar', 'myval'); // Stored in the default engine
jQuery.jStore.use('gears', 'display-prefs', 'my-web-app'); // Create a secondary Storage Engine
jQuery.jStore.setCurrentEngine('my-web-app.display-prefs.gears'); // Make it the current engine
jQuery.jStore.store('myvar', 'myval'); // Stored in the my-web-app.display-prefs.gears
jQuery.jStore.setCurrentEngine(); // Change back to the default engine
jQuery.jStore.load( )A method used to begin loading necessary jStore components. In most cases, the jStore.ready() function will be triggered shortly after this call.
This function MUST be called after the DOMReady event. Be sure to include it in a jQuery(document).ready( ... ) callback.
jQuery.jStore.FindEngine( )A method used for auto-detecting available storage engines. Will auto-instanciate the first available engine it finds.
This method is called automatically by jStore if no engine is specified. Users shouldn't have to ever call it manually.
jQuery.jStore.delgate.bind( 'event', function() )StorageEngine.delgate.bind( 'event', function() )Allows you to bind a callback to the jStore delegate.
In most cases, you should be subscribing callbacks to the delegate events through the jQuery.ready() like interfaces, and not through the raw binding call on the delegate.
Within the callbacks "this" will correspond to either the jQuery.jStore Object (for jStore events) or the instance of the Engine (for StorageEngine events).
jQuery.jStore.delgate.trigger( 'event', [ optionalParam, [ optionalPram, [ ...]]] )StorageEngine.delgate.trigger( 'event', [ optionalParam, [ optionalPram, [ ...]]] )Allows you to trigger a callback on the jStore Delegate.
jQuery.jStore.safeStore( value )Escapes the value passed into it, converting objects, arrays, and functions into JSON.
This function is called automatically by each engine before storage. Users should have no need to use this directly.
jQuery.jStore.safeResurrect( value )Tests the value provided to determine if it's JSON. If so, the value is eval'd and returned.
This function is called automatically by each engine before storage. Users should have no need to use this directly.
| Engine Type | Engine Name | Third-Party Library | Description |
|---|---|---|---|
| Google Gears | gears | http://code.google.com/apis/gears/gears_init.js | Allows jStore to work with Google Gears. The user must have installed Google Gears for their browser to use this storage engine. |
| Flash | flash | Allows jStore to work with Flash storage. The user must have at Flash Player 8.0.0+ to use this engine. Truly cross browser, so data is avilable in any browser that supports flash. | |
| Local Storage | local | DOM Storage, based on the HTML5 Specification for local storage. http://www.whatwg.org/specs/web-apps/current-work/#scs-client-side | |
| Session Storage | session | DOM Storage, based on the HTML5 Specification for session storage. Data persists through page reloads and refreshes, but leaving the page or opening a new tab/window of the page will create a new session. http://www.whatwg.org/specs/web-apps/current-work/#scs-client-side | |
| Html5 | html5 | Structured Client-Side Database Storage, based on the HTML5 Specification. http://www.whatwg.org/specs/web-apps/current-work/multipage/structured-client-side-storage.html#sql | |
| IE | ie | Internet Explorer Storage, based on Microsoft's userData behavior. http://msdn.microsoft.com/en-us/library/ms531424(VS.85).aspx |
All jStore Storage Engines inherit some base properties and methods from a StorageEngine class. This is a quick overview on those methods/properties.
These properties should be treated as Read-Only. Changing them manually could render the engine inoperable.
Edits made directly to the data object will NOT be committed. Use the get/set/rem methods.
StorageEngine.connect( )Performs all the work needed to establish a connection to the database. When finished, all StorageEngine.ready() callbacks will fire. Called automatically by the jStore manager.
// Attempt to fetch a value
StorageEngine.ready(function(){
this; // A reference to the engine which is ready
alert(this.jri + ' is ready for get/set/rem calls!');
});
// Connect to the storage database
StorageEngine.connect();
StorageEngine.include( )Includes all third party libraries required, and fires an event when all libraries are loaded.
StorageEngine.included( function() )Fires the callback when StorageEngine.include() finishes loading.
// Set up our onIncluded callback
StorageEngine.included(function(){
this; // A reference to the engine which is ready
alert(this.jri + ' has included ' + this.includes.length + ' extra libraries.');
});
StorageEngine.include();
StorageEngine.isAvailable( )A test to determine whether or not the current browser supports this storage engine.
// Test our engine's availability
alert( StorageEngine.isAvailable() ? 'Engine will function in this browser!' : 'Engine will NOT function in this browser!' );
StorageEngine.ready( function() )Fires the callback when the engine is finished initializing and is ready for data transactions.
// Set up our onIncluded callback
StorageEngine.ready(function(){
this; // A reference to the engine which is ready
alert(this.jri + ' is ready for get/set/rem calls!');
});
StorageEngine.interruptAccess()Since 1.2, checks to see if the engine is ready, and if not, throws an JSTORE_ENGINE_NOT_READY exception. Every engine get/set/rem function implements this check, to prevent access to the engine before it is ready.
StorageEngine.get( key )Finds and returns the request setting. Returns null if no matching key is found.
// Attempt to fetch a value
StorageEngine.ready(function(){
var value = this.get('somevar');
alert( key + ' is ' + ( value == null ? 'NOT SET!' : value) + '.' );
});
StorageEngine.set( key, value )Updates the requested setting. Returns the NEW value.
// Attempt to fetch a value
StorageEngine.ready(function(){
this.set('myvar', 'myval'); // Returns "myval"
});
StorageEngine.rem( key )Removes the setting, if it exists. Returns the value of the setting before removed.
// Attempt to fetch a value
StorageEngine.ready(function(){
var value = this.get('somevar'); // Returns "someval"
var value2 = this.rem('somevar'); // Returns "someval"
var value3 = this.get('somevar'); // Returns null
});
This is a simple list of which browsers currently support each engine.
| Engine | FF2+ | Safari3.1+ | WebKit Nightly | IE6 | IE7 | IE8 |
|---|---|---|---|---|---|---|
| local | ||||||
| session | ||||||
| gears | ||||||
| flash | ||||||
| html5 | ||||||
| ie |
| Event Name | Subscribe By | Fired When |
|---|---|---|
| jStore-ready | jQuery.jStore.ready() OR jQuery.jStore.delegate.bind('jStore-ready', callback) | jStore has successfully loaded the Storage Engine. |
| jStore-failure | jQuery.jStore.fail() OR jQuery.jStore.delegate.bind('jStore-failure', callback) | jStore has unsuccessfully attempted to instantiate a library after loading its third party libraries. |
| flash-ready | jQuery.jStore.flashReady() OR jQuery.jStore.delegate.bind('flash-ready', callback) | jStore has been notified that flash has successfully loaded. |
| Event Name | Subscribe By | Fired When |
|---|---|---|
| engine-ready | StorageEngine.ready() OR StorageEngine.delegate.bind('engine-ready', callback) | The Storage Engine is fully initialized and ready for data transactions. |
| engine-included | StorageEngine.included() OR StorageEngine.delegate.bind('engine-included', callback) | The Storage Engine has successfully included all third-party libraries. |
Javascript Exceptions are thrown by jStore when a critical error has occured.
| Exception Name | Thrown When |
|---|---|
| JSTORE_ENGINE_UNDEFINED | jStore was provided with an engine name it could not resolve. Ex: jQuery.jStore.use('foobar', 'my-project'); |
| JSTORE_JRI_CONFLICT | jStore attempted to create two identically named connections. This means the identifier, project, and engine type were the same for two different connections. |
| JSTORE_ENGINE_UNAVILABLE | jStore attempted to load an unavilable engine. Ex: calling StorageEngine.get('somevariable') before the StorageEngine ready event. |
| JSTORE_ENGINE_NOT_READY | Since 1.2, when jStore attempts to access or transact data through an engine that is not yet ready. Ex: calling jQuery.use('ie', 'my-project') in a Firefox browser |
The source archive, which is avilable for svn checkout from google code, uses Apache ANT http://ant.apache.org/.
| Command | Result |
|---|---|
| ant clean | Purges and recreates /jquery-jstore/dist/ |
| ant core | Creates jquery.jstore.js in /jquery-jstore/dist/development/ |
| ant all | Creates jquery.jstore-all.js in /jquery-jstore/dist/development/ |
| ant engines | Copies all engines into /jquery-jstore/dist/development/engines/ |
| ant development | Executes ant clean, ant core, ant all, ant engines |
| ant production | Executes ant development, minifies all js files and moves them to /jquery-jstore/dist/production |
| ant release | Executes ant production, and creates zip/tar.gz files of /jquery-jstore/dist/development and /jquery-jstore/dist/production in /jquery-jstore/dist/release |
Please visit: http://eric.garside.name/demo.html?p=jstore
The current version of jStore can be downloaded from Google Code
You can also checkout the subversion repository for jStore with the following command:
svn checkout http://jquery-jstore.googlecode.com/svn/trunk/ jquery-jstore-read-only