mattvague/ttresource

A first cut attempt to build a Three20 equivalent to ObjectiveResource, also backed by ObjectiveSupport

TTResource

Overview

TTResource sets out to solve the following dilemma: you (an iPhone application developer) are using either ObjectiveResource or Three20 but you want to also use the other one. On its face, that isn't an unreasonable desire--after all, they seem to be accomplishing wholly different objectives:

• ObjectiveResource sets out to handle automatic marshalling and unmarshalling of model objects that are backed in the cloud by RESTful services provided by Ruby on Rails
• Three20, meanwhile, provides some nifty views and controls, convenient extensions to UIKit, a novel CSS-like styling engine, and a means of intra-app navigation using URLs. (I gave a presentation summing up these four points: slides)

Right, So What's the Problem?

The problem is that ObjectiveResource and Three20 don't always play particularly well together. Neither thematically nor technically.

• ObjectiveResource's API was designed to handle all URL requests synchronously, while Three20's view controllers, TTModel, and TTURLRequest facilities were designed to encourage getting remote data loading out of the way of the main UI thread.
• As such, classes using ObjectiveResource to connect to a Rails backend are put at a disadvantage in the context of a Three20 app. They can't benefit from the on-disk caching or request queue management offered by Three20's TTURLRequest and TTURLRequestQueue.
• Additionally, Three20's included implementations of TTModel (like TTURLRequestModel), which can keep a view controller quite abreast of the status/readiness of the data model (e.g. loading, out of date, ready, etc.), rely on using the TTURLRequest class to make requests. More fundamentally, the TTModel protocol itself doesn't make very much sense when all requests take place synchronously on the main thread (though, in fairness to ObjectiveResource, there's a somewhat terse workaround for that).
• There are a couple minor bugs/hiccups to experience when first bringing together the two libraries into a single application (example).

And how is TTResource the solution?

First, a note: kudos to the folks that wrote ObjectiveResource, because they were smart enough to modularize almost all the code that does the real heavy lifting--the utilities to de/serialize and service objects impacted by RESTful service invocations--into a separate library called ObjectiveSupport. ObjectiveResource itself is actually pretty lightweight and cohesive.

Because ObjectiveResource is so lightweight, it actually didn't take long to realize that the most effective approach would be to re-implement it entirely, as if it had been written as part of a Three20 application from the start. So there you have it: what's called TTResource is essentially an ObjectiveResource rewrite. Like ObjectiveResource, it still depends on classes provided by ObjectiveSupport to do almost all of the hard stuff. And like a Three20 application, it still depends on classes provided by Three20 to do most of the hard stuff. TTResource, therefore, is just a little bit of other (presumably easy?) stuff to bridge the gap between them.

Last, another note: since TTResource itself borrows code directly from ObjectiveResource where it made sense to reuse it, I've attributed Y Factorial on each applicable copyright notice in the source and on the license file.

Adding TTResource to your project

Note: TTResource is pre-pre-pre-Alpha. It does not yet work. Do not add TTResource to your existing applications unless you plan to pitch in and contribute.

Note #2: Please pitch in and contribute!

1. Clone the TTResource repository to a permanent location on your hard drive:

    $ git clone git://github.com/searls/TTResource.git

2. TTResource depends on three20 and ObjectiveSupport, so immediately after cloning, you will need to:

	$ cd TTResource
	$ git submodule init
	$ git submodule update

3. Find TTResource.xcodeproj in Finder, then drag-and-drop it into your project's "Groups & Files" pane in Xcode underneath your Project.
   • Uncheck "Copy items"
   • Set "Reference Type" to "Relative to Project"
   • Check "Recursively create groups for any added folders"
4. Click "TTResource.xcodeproj" in your "Groups & Files" pane, and in the upper right, you should see a file named "libTTResource.a". Check the checkbox to the far right with a bullseye above it.
5. Set up the project's dependencies.
   1. From the menu bar, select "Project" -> "Edit Project Settings" and click the "General" tab.
   2. Click the + icon under "Direct Dependencies" and add TTResource.
6. Set up the project settings
   1. From the menu bar, select "Project" -> "Edit Project Settings" and click the "Build" tab.
   2. Set Configuration to All Configurations
   3. Under "Other Linker Flags" add both: -all_load and -ObjC
   4. Under "Header Search Paths", add the relative path from your XCode project to the TTResource source files. If your project and TTResource shared the same root folder, this would be "../TTResource/src"

Usage Example

Included in the git repository is a (very) simple Ruby on Rails application and a (very) simple TTResource project called TTResourceSample. To use the sample project and back it with the sample Rails app, you'll need to first start the Rails server:

1. First install Ruby and Rails, something most users of this library are probably familiar with.
2. Start the server:

	$ cd remote/ttresource
	$ script/server

3. Next, open sample/TTResourceSample/TTResourceSample.xcodeproj in Xcode.
4. Observe the meager code in TTResourceSampleAppDelegate.m and try a Build & Run, then monitor the results.