Discussion

This will include properties that you may not have defined in your Objective-C class, allowing you to dynamically add fields to your app if the server-side model changes. This dictionary won’t go through any of the encoding methods - it’ll be exactly the dictionary as was sent in JSON.

You’re safe to use this property after any method that sets your object’s properties from remote. For example:

NSError *error;
if ([myObj remoteFetch:&error])
{
    NSDictionary *hashSentByRails = myObj.remoteAttributes;
    …
}

Calling setPropertiesUsingRemoteDictionary: will also update remoteAttributes to the dictionary passed in.

Discussion

If true, this object will include a _destroy key on send (ie, when the model nesting it is sent during a remoteUpdate: or remoteCreate:).

This can be useful if you have a lot of nested models you need to destroy - you can do it in one request instead of several repeated destroys on each object.

Note that this is relevant for a nested object only. And, for this to work, make sure :allow_destroy => true is set in your Rails model.

Discussion

It should be noted that this property will be automatically updated after remoteCreate, as will anything else that is returned from that create.

Discussion

The default behavior is to return <NSRConfig’s> contextuallyRelevantConfig.

Discussion

Makes a GET request to /objects (where objects is the pluralization of receiver’s model name.)

Request made synchronously. See remoteAllAsync: for asynchronous operation.

Discussion

Asynchronously makes a GET request to /objects (where objects is the pluralization of receiver’s model name.)

Discussion

Asynchronously makes a GET request to /parents/3/objects (where parents/3 is the path for the parentObject, and objects is the pluralization of this model name.)

Discussion

Makes a GET request to /parents/3/objects (where parents/3 is the path for the parentObject, and objects is the pluralization of this model name.)

Request made synchronously. See remoteAllViaObject:async: for asynchronous operation.

Discussion

The default behavior (when not overriden) is to pluralize remoteModelName, so if your class was calledUser, by default requests involving its controller would be routed to/users. In the example above for custom model names, it would go to/subscribers` since remoteModelName was overridden.

However, this can be overridden as well, if, lets say, you have an irregular plural:

 @implementation Cactus

 + (NSString *) remoteControllerName
 {
    return @"cacti";
 }

 @end

Default Behavior (when not overriden)

Pluralizes remoteModelName.

Discussion

remoteModelName should be overriden if the name of this class in Objective-C is different than its corresponding model on your server. Recommended overriding behavior is to return a string literal:

 @implementation User

 + (NSString *) remoteModelName
 {
     return @"subscriber";
 }

 @end

The above example would be needed if the same class is called User in Objective-C but Subscriber on your server.

Default Behavior (when not overriden)

Returns the name of the subclass, lowercase and underscored if enabled, and with its prefix stripped if enabled.

Discussion

Asynchronously makes a GET request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is objectID)

Discussion

Makes a GET request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is objectID

Request made synchronously. See remoteObjectWithID:async: for asynchronous operation.

Discussion

This method should be overridden if you have a property whose JSON representation should be different than its actual object value when sending and retrieving to/from Rails.

 @interface MyClass : NSRRemoteObject

 @property (nonatomic, strong) NSURL *URL;         //on the server this is a plain string
 @property (nonatomic, strong) NSArray *csvArray;  //on the server this is a comma-separated string

 @end

In the example above, we want URL to be decoded (saved) as an NSURL locally and csvArray to be decoded as an NSArray locally, but Rails sends them to us as plain strings. Here’s a possible overridden implementation:

 - (void) decodeValue:(id)remoteObject forRemoteKey:(NSString *)remoteKey
 {
     if ([forRemoteKey isEqualToString:@"csv_array"])
     {
        self.csvArray = [remoteObject componentsSeparatedByString:@","];
     }
     else if ([forRemoteKey isEqualToString:@"url"])
     {
        self.URL = [NSURL URLWithString:remoteObject];
     }
     else
     {
        [super decodeValue:remoteObject forRemoteKey:remoteKey];
     }
 }

Note: the default implementation of this method will automatically take care of NSDates for you, decoding them into an NSDate object using the Rails date format. The format used can be changed in this NSRConfig property.

Also note that this should not be overridden for only a simple change in local/remote property naming. If your server has a different property name than your Objective-C code, but otherwise decodes the same, simply override propertyForRemoteKey:.

Discussion

This method should be overridden if you have a property whose JSON representation should be different than its actual object value when sending and retrieving to/from Rails.

 @interface MyClass : NSRRemoteObject

 @property (nonatomic, strong) NSURL *URL;         //on the server this is a plain string
 @property (nonatomic, strong) NSArray *csvArray;  //on the server this is a comma-separated string

 @end

In the example above, we can’t send these objects to a server as-is, since the server expects strings for both of these. We want to send URL as its actual content (remember, NSURL is not JSON-encodable), and send the array csvArray as a plain, comma-separated string. Here’s a possible overridden implementation:

 @implementation MyClass

 - (id) encodeValueForProperty:(NSString *)property remoteKey:(NSString **)remoteKey
 {
     if ([property isEqualToString:@"csvArray"]) {
         return [csvArray componentsJoinedByString:@","];
     }

     if ([property isEqualToString:@"URL"]) {
         return [URL absoluteString];
     }

     return [super encodeValueForProperty:property remoteKey:remoteKey];
 }

 @end

Moreover, custom remote keys can be defined here, if the names of your Objective-C property and remote attribute differ. Simply set the contents of the remoteKey reference. That’s the key it will be sent with.

 - (id) encodeValueForProperty:(NSString *)property remoteKey:(NSString **)remoteKey
 {
     if ([property isEqualToString:@"objcProperty"]) {
         *remoteKey = @"rails_attr";
     }

     return [super encodeValueForProperty:property remoteKey:remoteKey];
 }

Note: the default implementation of this method will automatically take care of NSDates for you, encoding them into a date format string that’s Rails-friendly. The format used can be changed in this NSRConfig property.

Discussion

The default behavior is to simply return the type of the property if it is a subclass of NSRRemoteObject. Otherwise, returns nil.

This must be overriden for any to-many relationships (since the property type is just an array, and NSRails doesn’t know what kind of object should be stored).

 - (Class) nestedClassForProperty:(NSString *)property
 {
     // Only necessary for 'responses' (to-many)
     // By default, the Author class (to-one) will be picked up through its property type
     if ([property isEqualToString:@"responses"]) {
         return [Response class];
     }

     return [super nestedClassForProperty:property];
 }

Ruby:

 # Because Ruby is not statically typed, this must be overriden for all relationships (necessary for both)
 # NSRails can't "guess" what class you want to nest in a property

 def nestedClassForProperty(property)
   return Response if property == "responses"
   return Author if property == "author"
 end

Discussion

This may be needed if you define your routes in Rails to look something like:

 MySweetApp::Application.routes.draw do
   resources :users
     resources :invites
   end
 end

Typically, this method is overriden with an instance variable that represents a parent:

 @implementation Invite

 - (NSRRemoteObject *) objectUsedToPrefixRequest:(NSRRequest *)request
 {
     return self.user;
 }

 @end

Now, invites will be accessed in relation to the given user (assume its remoteID is 1):

 GET    /users/1/invites.json
 POST   /users/1/invites.json
 GET    /users/1/invites/3.json
 DELETE /users/1/invites/3.json

Note that if user’s remoteID is nil, an exception will be thrown (its ID is needed in constructing the route).

You may also filter requests that you don’t want to prefix using the request parameter. Let’s say you only want this behavior for POST and GET, but want to keep DELETE and PATCH with their traditional routes:

 GET    /users/3/invites.json  "get all the invites for user 3"
 POST   /users/3/invites.json  "create an invite for user 3"
 PATCH  /invites/28.json       "update user invite 28"
 DELETE /invites/28.json       "delete user invite 28"

This could be done by checking request’s httpMethod:

 - (NSRRemoteObject *) objectUsedToPrefixRequest:(NSRRequest *)request
 {
     if ([request.httpMethod isEqualToString:@"GET"] || [request.httpMethod isEqualToString:@"POST"]) {
         return user;
     }
     return nil;
 }

Discussion

For example, will return updatedAt (the Objective-C property) for the updated_at key in an incoming dictionary, assuming that your class defines an updatedAt property.

The default behavior is to autoinflect into camelCase (if enabled), or convert id to remoteID. If the resulting conversion is not found as a property in the class, returns nil.

Overriding example:

 - (NSString *) propertyForRemoteKey:(NSString *)remoteKey
 {
     //the "rails" key given from a Rails hash will be translated to the "objc" property when decoding
     if ([remoteKey isEqualToString:@"rails"]) {
         return @"objc";
     }

     return [super propertyForRemoteKey:remoteKey];
 }

It is possible to also override decodeRemoteValue:forRemoteKey: and setting the objc property manually for a remoteKey of “rails”, but since decodeRemoteValue:forRemoteKey: uses this method internally, it is cleaner to just override this method.

The inverse method remoteKeyForProperty does not exist - instead override encodeValueForProperty:remoteKey: and modify the remote key.

Discussion

NSRails has no idea what types your properties are in Ruby, so to benefit from automatic Date -> string and string -> Date, it needs to know what properties are dates.

This is unnecessary in Objective-C.

 def propertyIsDate(property)
   (property == "birthday") || super
 end

Note that created_at and updated_at are already taken care of as dates.

Discussion

Sends a POST request to /objects (where objects is the pluralization of receiver’s model name), with the receiver’s remoteDictionaryRepresentationWrapped:YES as its body. Request made synchronously. See remoteCreateAsync: for asynchronous operation.

Discussion

Asynchronously sends a POST request to /objects (where objects is the pluralization of receiver’s model name), with the receiver’s remote dictionary representation as its body.

Discussion

Sends a DELETE request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID). Request made synchronously. See remoteDestroyAsync: for asynchronous operation.

Discussion

Asynchronously sends a DELETE request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID).

Discussion

Sends a GET request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID).

Request made synchronously. See remoteFetchAsync: for asynchronous operation.

Requires presence of remoteID, or will throw an NSRNullRemoteIDException.

Discussion

Asynchronously sends a GET request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID).

Requires presence of remoteID, or will throw anNSRNullRemoteIDException`.

Discussion

Default behavior is to introspect into the class and return an array of all non-primitive type properties. This also escalates up the class hierarchy to NSRRemoteObject’s properties as well (ie, remoteID).

If you want to override this, you should add or remove objects from super:

 - (NSMutableArray *) remoteProperties
 {
     NSMutableArray *props = [super remoteProperties];

     //remove an object from NSRails entirely
     [props removeObject:@"totallyLocal"];

     //can even add a property not defined in your class - encodable in encodeValueForProperty:remoteKey:
     [props addObject:@"totallyRemote"];

     return props;
 }

Ruby:

Overriding this method, adding on all of your instance variables is necessary in RubyMotion because properties are created on runtime and Objective-C introspection won’t apply.

 def remoteProperties
   super + ["author", "content", "created_at"]
 end

Discussion

Sends an PUT request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID).

The distinction between this method and remoteUpdate: is that this method will always use the PUT HTTP method, while remoteUpdate: is configurable. This is to allow servers that use PATCH to update attributes using remoteUpdate: and keep remoteReplace: for a more accurate “placement” procedure that should occur with the PUT method. More discussion here.

Request made synchronously. See remoteReplaceAsync: for asynchronous operation.

Requires presence of remoteID, or will throw anNSRNullRemoteIDException`.

Discussion

Asynchronously sends an PUT request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID).

The distinction between this method and remoteUpdateAsync: is that this method will always use the PUT HTTP method, while remoteUpdateAsync: is configurable. This is to allow servers that use PATCH to update attributes using remoteUpdateAsync: and keep remoteReplaceAsync: for a more accurate “placement” procedure that should occur with the PUT method. More discussion here.

Requires presence of remoteID, or will throw anNSRNullRemoteIDException`.

Discussion

Sends a request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID). Will use the HTTP method defined in the relevant config’s updateMethod property (default PUT).

Request made synchronously. See remoteUpdateAsync: for asynchronous operation.

Requires presence of remoteID, or will throw anNSRNullRemoteIDException`.

Discussion

Sends a request to /objects/1 (where objects is the pluralization of receiver’s model name, and 1 is the receiver’s remoteID). Will use the HTTP method defined in the relevant config’s updateMethod property(default PUT).

Requires presence of remoteID, or will throw anNSRNullRemoteIDException`.

Discussion

Uses the coding methods.

Will set remoteAttributes to dictionary.

Discussion

The default behavior is to return NO. (You don’t have to make a call to super here.)

This is useful if you have a property whose relationship is “belongs to”. Meaning, the receiving object on the server holds the foreign key - it has, say, a parent_id, which you want sent instead of parent_attributes (which would anger Rails).

 - (BOOL) shouldOnlySendIDKeyForNestedObjectProperty:(NSString *)property
 {
    return [property isEqualToString:"group"];
 }

Discussion

Will only be called for collection properties.

Discussion

Default behavior is to not send if:

• Property is remoteID and it is nil, or, nested is false. (Sending id is only relevant to ensure nested objects are not re-created.)
• Property is not a timestamp (created at, updated at).
• Property is a relationship, would send the full _attributes, and nested is true (ie, only send “shallow” copies of objects when they are being nested. This is to prevent infinite loops when recursively sending nested properties that could also include this object).
• Property is a relationship, but the value of the property is either nil or an empty collection. (No reason to send empty _attributes).

Otherwise the property is sent. So typically, this method is overridden if you do not wish to have a property in an outgoing request. Overriding this method would look like this:

 - (BOOL) shouldSendProperty:(NSString *)property whenNested:(BOOL)nested
 {
    //never send retrieveOnlyProperty to your server
    if ([property isEqualToString:@"retrieveOnlyProperty"]) {
        return NO;
    }

    //deepNest is a property with a has-one/has-many relationship that would otherwise not be sent when this object is *nested*
    if ([property isEqualToString:@"deepNest"] && nested) {
        return YES;
    }

    return [super shouldSendProperty:property whenNested:nested];
 }

The equivalent for this method for retrieving properties (“shouldSetProperty”) is done through decodeRemoteValue:forRemoteKey:. Simply override it and do nothing for that property if you do not want to decode & set it from a remote value.