Demo JazzRecord JS ORM in Your Browser!

What follows is a series of demonstrations of what JazzRecord can do for you, using Gears right in your browser. You should install Firebug (wait, you don't already have it?! Preposterous!) and Gears addons for your browser. In browsers other than Firefox, you can get limited functionality out of the Firebug bookmarklet.

Click the little Firebug icon in the bottom right of your browser to activate it. Navigate to the Console tab and learn the joy that is True Firebug Usage: Command line for the Web!

Make sure the Console tab in Firebug is activated. If it's not, you'll be shown a series of checkboxes for activating it and other deactivated tabs in Firebug. Once you've turned it on the page will reload.

Gears Notice

You will be prompted the first time through to allow Gears/this site to access your local Gears data. This is normal, and only gives access to data stored specifically for this site. Click allow in order to let the demo work. Alternately, you may download the file and try it out in your own site. Y'know. If you're really that paranoid.

Be aware that every visit to this page resets this particular database for demo purposes. In your own code, you'll most likely want to persist across sessions.

Now Load JazzRecord. This will setup the environment and load some sample data so that you can make queries to the models and see how JazzRecord works.

Open up Firebug, and you'll see a flurry of information has just been logged to it. This is a running record of all SQL statements which have been run in an instance of JazzRecord. This is very similar to Rails' own logging system, and can be turned off and on.

Models

JazzRecord's Model class is designed to behave very similar to ActiveRecord's. The main differences are language-based and the fact that columns and any custom data/behavior for the model must be declared all in one place. Here's a minimalist example:

var JazzLegend = new Model({
  table: "jazz_legends",
  columns: {
    name: "text",
    primary_instrument: "text",
    years_active: "text"
  }
});

After declaring such a model and migrating (more about this in the documentation), this model is available for making queries and interacting with the table that holds the saved data.

Finders

Like ActiveRecord, most of the activity in JazzRecord is based around loading, modifying, and saving records. It's no surprise, then, that Jazz has finders of various stripes. Try the following code in your Firebug console:

var miles = JazzLegend.findBy("name", "Miles Davis");
var louis = JazzLegend.first();
var dizzy = JazzLegend.find(2);

You'll see that now you can access fields from each of these famous artists.

miles.primary_instrument
//trumpet

louis.years_active
//1914-1971

Likewise, changing and saving records is equally as easy as ActiveRecord:

miles.name = "Miles Dewey Davis III";
miles.save();

Associations

By writing slightly more complex model declarations, you imply relationships between them, and take advantage of JazzRecord's automatic association-linking capabilities.

//new version of JazzLegend model
JazzLegend = new JazzRecord.Model({
  table: "jazz_legends",
  foreignKey: "jazz_legend_id",
  hasMany: {albums: "albums"},
  columns: {
    name: "text",
    primary_instrument: "text",
    years_active: "text"
  }
});

//associated model
Album = new JazzRecord.Model({
  table: "albums",
  belongsTo: {artist: "jazz_legends"},
  columns: {
    title: "text",
    year: "text",
    jazz_legend_id: "number"
  }
});

With these versions of the models in place, we can check out some examples of association-loading, one of the tricks up JazzRecord's sleeve. We've taken the liberty of loading the Gears instance on this page with these very models and some example data (and a few others just for fun). So feel free to copy and paste the following lines into your Firebug console, tinker with them and see what happens!

var milesRecords = JazzLegend.findBy("name", "Miles Dewey Davis III").albums;
//all of Miles' albums

milesRecords.length
//3

milesRecords[1].title
//Blue Period

milesRecords[0].load("artist").name
//Miles Davis, of course

Death and Destruction

What fun would databases be without the ability to trash all of your data?

dizzy.destroy();
//someone must've grown tired of Dizzy!

Album.count();
//3 albums so far, all Miles

Album.destroyAll();
//like that time you lost all your CDs when your car was broken into...

Album.count();
//0, no more Miles!!

There's More, Obviously

You didn't think we actually got any rest around here, did you?

From Rails 2.0-like "dirty" records, callbacks, and near-complete ActiveRecord options lists for finders, to custom Model/Record methods, JazzRecord has a lot going for it. If you think you have a use for it, try it out and let us know what you think!

For information on how to implement JazzRecord in your own projects, visit the documentation

In future releases of JazzRecord, validations will be fully available. Validations allow for requirements-based filtering of stored data. Minimum/maximum string length, string format checking/forcing, and even custom validations will all be possible.

Still to come is the ability to automatically associate one record with another and to dissociate two records when one is destroyed.

Also still to come are migrations, which allow you to move database schemas between versions of your app seamlessly without losing user data.