I’ve been looking around for good ways to store information for a PhoneGap application I’m working on. I think that the PhoneGap SQL APIs may still be the best bet but I also wanted to check out some of the more unique storage options. One of the options I came across was Lawnchair, by Brian Leroux. One of the beautiful things about Lawnchair is that it’s incredibly simple. It does persistent JSON storage, has adapters for different storage options (localstorage, webSQL, etc) and is very lightweight. One of the not-fun things about Lawnchair is that it’s incredibly simple. While I found it easy to use (mostly) there were some areas that didn’t work. I think part of the issue is that I don’t have a lot of experience with NoSQL solutions like CouchDB (where Lawnchair draws a lot of its inspiration) so I think a lot of the issue lies with me.

That said, I found it to be a powerful, if basic way to store data and I think it’s worth knowing about. This isn’t going to be helpful for people who know JavaScript pretty well or who have used Lawnchair a lot, but I figured jotting downs some of my thoughts and the basics of it would be helpful for my learning process. So here it is.

Quick Info Up Front

One of the first things I ran into was that Lawnchair will behave slightly differently depending on the adapter you end up using. For instance, I started out using the default ‘dom’ adapter, which just ties into the localStorage API and uses key/value pairs. So when you call the save() method, you pass in a key with values. But upon switching to the webkit-sqlite adapter, which relies on databases, I found that the old key/value pair code didn’t seem to work because of the way that the webkit-sqlite adapter assigns ids. The key is still stored, but it doesn’t seem to work as a selector. I think this might have something to do with the fact that I’m using ints as my key and not strings, but haven’t done enough research.

This post will use the webkit-sqlite adapter so keep that in mind as you’re looking at the code.

Getting Started

Getting started with Lawnchair is a beautiful thing. Simply drop the Lawnchair.js file and whatever adapter you want to use, then just start using the Lawnchair class. I found it’s helpful to assign it to a variable so that you can access it easily from other functions. It also requires a callback function. Normally, when you set the callback, you can use the this scope to perform operations on the database, but in my example I’m just tracing out that we connected.

     var beers = Lawnchair({name:'beers'},function(e){
          console.log('storage open');
     });

So beers is now the reference to my data storage and I can call the Lawnchair APIs using that variable.

Saving Data

While at first I was a little bit confused about how to treat Lawnchair as a way to store more complex data types, storing objects is incredibly easy. Just wrap whatever you want in a JavaScript object and then call the save method.

          var obj = {beername:"Wet Hop",brewername:"Deschuttes",brewerlocation:"Bend, OR"
                         ,beerstyle:"IPA",quantity:1,purchasedate:"12/11/2011",price:"9.00"
                         ,cellardate:"9/11/2011",cellartemp:40,brewdate:"8/10/2011"};
          beers.save({key:"1",value:obj});

In this case, I assigned a key of “1″, which makes sure it’s a string. If you just use integers, it ends up translating to the database as 1.0. This actually becomes kind of a pain later on as you’ll see, so it’s important to keep it in mind. If you use a string as your key, it will just make the ID that string, so it’s a little bit simpler to use. Below is what the data storage looks like when you don’t use a string.

By using strings I found it makes the retrieve operations a lot more simple. In fact, I couldn’t figure out how to use the get operation using the webkit-sqlite adapter and a number for the key. Getting 1 didn’t work and getting 1.0 didn’t work, so I just ended up using a string. I think that’s more a limitation of my JS knowledge than anything, but it was something that I struggled with.

One cool feature of modifying data in Lawnchair is that when you save() something, if you pass in a key that already exists, it will just overwrite that existing key. No having to worry about update versus insert, Lawnchair just figures it out and saves the data correctly.

Getting Data

There are a couple of good ways to get data; the first is the get() method. Pretty straightforward: You pass in a key, and it will return the value associated with that key.

             beers.get("1",function(obj){
                  console.log(obj);
             });

The object that comes back includes a key property and a value property, which is where the data is stored. So in my example object above, I can reference obj.value.beername to get the name of the beer.

Another helpful retrieve method is the all() method, which just dumps every object from the storage area in an array. Every function in Lawnchair can use a callback function and in this one it’s especially helpful. In my app I use the all() method to loop through the beers and display them in a list.

     beers.all(function(arrBeers){
          for(var i = 0; i<arrBeers.length;i++)
          {
               console.log(arrBeers.length);
               var listdiv = document.createElement('li');
                 listdiv.setAttribute('id','listdiv');
                 listdiv.innerHTML = arrBeers[i].value.beername;              
               $('#beer_list').append(listdiv);    
          }
          $('#beer_list').listview("refresh");
     });

Modifying Data

As I mentioned above, the way Lawnchair works is that when you save an object with the same key, it just overwrites it. So the key to modifying data is just grabbing it using the get() method, adjusting the data on the object, and calling save() with the same key.

          beers.get("1",function(thisobj){
               console.log(thisobj);
               var obj = {};
                    obj = thisobj.value;
                    obj.beername = "Not Wet Hop";
               beers.save({key:thisobj.key,value:obj});
          });

I found it kind of helpful to use the existing key on my retrieved object to save since that’s a good way to make sure you’re saving the object you want and not overwriting another one or creating a new one. Key management becomes kind of important with Lawnchair but it’s not tough to do.

Beyond

One of the things I found helpful after digging in was checking out the Lawnchair plugins. The couple that I downloaded were the query plugin and the callback plugin. The query plugin just lets you use some basic query syntax to pull out information. The callback plugin lets you specify callbacks for before and after events so you can make your code do specific things based on when you’re accessing the data.

It’s also really important to take a look at the adapters because that’s critical to making sure the application will work across devices. In general the adapters should be hot-swappable in that you should be able to just move adapters in and out without having to change the code. I had some trouble getting the latest DOM adapter to work, so I can’t totally verify that, but as I understand it that’s the way it’s supposed to work.

Conclusion

After messing with it, I think Lawnchair is one of the most straightforward ways to store data for a basic PhoneGap application. It’s not going to hold up to all of the use cases that a complex application needs, but for something where you’re storing some simple data, Lawnchair is perfect. It leverages existing web storage options and using adapters you can make sure it’s cross platform.

Full Code

I posted the full code snippet here. Keep in mind I’m a JavaScript newbie so if you see things I’m doing wrong I’d be grateful to hear about them.