Using MooTools' Hash.Cookie API

posted by Jonah Dempcy

MooTools makes working with cookies quite easy. Based on functions from Paul Peter Koch's QuirksMode, the MooTools API for handling cookies is intuitive and easy to remember.

For storing simple bits of information on the browser, the Cookie methods read(), write() and dispose() are adequate. As their names imply, these read, write and delete cookies from the browser, respectively.

But, if you want to do something more complex, such as save a JSON string each time a method is called on the cookie, then Hash.Cookie is for you.

What's the difference between the Hash.Cookie methods and the standard methods you say? For one, Hash.Cookie is its own module, so make sure the version of MooTools you're using has it included. Besides that, Hash.Cookie gives you all the functionality of the Hash class, including getters/setters, each(), some(), filter(), has(), keyOf() and more. For the full documentation on all Hash methods available, view the Hash docs here.

Here's an example that uses the Hash.Cookie class to store how many times a user has visited the page. Note that this uses Firebug so if you don't have it enabled, you'll need to override console.log().

window.addEvent('domready', function() {
    var cookie = new Hash.Cookie('test-cookie');
    
    var numberOfVisits = $defined(cookie.get('numberOfVisits')) ? 
                         cookie.get('numberOfVisits') :
                         0;
                         
    cookie.set('numberOfVisits', numberOfVisits + 1);
    
    console.log('You have visited the page ' + 
                 cookie.get('numberOfVisits') + 
                 ' times.');        
});

On line 1, we start by declaring everything to occur when the DOM is ready. For MooTools developers, this should be a familiar practice. Although we aren't manipulating the DOM in this example, I've left it in, as Firebug threw an error when I tried to console.log() before the DOM was ready.

On line 2, we instantiate a new cookie named 'test-cookie' without any options. Interestingly, this also has the effect of loading the cookie if it already exists. This means that the first time the user visits the page, it will write a cookie, but on all subsequent visits it will read a cookie. The end result is the same: we have a reference to the cookie as a hash object, and can use the methods that the Hash class provides.

Next, on lines 4-6, we use a ternary operator to check if 'numberOfVisits' has already been written to the cookie. If so, we read it from the cookie. If not, it is initialized to 0.

On line 8, we increment 'numberOfVisits' using the set() method. Finally, we log the number of visits using Firebug's console.log().

Getters, Setters and Auto-Saving Cookies

Getters and setters should be familiar to anyone versed in Java but I imagine some JavaScript developers may be unfamiliar with them. Essentially, get() and set() methods are provided for you to use instead of directly accessing the data. For instance, cookie.hash.numberOfVisits and cookie.get('numberOfVisits') both return the same data, but the former directly accesses the data while the latter uses a wrapper method.

There are numerous reasons to use getters/setters instead of directly accessing the data, but one practical example is the use of Hash.Cookie's autoSave functionality. There is an autoSave flag in the options which, if enabled, will save the data after each operation on the hash. It defaults to 'true' which is why I didn't have to write() the cookie in the above example.

Since I didn't define a duration in the options object when instantiating the cookie (nor did I even include an options object, for that matter), it will only live for the duration of the browser. In other words, it's a session cookie: When the user exits the browser and restarts, the cookie will be destroyed. For the cookie to live beyond the lifespan of the browser, you can specify the duration of the cookie to live (in days).

The other options which I omitted were domain, path and secure. None of those were important for my example but for some applications, setting domain- and path-specific cookies and ensuring they are only accessed over HTTPS may be necessary

This example is somewhat simple but I hope it has provided an introduction to using MooTools' excellent Hash.Cookie API. Good luck and enjoy a tall glass of soymilk with your Hash Cookies!