Alexis Smirnov

Enough snow?

Sun, 06 Feb 2011 06:41:03 -0800

Looking for a simpler way to work with the SproutCore store and records

Thu, 11 Nov 2010 09:12:00 -0800

This post is about SproutCore programming and assumes familiarity with the framework.

The traditional pattern of working with store's records is to set up a binding via a controller and handle a data change event. At high level, it goes something like this:

1. Request the creation of RecordArray via App.store.find() method

2. Set the record array as the "content" in an ArrayController

3. Bind a view to the content property of that ArrayController

First two steps are done together, usually when a state is setup. For example, say you want to show some contacts. You'd write some something like this:

App.contactsState = SC.Responder.create( {

didBecomeFirstResponder : function() {

var records = App.store.find(App.contactsQuery);

App.contactsController.set('content', records);

}

});

The third step of binding is done in a view eg.

view = App.ContactsView.design({

contentBinding : 'App.contactsController.arrangedObjects'

});

This pattern works great when you need a static relationship between a piece of data and a view. In this example we have a static binding between a set of contacts and the view that shows them.

However there are cases that don't call for a static binding relationship. Cases where an app simply wants to make a query, get the data, and act on it. These cases usually happen then an app needs to process a event eg. user action (button click), or server response. Handling these cases is quite convoluted with the pattern above.

For example, say you need to implement a button that sends a message to a subset of your contacts eg. "favorite contacts".

You cannot write:

onClickSendMessageToFavoriteContacts: function() {

var favoriteContacts = App.store.find(App.favoriteContactsQuery);

favoriteContacts.forEach(function(contact) {App.sendSomeMessage(contact);});

}

because find() cannot return the results when they haven't been retrieved yet (from the server, from local DB, etc.). By the time find() returns the RecordArray favoriteContacts can be empty and would be in the BUSY_LOADING state.

Instead the button handler would have to do the following:

1. create a new query -- because we want to select a subset of the data given a specific criteria (eg. select favorite contacts)

2. create a new controller -- because we need a way to be notified when the results of the query are available

3. setup an observer/binding that will wait until the results are available

4. perform the action (sending a message to favorite contacts)

5. tear down the observer relationship -- because we no longer interested in paying the cost of having "favorite contacts" be kept up to date

6. remove the record array -- because the array is no longer needed and would simply take up memory

Ideally we'd want a more direct way to act on the results of queries. Imagine being able to write:

App.Contact.objects().filter({varotite: YES}, function(contacts) {sendMessage(contacts);});

A filter() method would perform all the necessary steps to make sure that when the callback is called, the data is available. It would also tear-down all the bindings needed to make it happen. Similarly, one can imagine an API like:

App.Contact.objects().all().del()

App.Contact.objects().all(function(records) {dome something with all Contacts})

Those who are familiar with Django will recognize this API as similar to QuerySet (http://docs.djangoproject.com/en/dev/ref/models/querysets/), but modified to deal with asynchronous nature of JavaScript programming.

Getting an object would become:

App.Contact.objects().runGet({guid: '123'}, function(contact) { do something with contact 123 });

A multi-step operation such as getting or creating an object can also be hidden inside a method (see Django's version here: http://www.djangoproject.com/documentation/models/get_or_create/):

App.Contact.objects().runGetOrCreate({firstName: 'John', lastName: 'Lennon'}, {'birthday': '1940-10-9'}, function(john) { ... });

I've put an implementation sketch here:


App.ObjectsController = SC.ArrayController.extend({
	/**
	 * Pseudo-synchronous API to handle all objects of a given type.
	 * 
	 * This API in intended to hide the asynchronous nature of retrieving
	 * records by providing a callback to be called when the data in available.
	 * 
	 * Example usage:
	 * App.MyModel.objects().all(function(obj) {console.log(obj);));
	 */
	all: function(onSuccess, onError) {
		var records = this.get('content'),
			_statusDidChange = function() {
				if( this.status & SC.Record.READY_CLEAN && onSuccess) {
					// Now that the records are in READ_CLEAN state, call
					// the callback
					onSuccess(this);

					// Now that we've handled the event, we no longer need
					// to be listening for the status
					records.removeObserver('status', statusDidChange);
				}
			};

		// No records yet, launch the find() request for all objects of the
		// parentType
		if( !records ) {
			var parentType = this.get('parent');
			var store = this.get('store');

			records = store.find(parentType);
			this.set('content', records);
		}

		// If the records aren't ready yet, defer calling onSuccess
		if( onSuccess ) {
			if( records.status & SC.Record.READY_CLEAN )
				onSuccess(records);
			else
				records.addObserver('status', _statusDidChange);
		}
		return this;
	},

	/**
	 * Delete all objects contained objects
	 */
	del: function() {
		var records = this.get('content'),
			_del = function(records) {
				records.forEach(function(record) {
					record.store.destroyRecord(undefined, 
											undefined, 
											record.storeKey);
				});
				records.destroy();
			};

		if( records.status & SC.Record.READY_CLEAN ) {
			_del(records);
		} else {
			var _statusDidChange = function() {
				if( records.status & SC.Record.READY_CLEAN ) {
					console.log('deleting %@'.fmt(this));
					_del(this);
					this.removeObserver('status', statusDidChange);
				}
			};
			records.addObserver('status', _statusDidChange);
		}
	},

	runGet: function(queryConditions, onSuccess, onError) {
		var parentType = this.get('parent'),
		store = this.get('store'),
		queryString = '',
		andString = '',
		query = null,
		records = null,
		_statusDidChange = function() {
			console.log('status change: %@'.fmt(records.status));

			if( records.status & SC.Record.READY_CLEAN ) {
				if( records.length() === 1 && onSuccess ) { 
					onSuccess(records.objectAt(0));
				}
				if( records.length() != 1 && onError ){
					onError();
				}

				// Now that the READY state is handled, the observer is
				// no longer needed. So remove it.
				records.removeObserver('status', _statusDidChange);
				records.destroy();
			}
		};

		for( condition in queryConditions ) {
			if (queryConditions.hasOwnProperty(condition)) {
				queryString = '%@ %@ %@="%@"'.fmt(queryString, andString, condition, queryConditions[condition]);
				andString = "and";
			}
		}

		query = SC.Query.local(parentType, queryString);
		records = store.find(query);

		if( records.status & SC.Record.READY_CLEAN ) {
			_statusDidChange();
		} else {
			records.addObserver('status', _statusDidChange);
		}
	},
	/**
	 * Usage example:
	 * 
	 * MyApp.MyModel.objects().getOrCreate(
	 * 				'guid = 1', 
	 * 				{quid: 1, foo, 'bar'}, 
	 * 				function(result, created) {
	 * 					console.log('got %@ created? %@'.fmt(result, created);
	 * 				});
	 */
	getOrCreate: function(queryConditions, defaults, onSuccess, onError) {
		var parentType = this.get('parent'),
			store = this.get('store'),
			queryString = '',
			andString = '',
			query = null,
			records = null,
			_createRecord = function() {
				// If the conditions or defaults include the primary key,
				// it will be extracted from the defaults and be used as the ID
				// for the record.
				var record = store.createRecord(parentType, defaults);
				onSuccess(record, YES);
			},
			_statusDidChange = function() {
				if( records.status & SC.Record.READY_CLEAN ) {
					console.log('callback received records ready');
					if( records.length() > 1) {
						var handler = onError || console.log;
						handler('getOrCreate returned %@ records'.fmt(records.length()));
					}
					if( records.length() === 0) {
						_createRecord();
					}
					if( records.length() === 1 && onSuccess ) { 
						onSuccess(records.objectAt(0), NO);
					}
					// Now that the READY state is handled, the observer is
					// no longer needed. So remove it.
					records.removeObserver('status', _statusDidChange);
					records.destroy();
				}
			};

		for( condition in queryConditions ) {
			if (queryConditions.hasOwnProperty(condition)) {
				queryString = '%@ %@ %@="%@"'.fmt(queryString, andString, condition, queryConditions[condition]);
				andString = "and";
				defaults['%@'.fmt(condition)] = queryConditions[condition];
			}
		}			
		query = SC.Query.local(parentType, queryString);
		records = store.find(query);

		if( records.status & SC.Record.READY_CLEAN ) {
			_statusDidChange();
		} else {
			records.addObserver('status', _statusDidChange);
		}
	}
});
/*---------------------------------------------------------------------------*/

App.Record = SC.Record.extend({});
App.Record.mixin({
	_objects: null,
	objects: function() {
		if( !this._objects ) {
			this._objects = App.ObjectsController.create({parent: this, store: App.store});
		}
		return this._objects;
	}
});

App.Account = App.Record.extend( {
	accountClass : SC.Record.attr(String, {defaultValue: 'email/gmail'}),
	password : SC.Record.attr(String),
	name : SC.Record.attr(String)
});

App.User = App.Record.extend( {
	username : SC.Record.attr(String)
});

App.Message = App.Record.extend({
	body : SC.Record.attr(String)
});

and would love to hear any feedback. It is structured as a mixin to the Model and tracks the record states in order to call the callback at the right time.

Do you think SC's data model API should be improved? Can it be improved? Am I approaching the implementation from the right perspective? Does this idea have any fundamental issues with performance?

Alexis Smirnov

Enough snow?

Looking for a simpler way to work with the SproutCore store and records

Stanford's Entrepreneurship Corner: Marc Andreessen

StartupSquare Montreal and MTL NewTech

StartupSquare

Montreal New Tech

Amazon Simple Notification Service

A 2.5 Year-Old Uses an iPad for the First Time

Google Code Blog: OAuth access to IMAP/SMTP in Gmail

Placehold.it

Wanted: Greasemonkey script to share Hacker News up-votes

How to Replace IMAP

The Google Account problem

do

Disqus Commenting System

ZSync: sync library

Google Buzz re-invents Gmail - O'Reilly Radar

post.ly has a nice UI

Art of Paper Folding

Pictures

Writing Great Documentation

There are Over a Million People Actively Using Facebook Right Now