Inherits from NSObject
Conforms to NSCoding
Declared in NSRConfig.h

Overview

The NSRails configuration class is NSRConfig, a class that stores your Rails app’s configuration settings (server URL, etc) for either your app globally or in specific instances. It also supports basic HTTP authentication and very simple OAuth authentication.

Universal Config

This should meet the needs of the vast majority of Rails apps. Somewhere in your app setup, set your server URL (and optionally a username and password) using the defaultConfig singleton:

//AppDelegate.m

#import "NSRConfig.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
 [[NSRConfig defaultConfig] setRootURL:[NSURL URLWithString:@"http://myapp.com"]];

 //Similarly, if using HTTP Authentication, you can set your app's username and password like this:
 //[[NSRConfig defaultConfig] setAppUsername:@"username"];
 //[[NSRConfig defaultConfig] setAppPassword:@"password"];
}

Using several configs in one project

  • When NSRails needs to retrieve configuration settings, it calls the NSRRemoteObject config method. The default behavior is to return contextuallyRelevantConfig, but this can be overridden by your NSRRemoteObject subclass. Simply initialize your own NSRConfig instance and return it, and base URLs, autoinflection, date formats, and any other NSRConfig configurations will be used for NSRails actions called on this class or its instances.

  • If specific actions must be called using a separate config, an NSRConfig instance can be used to define a context block in which to call those config-specific methods:

      NSRConfig *myConfig = [[NSRConfig alloc] init]
  myConfig.rootURL = [NSURL URLWithString:@"http://secondrailsapp.com/"];

  [myConfig use];
  NSArray *peopleFromOtherServer = [Person getAllRemote];
  [myConfig end];

    Or, using block notation:

      NSArray *peopleToTransfer = [Person getAllRemote];
  NSRConfig *myConfig = [[NSRConfig alloc] init]
  myConfig.rootURL = [NSURL URLWithString:@"http://secondrailsapp.com/"];
  [myConfig useIn:^
      {
          for (Person *p in peopleToTransfer)
          {
              [p remoteCreate];
          }
      }
  ];

    In these examples, everything within the blocks will be called using the config context specified, regardless of defaultConfig. The config for the current context can be retrieved using the contextuallyRelevantConfig class method.

    You can nest several config contexts within each other.

Tasks

Properties

Routing

  •   autoinflectsClassNames

    When true, all Objective-C class names will have a default equivalence to their under_scored versions.

         property
  •   autoinflectsPropertyNames

    When true, all Objective-C property names will have a default equivalence to their under_scored versions.

         property
  •   ignoresClassPrefixes

    When converting class names to their Rails equivalents, prefixes will be omitted.

         property
  •   networkLogging

    If YES, NSRails will log HTTP verbs with their outgoing URLs, as well as any any JSON going out/coming in and server errors. If NO, NSRails will log nothing.

         property

Authentication

Server-side settings

  •   updateMethod

    HTTP method used for updating objects.

         property
  •   dateFormat

    Date format used if a property of type NSDate is encountered, to encode and decode NSDate objects.

         property

CoreData

Configuring to a Rails version

Retrieving global configs

Using configs in specific locations

  • – use

    Begins a context block of code to use the receiver as the default config.
  • – end

    Ends a context block of code to use the receiver as the default config.
  • – useIn:

    Executes a given block with the receiver as the default config in that block.
  • – useAsDefault

    Specifies for all NSRails actions to use the receiver.

Date conversions

Properties

additionalHTTPHeaders

A dictionary of additional HTTP headers to send with each request that uses this configuration.

@property (nonatomic, strong) NSDictionary *additionalHTTPHeaders

Declared In

NSRConfig.h

autoinflectsClassNames

When true, all Objective-C class names will have a default equivalence to their under_scored versions.

@property (nonatomic) BOOL autoinflectsClassNames

Discussion

For instance, the class DataType in Objective-C will change to data_type when sending/receiving to/from Rails.

When false, names must be identical to their corresponding models in Rails.

If there are just a few cases where you don’t want this, you can override model names like this.

Default: YES.

Declared In

NSRConfig.h

autoinflectsPropertyNames

When true, all Objective-C property names will have a default equivalence to their under_scored versions.

@property (nonatomic) BOOL autoinflectsPropertyNames

Discussion

For instance, myProperty in Obj-C will change to my_property when sending/receiving to/from Rails. the_id = theID; the_ids = theIDs.

When false, names must be identical to their corresponding attributes in Rails.

If there are just a few cases where you don’t want this, see NSRRemoteObject’s overridable methods.

Default: YES.

Declared In

NSRConfig.h

basicAuthPassword

Password for basic HTTP authentication (if used by server.)

@property (nonatomic, strong) NSString *basicAuthPassword

Declared In

NSRConfig.h

basicAuthUsername

Username for basic HTTP authentication (if used by server.)

@property (nonatomic, strong) NSString *basicAuthUsername

Declared In

NSRConfig.h

dateFormat

Date format used if a property of type NSDate is encountered, to encode and decode NSDate objects.

@property (nonatomic, strong) NSString *dateFormat

Discussion

This should not be changed unless the format is also changed server-side; the default is the default Rails format.

Default: @"yyyy-MM-dd'T'HH:mm:ss.SSSZ" (Rails 4 default).

Note: if you’re not using Rails 4, you can configure your settings to the Rails 3 defaults using configureToRailsVersion:.

Declared In

NSRConfig.h

ignoresClassPrefixes

When converting class names to their Rails equivalents, prefixes will be omitted.

@property (nonatomic) BOOL ignoresClassPrefixes

Discussion

Example: NSRClass will simply become class, instead of nsr_class.

Default: YES.

Declared In

NSRConfig.h

managedObjectContext

Managed object context for CoreData support. (Required if CoreData is enabled)

@property (nonatomic, strong) NSManagedObjectContext *managedObjectContext

Discussion

This is the context into which NSRails will insert any new objects created by various internal methods, or search for any existing objects.

Should stay nil (default) if CoreData is not being used.

Declared In

NSRConfig.h

managesNetworkActivityIndicator

The network activity indicator (gray spinning wheel on the status bar) will automatically turn on and off with requests.

@property (nonatomic) BOOL managesNetworkActivityIndicator

Discussion

This is only supported for asynchronous requests, as otherwise the main thread is blocked.

Also only supported in iOS development.

Default: NO.

Declared In

NSRConfig.h

networkLogging

If YES, NSRails will log HTTP verbs with their outgoing URLs, as well as any any JSON going out/coming in and server errors. If NO, NSRails will log nothing.

@property (nonatomic) BOOL networkLogging

Discussion

Default: YES.

Declared In

NSRConfig.h

oAuthToken

Token for OAuth authentication (if used by server.)

@property (nonatomic, strong) NSString *oAuthToken

Declared In

NSRConfig.h

performsCompletionBlocksOnMainThread

When true, the completion blocks passed into asynchronous remote methods will be called on the main thread.

@property (nonatomic) BOOL performsCompletionBlocksOnMainThread

Discussion

This can be useful if you wish to update view elements from this block (where iOS would otherwise lock up).

Not sure when this couldn’t be useful, but leaving disabling it as an option. Maybe performance?

Default: YES.

Declared In

NSRConfig.h

rootURL

Root URL for your Rails server.

@property (nonatomic, strong) NSURL *rootURL

Declared In

NSRConfig.h

succinctErrorMessages

Cleaner error messages when generating NSError objects.

@property (nonatomic) BOOL succinctErrorMessages

Discussion

For example, simply Couldn't find Person with id=15, instead of this mess.

May not be effective with non-Rails servers.

Default: YES.

Declared In

NSRConfig.h

timeoutInterval

Timeout interval for HTTP requests.

@property (nonatomic) NSTimeInterval timeoutInterval

Discussion

The minimum timeout interval for POST requests is 240 seconds (set by Apple).

Default: 60.

Declared In

NSRConfig.h

updateMethod

HTTP method used for updating objects.

@property (nonatomic, strong) NSString *updateMethod

Discussion

Default: @"PATCH" (Rails 4 default).

Note: if you’re not using Rails 4, you can configure your settings to the Rails 3 defaults using configureToRailsVersion:.

Declared In

NSRConfig.h

Class Methods

contextuallyRelevantConfig

Returns the contextually relevant configuration.

+ (instancetype)contextuallyRelevantConfig

Return Value

The contextually relevant configuration, or default configuration is no explicit context is set.

Discussion

This is like defaultConfig, but will return any configuration currently being used in a use/end or useIn: block before going to the default.

Declared In

NSRConfig.h

defaultConfig

Returns the current default configuration.

+ (instancetype)defaultConfig

Return Value

The default configuration.

Declared In

NSRConfig.h

Instance Methods

configureToRailsVersion:

Sets dateFormat and updateMethod to the standards for the given Rails version.

- (void)configureToRailsVersion:(NSRRailsVersion)railsVersion

Parameters

railsVersion

The version of Rails to configure to (NSRRailsVersion3 or NSRRailsVersion4).

Discussion

Rails version Date format update method
Rails 3.x yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z' PUT
Rails 4.x yyyy-MM-dd'T'HH:mm:ss.SSSZ PATCH

Declared In

NSRConfig.h

dateFromString:

Returns a date representation of a given string interpreted using dateFormat.

- (NSDate *)dateFromString:(NSString *)string

Parameters

string

The string to parse.

Discussion

This method is used internally to convert a Rails-sent datetime string representation into an NSDate for an object property.

See Also

Declared In

NSRConfig.h

end

Ends a context block of code to use the receiver as the default config.

- (void)end

Discussion

Highest config precedence.

See Also

Declared In

NSRConfig.h

stringFromDate:

Returns a string representation of a given date formatted using dateFormat.

- (NSString *)stringFromDate:(NSDate *)date

Parameters

date

The date to format.

Discussion

This method is used internally to convert an NSDate property in an object to a Rails-readable string.

See Also

Declared In

NSRConfig.h

use

Begins a context block of code to use the receiver as the default config.

- (void)use

Discussion

Highest config precedence.

See Also

Declared In

NSRConfig.h

useAsDefault

Specifies for all NSRails actions to use the receiver.

- (void)useAsDefault

Discussion

defaultConfig will now return the receiver.

Declared In

NSRConfig.h

useIn:

Executes a given block with the receiver as the default config in that block.

- (void)useIn:(void ( ^ ) ( void ))block

Parameters

block

Block to be executed with the default config context of receiver.

See Also

Declared In

NSRConfig.h