JazzRecord JavaScript ORM Documentation

JazzRecord is about making databases fun. It's about removing all of the garbage and discontinuity of API and data format in Gears and Adobe AIR.

To actually do much of anything with JazzRecord, you'll need to do the following:

  1. Setup an adapter for your given runtime environment.
  2. Setup data models
  3. (optional) Associate them to one another
  4. (optional) Provide models with validations to prevent dirty data from infiltrating the database.
  5. (optional) Provide models with behavior and callbacks which can then affect your application.
  6. Use automigration OR Setup migrations

After you've prepped your database, you can go to town:

  • Query models for record objects.
  • Custom finders and other methods provided in the model definition will be made available to the model.
  • Record objects can be modified and saved back down to update the database.
  • Record objects can be destroyed, deleting the corresponding rows in the database.
  • Record objects automatically have access to associated data stored in the database when they are first instantiated.
  • Associated data is loaded into sub-objects accessed as properties of the primary record object. This is as expected if you've worked much with ActiveRecord.
  • Any custom methods provided in the model definition will be made available to record objects returned by the model.
  • Any validations or callbacks provided in the model definition will be called automatically on save, on update, or during specified actions.

While we'd like to think JazzRecord is all but difficult to use, there are of course caveats.

Requirements

JazzRecord requires one of the following JavaScript development environments:

  • Google Gears, a cross-browser JavaScript development environment
  • Adobe AIR, a standalone product for developers looking to do desktop development within the familiar confines of JavaScript.
  • Appcelerator Titanium (PR2 only for now), another upcoming, standalone, JavaScript development environment

Note that JazzRecord is intended for use with JavaScript projects only, not Flash-based apps.

If you are using Gears or AIR, you must load either gears_init.js (for Gears) or AIRAliases.js (for AIR). These files must be loaded before jazz_record.js.

In order to fully appreciate JazzRecord, you'll want a console to debug with, view log statements with, and possibly grow old with. For that, of course, we recommend the amazing Firebug and Firebug Lite in browsers, although Safari/Webkit/Chrome have built in consoles that aren't too shabby. In Adobe AIR, we recommend running AIRIntrospector.

Limitations of JazzRecord

For the most part, JazzRecord follows ActiveRecord concepts once its data and models are in place. Qeurying models and working with records is mostly the same. However, keep a few things in mind:

  1. Currently, there is no formal migration syntax. This is under development but not yet ready for prime time.
  2. Model definition and table definition usually happen in the same place, and are the basis for "automigration", which allows Jazz to build model tables and mapping tables based on model declarations provided prior to a call to the function migrate().
  3. JazzRecord only loads 1 level of associations by default. This can be overridden as a config option in your code, or overridden per each call to one of the finder methods.
  4. Association data beyond the pre-loaded depth is easily retrievable by calling the load() method of the primary record object.
  5. JazzRecord does not handle any of the more complicated ActiveRecord magic, like "has many through", or polymorphism (STI or inherited models) as of yet.