Merge pull request #3 from hyperoslo/update/readme

Update README and add logo
hyperoslo · Nov 11, 2015 · 036be10 · 036be10
2 parents 6d95d5c + adfc7cc
commit 036be10
Show file tree

Hide file tree

Showing 6 changed files with 112 additions and 6 deletions.
diff --git a/Example/CompassExample/CompassExample.xcodeproj/project.pbxproj b/Example/CompassExample/CompassExample.xcodeproj/project.pbxproj
@@ -7,7 +7,7 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
-		770C3CD094BF3A3377FCD018 /* Pods.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 444C742BF0B07D34601BB603 /* Pods.framework */; settings = {ATTRIBUTES = (Weak, ); }; };
+		770C3CD094BF3A3377FCD018 /* Pods.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 444C742BF0B07D34601BB603 /* Pods.framework */; };
 		BD6929321BC51DC40063E97E /* LoginController.swift in Sources */ = {isa = PBXBuildFile; fileRef = BD6929311BC51DC40063E97E /* LoginController.swift */; settings = {ASSET_TAGS = (); }; };
 		BD93421A1BC4FFCA00F25395 /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = BD9342191BC4FFCA00F25395 /* AppDelegate.swift */; };
 		BD93421C1BC4FFCA00F25395 /* ViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = BD93421B1BC4FFCA00F25395 /* ViewController.swift */; };

diff --git a/Example/CompassExample/CompassExample/Info.plist b/Example/CompassExample/CompassExample/Info.plist
@@ -24,7 +24,7 @@
 			<key>CFBundleTypeRole</key>
 			<string>Editor</string>
 			<key>CFBundleURLName</key>
-			<string>no.hyper.CompassExample</string>
+			<string>no.hyper.Compass</string>
 			<key>CFBundleURLSchemes</key>
 			<array>
 				<string>compass</string>

diff --git a/Example/CompassExample/Podfile.lock b/Example/CompassExample/Podfile.lock
@@ -11,4 +11,4 @@ EXTERNAL SOURCES:
 SPEC CHECKSUMS:
   Compass: e01188a61ec071d122ca607202a21eb9b52ea0b9
 
-COCOAPODS: 0.39.0.beta.4
+COCOAPODS: 0.39.0
diff --git a/Images/logo_v1.png b/Images/logo_v1.png
diff --git a/Images/setup-url-scheme.png b/Images/setup-url-scheme.png
diff --git a/README.md b/README.md
@@ -1,14 +1,120 @@
-# Compass
+![Compass logo](https://raw.githubusercontent.com/hyperoslo/Compass/update/readme/Images/logo_v1.png)
 
 [![CI Status](http://img.shields.io/travis/hyperoslo/Compass.svg?style=flat)](https://travis-ci.org/hyperoslo/Compass)
 [![Version](https://img.shields.io/cocoapods/v/Compass.svg?style=flat)](http://cocoadocs.org/docsets/Compass)
 [![License](https://img.shields.io/cocoapods/l/Compass.svg?style=flat)](http://cocoadocs.org/docsets/Compass)
 [![Platform](https://img.shields.io/cocoapods/p/Compass.svg?style=flat)](http://cocoadocs.org/docsets/Compass)
 
-## Usage
+Compass helps you setup a central navigation system for your application.
+This has many benefits, one of them being that controllers can now be
+decoupled, meaning that the list that presents the detail no longer knows 
+about what its presenting. Controllers become agnostic and views stay 
+stupid. The user experience stays the same but the logic and separation of
+concerns become clearer. The outcome is that your application will become 
+more modular by default. Anything could potentially be presented from 
+anywhere, but remember, with great power comes great responsibility.
 
+## Setup
+
+#### Step 1
+First you need to register a URL scheme for your application
+<img src="https://raw.githubusercontent.com/hyperoslo/Compass/update/readme/Images/setup-url-scheme.png"> 
+
+#### Step 2
+Now you need to configure Compass to use that URL scheme, a good place
+to do this is in your `AppDelegate`
+```swift
+func application(application: UIApplication, 
+  didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
+    Compass.scheme = "compass"
+    return true
+}
+```
+#### Step 3
+Configure your application routes
+```swift
+func application(application: UIApplication, 
+  didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
+    Compass.scheme = "compass"
+    Compass.routes = ["profile:{username}", "login:{username}", "logout"]
+    return true
+}
+```
+#### Step 4
+Setup your application to response to the URLs, this can be done in the `AppDelegate` but its up to you to find a more suitable place for it depending on the size of your implementation.
+```swift
+func application(app: UIApplication, 
+  openURL url: NSURL, 
+  options: [String : AnyObject]) -> Bool {
+    return Compass.parse(url) { route, arguments in
+      switch route {
+        case "profile:{username}":
+          let profileController = profileController(title: arguments["{username}"])
+          self.navigationController?.pushViewController(profileController, 
+            animated: true)
+        case "login:{username}":
+          let loginController = LoginController(title: arguments["{username}"])
+          self.navigationController?.pushViewController(loginController, 
+            animated: true)
+        case "logout":
+          logout()
+        default: break
+      }
+    }
+}
+```
+
+Setting it up this way would mean that
+you could open any view from a push notification depending on the contents of the payload.
+Preferably you would add your own global function that you use for internal navigation.
+
+## Compass life hacks
+
+##### Tip 1. NavigationHandler.swift
+You could have multiple handlers depending on if a user is logged in or not.
 ```swift
-<API>
+import UIKit
+import Compass
+
+struct NavigationHandler {
+  static func routePreLogin(route: String, arguments: [String: String], 
+    navigationController: UINavigationController) {
+      switch route {
+        case "forgotpassword:{username}":
+          let forgotPasswordController = ForgotPasswordController(title: arguments["{username}"])
+          navigationController?.pushViewController(loginController, 
+            animated: true)
+        default: break
+      }
+  }
+
+  static func routePostLogin(route: String, arguments: [String: String], 
+    navigationController: UINavigationController) {
+      switch route {
+      case "profile:{username}":
+        let profileController = ProfileController(title: arguments["{username}"])
+        navigationController?.pushViewController(profileController, 
+          animated: true)
+      case "logout":
+        AppDelegate.logout()
+      default: break
+    }
+   }
+}
+```
+
+##### Tip 2. Compass.swift
+Add your own global function to easily navigate internally
+``` swift
+import Compass
+
+public func navigate(urn: String) {
+  let stringURL = "\(Compass.scheme)\(urn)"
+  guard let appDelegate = UIApplication.sharedApplication().delegate as? ApplicationDelegate,
+    url = NSURL(string: stringURL) else { return }
+
+  appDelegate.handleURL(url)
+}
 ```
 
 ## Installation