NSRConfig Class Reference
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 returncontextuallyRelevantConfig
, 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 thecontextuallyRelevantConfig
class method.You can nest several config contexts within each other.
Tasks
Properties
-
rootURL
Root URL for your Rails server.
property -
performsCompletionBlocksOnMainThread
When true, the completion blocks passed into asynchronous
propertyremote
methods will be called on the main thread. -
managesNetworkActivityIndicator
The network activity indicator (gray spinning wheel on the status bar) will automatically turn on and off with requests.
property -
succinctErrorMessages
Cleaner error messages when generating
propertyNSError
objects. -
timeoutInterval
Timeout interval for HTTP requests.
property
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
propertyYES
, NSRails will log HTTP verbs with their outgoing URLs, as well as any any JSON going out/coming in and server errors. IfNO
, NSRails will log nothing.
Authentication
-
basicAuthUsername
Username for basic HTTP authentication (if used by server.)
property -
basicAuthPassword
Password for basic HTTP authentication (if used by server.)
property -
oAuthToken
Token for OAuth authentication (if used by server.)
property -
additionalHTTPHeaders
A dictionary of additional HTTP headers to send with each request that uses this configuration.
property
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
-
managedObjectContext
Managed object context for CoreData support. (Required if CoreData is enabled)
property
Configuring to a Rails version
-
– configureToRailsVersion:
Sets
dateFormat
andupdateMethod
to the standards for the given Rails version.
Retrieving global configs
-
+ defaultConfig
Returns the current default configuration.
-
+ contextuallyRelevantConfig
Returns the contextually relevant configuration.
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
-
– stringFromDate:
Returns a string representation of a given date formatted using dateFormat.
-
– dateFromString:
Returns a date representation of a given string interpreted using dateFormat.
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
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
orNSRRailsVersion4
).
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