Chocobo

Backbon-ify your iOS models and make it extremely easy to communicate with a RESTful API. Provides an easy API to connect, communicate and return success/failure events.

Installation

Chocobo is available through CocoaPods, to install it simply add the following line to your Podfile:

pod "Chocobo"

There's one other step that you will need to do in order to get it working. Add a file to your project and call it 'Environments.plist'. Inside of there you will need to specify your different API environments you want to use.

Now finally add a 'Configuration' parameter to your app's plist.

# support/appName.plist

Configuration (String) 'dev(or whatever you named your environment you want to use)'

Usage

Chocobo allows you to easily create async models/collections in your iOS app to communicate easily with a RESTful API.

Models

Extend your model from the Model object and specify all the attributes using properties.

@interface User : Model

@property (nonatomic, copy) NSNumber *userId;
@property (nonatomic, copy) NSString *firstName;
@property (nonatomic, copy) NSString *lastName;
@property (nonatomic, copy) NSString *email;

@end

Next you will need to override the models method 'updateModelWithJson:'

-(void) updateModelWithJson:(NSDictionary *)json
{
    NSDictionary *attributes = [json valueForKey:@"user"];
    self.userId = [attributes valueForKey:@"id"];
    self.firstName = [attributes valueForKey:@"first_name"];
    self.lastName = [attributes valueForKey:@"last_name"];
    self.email = [attributes valueForKey:@"email"];
}

Now you can call:

[self fetchFromEndpoint:@"login.json" withParams:parameters onSuccess:^(id responseObject) {

        NSLog(@"Do Something with your response object here");

    } onFailure:^(NSError *error)  {

        NSLog(@"Do something with the error");

    }];

Collections

Collections will extend off the Collection object.

#import "Collection.h"

@interface Users : Collection

@end

Your collection will then need to overide 2 functions

-(id)model
{
    return @"User";
}

-(NSString *)collectionEndpoint
{
    return @"users.json";
}

This will allow the collection to automatically grab all the models from the collection endpoint and set them in the models array.

Accessing the models in a collection are easy. Just use the models accessor.

[[collection models] objectAtIndex: 0];

Has Many Relationships

Setting up a has many relationship in your model is easy. Set up an NSMutableArray as a property on the model of the model type that the relationship is set.

# models/user.h

@property (nonatomic, retain) NSMutableArray *accounts;

Synthesize and set up the relationship in a loop inside your updateModelWithJson: function

# models/user.m

@synthesize wells = _wells;

-(void) updateModelWithJson:(NSDictionary *)json
{
    for (NSDictionary* key in [json valueForKey:@"accounts"]) {
        Account *accountModel = [[Account alloc] init];
        [accountModel updateModelWithJson:key];

        [self.accounts addObject:account];
    }
}

Has One Relationships

To setup a has one relationship on your models, set up a property on your model of the type you would like to set it up with.

# models/user.h

#import 'Account.h'

@property (nonatomic, retain) Account *account;

And then in updateModelWithJson:

# models/user.m

-(void) updateModelWithJson:(NSDictionary *)json
{
    Account *account = [[Account alloc] init];
    [account updateModelWithJson: [json valueForKey:@"account"]];
    self.account = account;
}

Development

To run tests cd into the Tests directory and run pod install. Then open the Chocobo.xcworkspace and run command + u. The Scheme must be set to TestsTests:

License

Creative Commons 3.0 - Attribution Sharealike

You can remix, copy or use for both commercial and non-commercial products and services but you need to provide attribution for the original work in the source code to "PetroFeed Inc.". You must also share the original or any derivative under the same license. A description of the license can be found here.