NSRails is a light-weight Objective-C framework that provides your classes with a high-level, ActiveResource-like API. This means CRUD and other operations on your corresponding Rails objects can be called natively via Objective-C methods.
Instances will inherit methods to remotely create, read, update, or destroy a remote object:
Post *newPost = [[Post alloc] init];
newPost.author = @"Me";
newPost.content = @"Some text";
// Create this post with its properties right on a Rails server
// POST /posts.json
[newPost remoteCreateAsync:^(NSError *e) {
if (e) { ... }
}];
Classes will inherit methods to retrieve all objects, or only certain ones:
// GET /posts.json
[Post remoteAllAsync:^(NSArray *allPosts, NSError *error) {
//allPosts => [<#Post1#>, <#Post2#>]
}];
// GET /posts/1.json
[Post remoteObjectWithID:1 async:^(Post *post, NSError *error) {
//post => <#Post#>
//post.content => "First!!11!"
}];
NSRails is accessible while very flexible, and keeps your code clean and organized. It uses your classes' names and standard @properties
to map to your remote models, so it's easy to fit into any project.
- High-level API, yet flexible enough even to work with any RESTful server
- Highly customizable property behaviors and nesting
- Seamless CoreData support
- Asynchronous requests
- Fully supported in RubyMotion and MacRuby
- Written with ARC
- Autogenerate NSRails-ready classes from a Rails project
- Documentation
- CoreData guide
- Cookbook
- Hop on Gitter if you need any help or want to talk about the project!
(Note: getting started using NSRails with Ruby has been moved here.)
- Add NSRails to your project. You can:
- Use CocoaPods (highly recommended.) Add
pod 'NSRails'
to your Podfile, orpod 'NSRails/CoreData'
if you're using CoreData. - If you're not using CocoaPods, or maybe you're really lazy, you can drop the Source folder into your project. But if you're using CoreData, you must also add
#define NSR_USE_COREDATA
to your Prefix.pch file, or addNSR_USE_COREDATA
to Preprocessor Macros in your Build Settings.
- Make a class for your Rails model that subclasses NSRRemoteObject (or NSRRemoteManagedObject with CoreData)
#import <NSRails/NSRails.h>
@interface Post : NSRRemoteObject //NSRRemoteManagedObject with CoreData
@property (nonatomic, strong) NSString *author, *content;
@property (nonatomic, strong) NSDate *createdAt;
@end
- Set your server URL in your app setup:
#import <NSRails/NSRails.h>
- (BOOL)application:(UIApplication *)app didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[NSRConfig defaultConfig].appURL = @"http://localhost:3000";
// If you're using Rails 3
//[[NSRConfig defaultConfig] configureToRailsVersion:NSRRailsVersion3];
...
}
Note: By default, NSRails assumes you're using Rails 4. If not, make sure you configure to Rails 3 standards (ie, PUT instead of PATCH and a different date format) as shown above.
You're done! By subclassing NSRRemoteObject, your class gets instance and class methods that'll act on your remote objects. Here are a few of the things you can do with your new class:
// Retrieve post with ID 1
Post *post = [Post remoteObjectWithID:1 error:&error];
// Update this post remotely
post.content = @"Changed!";
[post remoteUpdate:&error];
// Fetch any latest data for this post
[post remoteFetch:&error];
// Retrieve a collection based on an object - will GET /posts/1/responses.json
NSArray *responses = [Response remoteAllViaObject:post error:&error];
// Async is also available for all commands, with blocks!
[post remoteDestroyAsync: ^(NSError *error) { if (!error) ... }];
See the documentation for more on what you can do with your new class, or the cookbook for quick NSRRemoteObject recipes.
- iOS 5.0+
- Automatic Reference Counting (ARC): If your project isn't using ARC, you'll need to selectively specify it for NSRails. Go to your active target, select the "Build Phases" tab, and in the "Compile Sources" section, set
-fobjc-arc
as a compiler flag for each NSRails source file.
NSRails is written and maintained by Dan Hassin. A lot of it was inspired by the ObjectiveResource project, many thanks there!