jstorage - simple javascript plugin to store data locally

5/2/2015 jStoragesimpleJavaScriptplugintostoredatalocally

http://www.jstorage.info/#basics 1/5

jStoragestoredatalocallywithJavaScriptjStorageisacrossbrowserkeyvaluestoredatabasetostoredatalocallyinthebrowserjStoragesupportsallmajorbrowsers,bothindesktop(yesevenInternetExplorer6)andinmobile.

AdditionallyjStorageislibraryagnostic,itworkswellwithanyotherJavaScriptlibraryonthesamewebpage,beitjQuery,Prototype,MooToolsorsomethingelse.Thoughyoustillneedtohaveeitherathirdpartylibrary(Prototype,MooTools)orJSON2onthepagetosupportolderIEversions.

jStoragesupportsstoringStrings,Numbers,JavaScriptobjects,ArraysandevennativeXMLnodes.jStoragealsosupportssettingTTLvaluesforautoexpiringstoredkeysandbestofallnotifyingothertabs/windowswhenakeyhasbeenchangedorpublishing/subscribingtoeventsfromthesameoranothertab/window,whichmakesjStoragealsoalocalPubSubplatformforwebapplications.

jStorageisprettysmall,about7kBwhenminifiedand4kBgzipped.

Donate

SupportjStoragedevelopment

Index

1. Basics2. Download3. Interactivetest4. Browsersupport5. Usage6. Functionreference7. Usageexample8. Issues9. ContactandCopyright

1.Basics

jStoragemakesuseofHTML5localstoragewhereavailableanduserDatabehaviorinInternetExplorerolderversions.

Currentavailability:jStoragesupportsallmajorbrowsersInternetExplorer6+,Firefox2+,Safari4+,Chrome4+,Opera10.50+

Ifthebrowserdoesn'tsupportdatacaching,thennoexceptionsareraisedjStoragecanstillbeusedbythescriptbutnothingisactuallystored.

jStorageisreallysmall,justabout7kBwhenminified(4kBwhengzipped)!

5/2/2015 jStoragesimpleJavaScriptplugintostoredatalocally

http://www.jstorage.info/#basics 2/5

2.Download

jStoragecanbedownloadedatgithub(directdownloadlink)

3.Interactivetest

Addsomevaluesandrefreshthepageifyourbrowsersupportsstoringlocaldata,thenthevaluesshouldsurvivethepagerefresh.

KEY VALUE

ADD

Clicking"GET"alertsthevalueforprovidedkeywiththemethod$.jStorage.get(key) GET

Clearallsaveddata FLUSH

4.Browsersupport

Browser Storagesupport SurvivesbrowserrestartSurvivesbrowser

crash Storagesize

Chrome4 + + + 5MBFirefox3.6 + + + 5MBFirefox3 + + + 5MBFirefox2 + + + 5MBIE8 + + + 10MBIE7 + + + 128kBIE6 + + + 128kBOpera10.50 + + 5MBOpera10.10 N/A N/A N/ASafari4 + + + 5MBIphoneSafari + + + 5MBSafari3 N/A N/A N/A

5.Usage

jStoragerequiresPrototype,MooToolsorjQuery+jQueryJSONorJSON2.Eitherway,thesyntaxstaysthesame.

SimplesetuptosupportjStoragewithJSON2

/*$.jStorageisnowavailable*/

SetupwithjQuery2

/*$.jStorageisnowavailable*/

5/2/2015 jStoragesimpleJavaScriptplugintostoredatalocally

http://www.jstorage.info/#basics 3/5

6.Functionreference

set(key,value[,options])

$.jStorage.set(key,value,options)

Savesavaluetolocalstorage.keyneedstobestringotherwiseanexceptionisthrown.valuecanbeanyJSONeablevalue,includingobjectsandarraysoraXMLnode.CurrentlyXMLnodescan'tbenestedinsideotherobjects:$.jStorage.set("xml",xml_node)isOKbut$.jStorage.set("xml",{xml:xml_node})isnot.

Optionsisanoptionaloptionsobject.Currentlyonlyavailableoptionisoptions.TTLwhichcanbeusedtosettheTTLvaluetothekey($.jStorage.set(key,value,{TTL:1000});).NBifnoTTLoptionvaluehasbeenset,anycurrentlyusedTTLvalueforthekeywillberemoved.

get(key[,default])

value=$.jStorage.get(key)value=$.jStorage.get(key,"defaultvalue")

getretrievesthevalueifkeyexists,ordefaultifitdoesn't.keyneedstobestringotherwiseanexceptionisthrown.defaultcanbeanyvalue.

deleteKey(key)

$.jStorage.deleteKey(key)

Removesakeyfromthestorage.keyneedstobestringotherwiseanexceptionisthrown.

setTTL(key,ttl)

$.jStorage.set("mykey","keyvalue");$.jStorage.setTTL("mykey",3000);//expiresin3seconds

SetsaTTL(inmilliseconds)foranexistingkey.Use0ornegativevaluetoclearTTL.

getTTL(key)

ttl=$.jStorage.getTTL("mykey");//TTLinmillisecondsor0

GetsremainingTTL(inmilliseconds)forakeyor0ifnotTTLhasbeenset.

flush()

$.jStorage.flush()

Clearsthecache.

index()

$.jStorage.index()

Returnsallthekeyscurrentlyinuseasanarray.varindex=$.jStorage.index();console.log(index);//["key1","key2","key3"]

storageSize()

$.jStorage.storageSize()

Returnsthesizeofthestoreddatainbytes

currentBackend()

5/2/2015 jStoragesimpleJavaScriptplugintostoredatalocally

http://www.jstorage.info/#basics 4/5

$.jStorage.currentBackend()

Returnsthestorageenginecurrentlyinuseorfalseifnone

reInit()

$.jStorage.reInit()

Reloadsthedatafrombrowserstorage

storageAvailable()

$.jStorage.storageAvailable()

Returnstrueifstorageisavailable

subscribe(channel,callback)

$.jStorage.subscribe("ch1",function(channel,payload){console.log(payload+"from"+channel);});

SubscribestoaPublish/Subscribechannel)

publish(channel,payload)

$.jStorage.publish("ch1","data");

PublishespayloadtoaPublish/Subscribechannel

listenKeyChange(key,callback)

$.jStorage.listenKeyChange("mykey",function(key,action){console.log(key+"hasbeen"+action);});

Listensforupdatesforselectedkey.NB!evenupdatesmadeinotherwindows/tabsarereflected,sothisfeaturecanalsobeusedforsomekindofpublish/subscribeservice.

stopListening(key[,callback])

$.jStorage.stopListening("mykey");//cancelalllistenersfor"mykey"change

Stopslisteningforkeychange.Ifcallbackisset,onlytheusedcallbackwillbecleared,otherwisealllistenerswillbedropped.

7.Usageexample

jQuery

jQuerydoesn'tcomewithbuiltinJSONencoder/decodersoifyouneedtosupportIE6/IE7youshouldincludeoneyourseltlikeintheexample

//Checkif"key"existsinthestoragevarvalue=$.jStorage.get("key");if(!value){//ifnotloadthedatafromtheservervalue=load_data_from_server()//andsaveit$.jStorage.set("key",value);

5/2/2015 jStoragesimpleJavaScriptplugintostoredatalocally

http://www.jstorage.info/#basics 5/5

}

Prototype

//Checkif"key"existsinthestoragevarvalue=$.jStorage.get("key");if(!value){//ifnotloadthedatafromtheservervalue=load_data_from_server()//andsaveit$.jStorage.set("key",value);}

8.Issues

WhywouldyouwanttousejStoragewhencookiesworkalreadyineverybrowser?CookiesarenotmeanttosavelargequantitiesofdatalocallytheyaremeanttopassaroundIDvaluestokeeptrackofusers.InternetExplorerallowstouseupto20cookiesperdomainwiththepayloadof4kBpercookie.Itisn'tverymuch,especiallyconsideringtheneedtochunklargerdataintosmallerbits.Thefactthatthedata(max.80kB)issenttotheserverwith*every*calldoesn'tsoundmuchofagoodideaeither.

9.ContactandCopyright

20102012AndrisReinman,andris.reinman@gmail.comjStorageislicensedunderUnlicense,sobasicallyyoucandowhateveryouwanttodowithit.