localForage: a guide for the beginners

localForage is a JavaScript library that simplifies your work of storing data on the client side. Cross-Browser compatibility problems may arise while using browser storage. localForage fixes this by falling back to IndexedDB / WebSQL or localStorage. Let’s get our hands dirty and write some real code to store real data.

Installation

Add localForage to your app just by downloading the latest release of localForage and adding it via a script tag.

<script type="text/javascript" src="localforage.js"></script>

Storing Data

localForage is simply a key-value pair storage. But don’t get upset right away. We can essentially store anything, JavaScript objects, strings, arrays, integers, floats… as well, so we can make complex data structures and store them in a key (will check on this in a while). First, let’s go plain simple and store just string values.

The first parameter to setItem is the name of the ‘key’, the ‘key’ is unique and it basically “identifies” the value you want to store. And the second one is the value itself.

localforage.setItem('name', 'Aniruddha');

We can also store arrays,

var list_of_names = ['Ani', 'Rahid', 'Shafiul'];

localforage.setItem('names', list_of_names);

And Objects…

var profile = {
    "name":   "Aniruddha Adhikary",
    "github": "aniruddha-adhikary"
};

localforage.setItem('profile', profile);

setItem can also take a callback function as the third parameter, the function gets called when the data gets stored.

localforage.setItem('name', 'Aniruddha', function(value) {
    // Do something once the value has been stored.
    console.log("The value " + value + " has been successfully stored");
});

Reading Data

So, to read an item, we will simply use getItem. The first parameter would be they name of the key, and the second (optional) is a callback function that gets called upon the value is retrieved from the browser. If you really want to read and use the value somehow in your app, you must have a callback function. Like the example just plain and simply prints the value of the key ‘name’ on the browser console.

localforage.getItem('name', function(value) {
    // Do something once the value has been loaded.
    console.log(value);
});

What if we have an array…

localforage.getItem('list_of_names', function(value) {
    for (each_name in value) {
        // do something with every stuff, you get the idea now
        console.log(each_name);
    }
});

Clearing all data

If you want to clear all data stored by your app on the client, just do…

localforage.clear()

The number of key/value pairs

The total number of key/value pairs stored in the client’s data storage can be obtained by…

localforage.length(function(numberOfKeys) {
    // Outputs the length of the database.
    console.log(numberOfKeys);
});

The n-th key

To get the n-th key from the client’s data storage, simply use localforage.key. Here, “n” starts from 0. So the 1st key is actually key #0. or n = 0

localforage.key(n, function(v) {
    console.log(v)
});

All the keys

And to get all they keys stored on the client, you can simply run loops.

localforage.length(function(numberOfKeys) {
    for (var i = numberOfKeys - 1; i >= 0; i--) {
    	localforage.key(i, function(le_key) {
    		// append to a list or something I guess? 
    		console.log(le_key);
    	});
    };
});

Hope this helps