Building a PhoneGap Couchbase Lite Container

Note: This is old, like 6 months out of date before we finally released something for PhoneGap 3.0. For the latest background, you might try the plugin builder.

These are the steps I took to build LiteGap. Eventually LiteGap will be a script to do this for you. Ideally a plugman plugin. For now follow these instructions, or see the master branch for an approximation of what you'd get when you've done this:

Download PhoneGap

They put out a new version each month, so grab the latest PhoneGap release, download it and figure out where it downloaded to so you can run some binaries in there via the command line.

Create a new app

There is a create script in the package, under the lib/ios/bin directory. Run it like this:

/phonegap-2.5.0/lib/ios/bin/create ./LiteGapApp com.couchbase.LiteGapApp LiteGapApp

Now test the build once, you should see a basic PhoneGap hello world. Running it puts some files in place you'll want to have in your first version control check-in.

Install Couchbase Lite

See the Couchbase Lite wiki for detailed installation instructions or do this:

• Add the CouchbaseLite.framework and CouchbaseLiteListener.framework packages to the Frameworks for your project.
• Link libstdc++, libicucore, libz, libsqlite3 and Security.framework
• Launch the database by putting this in AppDelegate.m

    // at the top
    #import "<CouchbaseLite/CouchbaseLite.h>"

    // in didFinishLaunching...
    NSLog(@"Opening database...");
    CBLManager* dbmgr = [CBLManager sharedInstance];
    // [CBLView setCompiler: [[[CBLJSViewCompiler alloc] init] autorelease]];
    NSURL* url = dbmgr.internalURL;
    NSLog(@"Couchbase Lite url = %@", url);

You can create a database from your PhoneGap environment with code like this:

$.ajax({url:"http://lite.couchbase./db", type : "PUT", success : console.log});

And post data to it like this:

$.ajax({
  url : "http://lite.couchbase./db", 
  type : "POST", 
  dataType: "json", 
  contentType : "application/json", 
  data : JSON.stringify({tacos:"rule"}), 
  success : console.log
});

Here's an API cheat sheet.

Set up JavaScript Views

If you want to program views in JavaScript from your PhoneGap runtime (instead of defining them in AppDelegate.m when you create the connection) you can do that by including some stuff from the Extras directory in the Couchbase Lite download.

Move these 4 files into your build, add #import "CBLJSViewCompiler.h" at the top of your AppDelegate.m, and uncomment the line about CBLJSViewCompiler above. Now you can write your views in JavaScript and save them to design documents using any JSON Ajax client.

CBLJSFunction.h
CBLJSFunction.m
CBLJSViewCompiler.h
CBLJSViewCompiler.m

You'll also need to add your own build of Apple's JavaScriptCore.framework to your project. Building this for all platforms is kind of a pain (you'll end up running lipo by hand on the build artifacts for Simulator, iPad, and iPhone) so I've checked a binary version of it into this repo. It's probably easiest to clone that down and use it. Just drop it in your Frameworks group.

Persona for Login

The Couchbase Sync Gateway lets you log in with Mozilla Persona so if you want to do that you'll need some code in your app. Luckily, you can install it as a PhoneGap plugin.

Start developing!

You may want to look at an example PhoneGap Couchbase Lite app to see how we did things.