diff --git a/DOXYGEN.md b/DOXYGEN.md new file mode 100644 index 0000000..27ad16f --- /dev/null +++ b/DOXYGEN.md @@ -0,0 +1,7 @@ +## Generating the API Documentation + + 1. Install doxygen. + 1. Find the installation location: `which doxygen`. Copy the result. + 1. Add the result as a User-Defined Setting in the LoopBackDocs target. + 1. Build the LoopBackDocs target (the device setting doesn't matter). + 1. Profit. diff --git a/README.md b/README.md index 27ad16f..f5396ee 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ -## Generating the API Documentation +## iOS - 1. Install doxygen. - 1. Find the installation location: `which doxygen`. Copy the result. - 1. Add the result as a User-Defined Setting in the LoopBackDocs target. - 1. Build the LoopBackDocs target (the device setting doesn't matter). - 1. Profit. +The LoopBack iOS SDK obviates the need for using the clunky `NSURLRequest` and +similar interfaces to interact with a LoopBack-based backend, albeit RESTful. +Instead, interact with your Models and Data Sources in a comfortable, +first-class, native manner. diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md new file mode 100644 index 0000000..6e374e3 --- /dev/null +++ b/docs/GettingStarted.md @@ -0,0 +1,123 @@ +## Getting Started + +Once you've got your LoopBack-powered backend running, it's time to integrate it +with your mobile application. + +### Requirements + + * Mac OSX with [Xcode](https://developer.apple.com/) 4.6 or higher + * LoopBack SDK, a part of the [StrongLoop + Suite](http://strongloop.com/strongloop-suite/) + * For on-device testing, an iOS device with iOS 5 or higher + * A LoopBack-powered server application (For example, the StrongLoop Suite + Example App. [More information here.](http://docs.strongloop.com)) + +### Guided: Get Started with the Guide Application + +The easiest way to get started with the LoopBack iOS SDK is with the LoopBack +iOS Guide Application. The Guide Application comes ready to compile with XCode, +and each Tab in the Application will guide you through the features available to +mobile applications through the SDK. + +tab Home +tab 1 +tab 2 +tab 3 + +From your usual projects directory: + + 1. Download the LoopBack Guide Application to your local machine from + [GitHub](https://github.com/strongloop/loopback-ios-getting-started). + + ```sh + git clone git@github.com:strongloop/loopback-ios-getting-started.git + ``` + + 1. Open the Xcode project downloaded as a part of the Guide Application's + Git repository. + + ```sh + cd loopback-ios-getting-started\loopback-ios-app + open loopback-ios-multi-model.xcodeproj + ``` + + 1. Run the Application from Xcode (Command+R by default) and follow the + instructions on each tab. Popup dialogs in the Application will ask you to + uncomment various code blocks in each ViewController illustrating how to use + the LoopBack SDK to interact with Models stored on the server. + +### DIY: Get Started with the LoopBack SDK + +If you are creating a new iOS application or want to integrate an existing +application with LoopBack you'll want to use the LoopBack SDK directly +(LoopBack.framework) independent of the Guide Application. + +Once you have the [StrongLoop Suite](http://strongloop.com/strongloop-suite/) +installed and are ready to develop LoopBack applications (see +[Requirements](#requirements) for more information on what you'll need): + + 1. Open the Xcode project you want to use with LoopBack, or [create a new one](https://developer.apple.com/library/ios/documentation/ToolsLanguages/Conceptual/Xcode_User_Guide/020-Start_a_Project/start_project.html). + 1. Open the SDKs folder of the distro: + + ```sh + open /usr/local/share/strongloop-node/strongloop/sdks/loopback-ios-sdk + ``` + + 1. Drag the entire LoopBack.framework folder from the new Finder window into + your Xcode project. + +Finder to Xcode + + - **Important:** Make sure the "Copy items to destination's group folder" + checkbox is checked. This places a copy of the SDK within your application's + project folder. + +Copy items + + 1. Verify LoopBack is included in the list of iOS Frameworks to link against + your binary. In your Project settings, check the 'Link with Binaries' section + under the 'Build Phases' tab. If it's missing, you can add it directly by + clicking the '+' button and selecting LoopBack.framework. + + - If LoopBack.framework isn't displayed in the list, try the previous step + again; Xcode didn't create the copy it was supposed to create. + +Link with Binaries + + 1. Import the LoopBack.h header into your application just as you would + `Foundation/Foundation.h`: + + ```objectivec + #import + ``` + +LoopBack.h + + 1. Somewhere, we're going to need an Adapter to tell the SDK where to find our + server: + + ```objectivec + LBRESTAdapter *adapter = [LBRESTAdapter adapterWithURL:[NSURL URLWithString:@"http://example.com"]]; + ``` + + - This `LBRESTAdapter` provides the starting point for all our interactions + with the running and anxiously waiting server. + + 1. Once we have access to `adapter` (for the sake of example, we'll assume the + Adapter is available through our AppDelegate), we can create basic `LBModel` + and `LBModelPrototype` objects. Assuming we've previously created [a model + named "product"](http://docs.strongloop.com/loopback#model): + + ```objectivec + LBRESTAdapter *adapter = [[UIApplication sharedApplication] delegate].adapter; + LBModelPrototype *Product = [adapter prototypeWithName:@"products"]; + LBModel *pen = [Product modelWithDictionary:@{ "name": "Awesome Pen" }]; + ``` + + - All the normal, magical `LBModel` and `LBModelPrototype` methods (e.g. + `create`, `destroy`, `findById`) are now available through `Product` and + `pen`! + + 1. Go forth and develop! Check out the [API docs](ios/api) or create more + Models with the LoopBack [CLI](http://docs.strongloop.com/loopback#model) or + [Node API](http://docs.strongloop.com/loopback#a-simple-example). diff --git a/docs/Subclassing.md b/docs/Subclassing.md index 8ba3ac0..aa3d9ae 100644 --- a/docs/Subclassing.md +++ b/docs/Subclassing.md @@ -4,8 +4,9 @@ - **Knowledge of Objective-C and iOS App Development** - **LoopBack iOS SDK** - You should know how to set this up already if you've - gone through the [sample app](#). If not, run through that guide first. It - doesn't take long, and it provides the basis for this guide. + gone through the [Getting Started](#getting-started). If not, run through + that guide first. It doesn't take long, and it provides the basis for this + guide. - **Schema** - Explaining the type of data to store and why is outside the scope of this guide, being tightly coupled to your application's needs. @@ -18,10 +19,11 @@ types. ### Step 1: Model Interface & Properties As with any Objective-C class, the first step is to build your interface. If we -leave any [custom behaviour](#) for later, then it's just a few `@property` -declarations and we're ready for the implementation. +leave any [custom behaviour](#http://docs.strongloop.com/strong-remoting) for +later, then it's just a few `@property` declarations and we're ready for the +implementation. -```objc +```objectivec /** * A widget for sale. */ @@ -38,10 +40,10 @@ declarations and we're ready for the implementation. ### Step 2: Model Implementation -Since we've left [custom behaviour](#) for later, then I'll just leave this -here. +Since we've left [custom behaviour](#http://docs.strongloop.com/strong-remoting) +for later, then I'll just leave this here. -```objc +```objectivec @implementation Widget @end ``` @@ -71,7 +73,7 @@ your own. Since `LBModelPrototype` provides a basic implementation, we only need to override its constructor to provide the appropriate name. -```objc +```objectivec @interface WidgetPrototype : LBModelPrototype + (instancetype)prototype; @@ -83,7 +85,7 @@ override its constructor to provide the appropriate name. Remember to use the right name: -```obj +```objectivec @implementation WidgetPrototype + (instancetype)prototype { @@ -95,10 +97,10 @@ Remember to use the right name: ### Step 5: A Little Glue -Just as we did in [the getting started guide](#), we'll need an `LBRESTAdapter` -instance to connect to our server: +Just as we did in [the getting started guide](#getting-started), we'll need an +`LBRESTAdapter` instance to connect to our server: -```objc +```objectivec LBRESTAdapter *adapter = [LBRESTAdapter adapterWithURL:[NSURL URLWithString:@"http://myserver:3000"]]; ``` @@ -107,7 +109,7 @@ server. Once we have that adapter, we can create our Prototype instance. -```objc +```objectivec WidgetPrototype *prototype = (WidgetPrototype *)[adapter prototypeWithClass:[WidgetPrototype class]]; ``` @@ -117,13 +119,13 @@ Now that we have a `WidgetPrototype` instance, we can: - Create a `Widget` -```objc +```objectivec Widget *pencil = (Widget *)[prototype modelWithDictionary:@{ @"name": @"Pencil", @"price": @1.50 }]; ``` - Save said `Widget` -```objc +```objectivec [pencil saveWithSuccess:^{ // Pencil now exists on the server! } @@ -134,7 +136,7 @@ Widget *pencil = (Widget *)[prototype modelWithDictionary:@{ @"name": @"Pencil", - Find another `Widget` -```objc +```objectivec [prototype findWithId:@2 success:^(LBModel *model) { Widget *pen = (Widget *)model; @@ -146,7 +148,7 @@ Widget *pencil = (Widget *)[prototype modelWithDictionary:@{ @"name": @"Pencil", - Remove a `Widget` -``` +```objectivec [pencil destroyWithSuccess:^{ // No more pencil. Long live Pen! }