Inherits from _NSR_SUPERCLASS
Conforms to NSCoding
Declared in NSRRemoteObject.h

Overview

NSRRemoteObject is the primary class in NSRails - any classes that subclass it will be treated with a “remote correspondance” and ActiveResource-like APIs will be available.

Note that you do not have to define an id property for your Objective-C class, as your subclass will inherit NSRRemoteObject’s remoteID property.

CoreData

To use NSRails with CoreData, subclass NSRRemoteManagedObject.

Validation Errors

If a create or update failed due to validation reasons, NSRails will package the validation failures into a dictionary. This can be retrieved using the key constant NSRErrorResponseBodyKey in the userInfo property of the error. This dictionary contains each failed property as a key, with each respective object being an array of the reasons that property failed validation. For instance,

 NSError *error;
 if (![user createRemote:&error])
 {
     NSDictionary *validationErrors = [[error userInfo] objectForKey:NSRErrorResponseBodyKey];

     for (NSString *property in validationErrors)
     {
         for (NSString *reasonForFailure in [validationErrors objectForKey:property])
         {
             NSLog(@"%@ %@",property,reasonForFailure);  //=> "Name can't be blank"
         }
     }
 }

Overriding Behavior

See the “Methods to Override” section of this class reference. These methods can be overriden for custom per-property behavior.

Remember, these are not delegate methods. You must make a call to super if you’re not overriding behavior for that property.

Finally, check out the NSRails Cookbook for quick overriding recipes.

Tasks

Properties

  •   remoteID

    The corresponding local property for remote attribute id.

    property
  •   remoteAttributes

    The most recent dictionary of all properties returned by Rails, exactly as it returned it. (read-only)

    property
  •   remoteDestroyOnNesting

    If true, will remotely destroy this object if sent nested.

    property

Common controller requests

  • + remoteAll:

    Returns an array of all remote objects (as instances of receiver’s class.) Each instance’s properties will be set to those returned by Rails.

  • + remoteAllViaObject:error:

    Returns an array of all remote objects (as instances of receiver’s class), constructed with a parent prefix. Each instance’s properties will be set to those returned by Rails.

  • + remoteAllAsync:

    Retrieves an array of all remote objects (as instances of receiver’s class.) Each instance’s properties will be set to those returned by Rails.

  • + remoteAllViaObject:async:

    Retrieves an array of all remote objects (as instances of receiver’s class.) Each instance’s properties will be set to those returned by Rails.

  • + remoteObjectWithID:error:

    Returns an instance of receiver’s class corresponding to the remote object with that ID.

  • + remoteObjectWithID:async:

    Retrieves an instance receiver’s class corresponding to the remote object with that ID.

CRUD

Setting and retrieving JSON representations

Initializers

Methods to override

Methods to override (Ruby-specific)

Properties

remoteAttributes

The most recent dictionary of all properties returned by Rails, exactly as it returned it. (read-only)

@property (nonatomic, strong, readonly) NSDictionary *remoteAttributes

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.

Declared In

NSRRemoteObject.h

remoteDestroyOnNesting

If true, will remotely destroy this object if sent nested.

@property (nonatomic) BOOL remoteDestroyOnNesting

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.

Declared In

NSRRemoteObject.h

remoteID

The corresponding local property for remote attribute id.

@property (nonatomic, strong) NSNumber *remoteID

Discussion

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

Declared In

NSRRemoteObject.h

Class Methods

config

Should return a configuration for this class and its members.

+ (NSRConfig *)config

Return Value

A configuration for this class and its members.

Discussion

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

Declared In

NSRRemoteObject.h

objectWithRemoteDictionary:

Initializes a new instance of the receiver’s class with a given dictionary input.

+ (instancetype)objectWithRemoteDictionary:(NSDictionary *)remoteDictionary

Parameters

remoteDictionary

Remote dictionary to be evaluated. (e.g., keys are “id”, not “remoteID”; “my_property”, not “myProperty”).

Note that this dictionary needs to be JSON-parasable, meaning all keys are strings and all objects are instances of NSString, NSNumber, NSArray, NSDictionary, or NSNull.

Return Value

A new instance of the receiver’s class with properties set using dictionary.

Declared In

NSRRemoteObject.h

objectsWithRemoteDictionaries:

Returns an array of new or existing instances of the receiver’s class, based off input of any number of remote dictionaries (JSON array from the server).

+ (NSArray *)objectsWithRemoteDictionaries:(NSArray *)remoteDictionaries

Parameters

remoteDictionaries

Array of remote dictionaries to be evaluated.

Note that the dictionaries in this array need to be JSON-parasable, meaning all keys are strings and all objects are instances of NSString, NSNumber, NSArray, NSDictionary, or NSNull.

Return Value

An array of new or existing instances of the receiver’s class, with their properties set using the dictionaries in remoteDictionaries.

Declared In

NSRRemoteObject.h

remoteAll:

Returns an array of all remote objects (as instances of receiver’s class.) Each instance’s properties will be set to those returned by Rails.

+ (NSArray *)remoteAll:(NSError **)error

Parameters

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

NSArray of instances of receiver’s class. Each object’s properties will be set to those returned by Rails.

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.

Declared In

NSRRemoteObject.h

remoteAllAsync:

Retrieves an array of all remote objects (as instances of receiver’s class.) Each instance’s properties will be set to those returned by Rails.

+ (void)remoteAllAsync:(NSRFetchAllCompletionBlock)completionBlock

Parameters

completionBlock

Block to be executed when the request is complete.

Discussion

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

Declared In

NSRRemoteObject.h

remoteAllViaObject:async:

Retrieves an array of all remote objects (as instances of receiver’s class.) Each instance’s properties will be set to those returned by Rails.

+ (void)remoteAllViaObject:(NSRRemoteObject *)parentObject async:(NSRFetchAllCompletionBlock)completionBlock

Parameters

parentObject

Remote object by which to request the collection from - establishes pattern for resources depending on nesting. Raises an exception if this object’s remoteID is nil, as it is used to construct the route.

completionBlock

Block to be executed when the request is complete.

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.)

Declared In

NSRRemoteObject.h

remoteAllViaObject:error:

Returns an array of all remote objects (as instances of receiver’s class), constructed with a parent prefix. Each instance’s properties will be set to those returned by Rails.

+ (NSArray *)remoteAllViaObject:(NSRRemoteObject *)parentObject error:(NSError **)error

Parameters

parentObject

Remote object by which to request the collection from - establishes pattern for resources depending on nesting. Raises an exception if this object’s remoteID is nil, as it is used to construct the route.

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

NSArray of instances of receiver’s class. Each object’s properties will be set to those returned by Rails.

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.

Declared In

NSRRemoteObject.h

remoteControllerName

The name of this class’s controller on the server - where actions for this class should be routed.

+ (NSString *)remoteControllerName

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.

Declared In

NSRRemoteObject.h

remoteModelName

The equivalent name of this class on your server.

+ (NSString *)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.

Warning: When overriding this method, NSRails will no longer autoinflect for determining this class name! What you enter will be used exactly, so make sure it’s lowercase, etc.

Declared In

NSRRemoteObject.h

remoteObjectWithID:async:

Retrieves an instance receiver’s class corresponding to the remote object with that ID.

+ (void)remoteObjectWithID:(NSNumber *)objectID async:(NSRFetchObjectCompletionBlock)completionBlock

Parameters

objectID

The ID of the remote object.

completionBlock

Block to be executed when the request is complete.

Discussion

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

Declared In

NSRRemoteObject.h

remoteObjectWithID:error:

Returns an instance of receiver’s class corresponding to the remote object with that ID.

+ (instancetype)remoteObjectWithID:(NSNumber *)objectID error:(NSError **)error

Parameters

objectID

The ID of the remote object.

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

Instance of receiver’s class with properties from the remote object with that ID.

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.

Declared In

NSRRemoteObject.h

Instance Methods

decodeRemoteValue:forRemoteKey:

Should set what you want an Objective-C property to be set to, based off a remote representation.

- (void)decodeRemoteValue:(id)remoteObject forRemoteKey:(NSString *)remoteKey

Parameters

remoteObject

Remote representation of this key. Will be a JSON-parsed object (NSDictionary, NSArray, NSString, NSNumber, or nil).

remoteKey

The remote key returned from Rails. Use propertyForRemoteKey: if you want the Objective-C property version of this key.

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:.

Warning: Make sure you make a call to super if a certain property shouldn’t be custom-coded.

Declared In

NSRRemoteObject.h

encodeValueForProperty:remoteKey:

Should return the remote representation for each property, optionally modifying the remote key.

- (id)encodeValueForProperty:(NSString *)property remoteKey:(NSString **)remoteKey

Parameters

property

Name of the property.

remoteKey

Reference to an NSString that contains the key that should be put into the JSON going out. Will contain the key that would be sent by default (ie, underscored, if enabled).

Return Value

Remote representation for this property. Return value must be JSON-parsable (NSDictionary, NSArray, NSString, NSNumber, or (NSNull or nil)).

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.

Warning: Make sure you make a call to super if a certain property shouldn’t be custom-coded.

Declared In

NSRRemoteObject.h

nestedClassForProperty:

Should return the class for the nested object stored in the property, or nil if it is not a nested object.

- (Class)nestedClassForProperty:(NSString *)property

Parameters

property

Name of the property.

Return Value

The class for the nested object stored in the property, or nil if it is not a nested object.

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

Warning: In Objective-C, make sure you make a call to super.

Declared In

NSRRemoteObject.h

objectUsedToPrefixRequest:

Should be overridden if instances of your subclass class should have their resource path be based off an association.

- (NSRRemoteObject *)objectUsedToPrefixRequest:(NSRRequest *)request

Parameters

request

The request whose path is currently being evalutated. Its route will be the route before adding the prefix (ie, the route used if the behavior is not desired).

Return Value

An object (typically an instance variable) that represents a parent to this class, or nil if this behavior is not desired.

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;
 }

Declared In

NSRRemoteObject.h

propertyForRemoteKey:

Should return the equivalent Objective-C property for a given remote key.

- (NSString *)propertyForRemoteKey:(NSString *)remoteKey

Parameters

remoteKey

The key sent in the remote dictionary.

Return Value

The Objective-C property equivalent for a remote key. If your class doesn’t define a property for this remote key, this should 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.

Declared In

NSRRemoteObject.h

propertyIsDate:

Should return whether or not this property should be encoded/decoded to/from a Date object.

- (BOOL)propertyIsDate:(NSString *)property

Parameters

property

Name of the property.

Return Value

Whether or not this property should be encoded/decoded to/from a Date object.

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.

Warning: Make a call to super.

Declared In

NSRRemoteObject.h

remoteCreate:

Creates the receiver remotely. Receiver’s properties will be set to those given by Rails (including remoteID).

- (BOOL)remoteCreate:(NSError **)error

Parameters

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

YES if create was successful. Returns NO if an error occurred.

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.

Declared In

NSRRemoteObject.h

remoteCreateAsync:

Creates the receiver remotely. Receiver’s properties will be set to those given by Rails (including remoteID).

- (void)remoteCreateAsync:(NSRBasicCompletionBlock)completionBlock

Parameters

completionBlock

Block to be executed when the request is complete.

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.

Declared In

NSRRemoteObject.h

remoteDestroy:

Destroys receiver’s corresponding remote object. Local object will be unaffected.

- (BOOL)remoteDestroy:(NSError **)error

Parameters

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

YES if destroy was successful. Returns NO if an error occurred.

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.

Declared In

NSRRemoteObject.h

remoteDestroyAsync:

Destroys receiver’s corresponding remote object. Local object will be unaffected.

- (void)remoteDestroyAsync:(NSRBasicCompletionBlock)completionBlock

Parameters

completionBlock

Block to be executed when the request is complete.

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).

Declared In

NSRRemoteObject.h

remoteDictionaryRepresentationWrapped:

Serializes the receiver’s properties into a dictionary.

Uses the coding methods.

- (NSDictionary *)remoteDictionaryRepresentationWrapped:(BOOL)wrapped

Parameters

wrapped

If YES, wraps the dictionary with a key of the model name:

{"user"=>{"name"=>"x", "email"=>"y"}}

Return Value

The receiver’s properties as a dictionary.

Declared In

NSRRemoteObject.h

remoteFetch:

Retrieves the latest remote data for receiver and sets its properties to received response.

- (BOOL)remoteFetch:(NSError **)error

Parameters

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

YES if fetch was successful. Returns NO if an error occurred.

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.

Declared In

NSRRemoteObject.h

remoteFetchAsync:

Retrieves the latest remote data for receiver and sets its properties to received response.

- (void)remoteFetchAsync:(NSRBasicCompletionBlock)completionBlock

Parameters

completionBlock

Block to be executed when the request is complete.

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`.

Declared In

NSRRemoteObject.h

remoteProperties

Should return an array of all properties to be used by NSRails.

- (NSMutableArray *)remoteProperties

Return Value

An array of all properties to be used by NSRails.

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

Declared In

NSRRemoteObject.h

remoteReplace:

“Places” receiver’s corresponding remote object.

- (BOOL)remoteReplace:(NSError **)error

Parameters

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

YES if place was successful. Returns NO if an error occurred.

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`.

Warning: No local properties will be set, as (by default) Rails does not return anything for this action. This means that if you update an object with the creation of new nested objects, those nested objects will not locally update with their respective IDs.

Declared In

NSRRemoteObject.h

remoteReplaceAsync:

“Places” receiver’s corresponding remote object.

- (void)remoteReplaceAsync:(NSRBasicCompletionBlock)completionBlock

Parameters

completionBlock

Block to be executed when the request is complete.

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`.

Warning: No local properties will be set, as (by default) Rails does not return anything for this action. This means that if you update an object with the creation of new nested objects, those nested objects will not locally update with their respective IDs.

Declared In

NSRRemoteObject.h

remoteUpdate:

Updates receiver’s corresponding remote object.

- (BOOL)remoteUpdate:(NSError **)error

Parameters

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

YES if update was successful. Returns NO if an error occurred.

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`.

Warning: No local properties will be set, as (by default) Rails does not return anything for this action. This means that if you update an object with the creation of new nested objects, those nested objects will not locally update with their respective IDs.

Declared In

NSRRemoteObject.h

remoteUpdateAsync:

Updates receiver’s corresponding remote object.

- (void)remoteUpdateAsync:(NSRBasicCompletionBlock)completionBlock

Parameters

completionBlock

Block to be executed when the request is complete.

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`.

Warning: No local properties will be set, as (by default) Rails does not return anything for this action. This means that if you update an object with the creation of new nested objects, those nested objects will not locally update with their respective IDs.

Declared In

NSRRemoteObject.h

setPropertiesUsingRemoteDictionary:

Sets the receiver’s properties given a dictionary.

- (void)setPropertiesUsingRemoteDictionary:(NSDictionary *)dictionary

Parameters

dictionary

Dictionary to be evaluated.

Discussion

Uses the coding methods.

Will set remoteAttributes to dictionary.

Declared In

NSRRemoteObject.h

shouldOnlySendIDKeyForNestedObjectProperty:

Should return whether or not a nested object should be sent with its entire body (x_attributes), or just ID (x_id).

- (BOOL)shouldOnlySendIDKeyForNestedObjectProperty:(NSString *)property

Parameters

property

Name of the property.

Return Value

YES if only the x_id key should be sent for this nested property, NO if the full x_attributes should be sent.

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"];
 }

Declared In

NSRRemoteObject.h

shouldReplaceCollectionForProperty:

Whether or not to fully replace a collection for a given property, as opposed to simply adding to it.

- (BOOL)shouldReplaceCollectionForProperty:(NSString *)property

Parameters

property

The name of the collection property.

Return Value

Whether or not to fully replace a collection for a given property, as opposed to simply adding to it.

Discussion

Will only be called for collection properties.

Declared In

NSRRemoteObject.h

shouldSendProperty:whenNested:

Should return whether or not a certain property should be sent in the outgoing dictionary.

- (BOOL)shouldSendProperty:(NSString *)property whenNested:(BOOL)nested

Parameters

property

The name of the property.

nested

Whether or not the receiving object is being nested.

Return Value

YES if the property should be included in the dictionary, NO if it shouldn’t.

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.

Warning: Make sure you make a call to super if a certain property shouldn’t be manually managed.

Declared In

NSRRemoteObject.h