Fork me on GitHub

Alex Rupérez

Link: http://j.mp/2EtOlnh
Published: 04 Mar 11:35
I starred hubrioAU/XRouter at GitHub.
A simple routing library for iOS projects.
View on GitHub


View README


XRouter

Navigate anywhere in your iOS app in one line.

Codacy Badge CodeCov Badge Build Status Docs Badge Version License Platform

XRouter

Basic Usage

Configure

Define Routes

/**
 Routes
 */
enum Route: RouteType {

    /// Newsfeed page
    case newsfeed
    
    /// Login flow
    case login
    
    /// Signup flow
    case signup 
    
    /// User profile
    case profile(userID: String)
    
}

Create Router

/**
 Router
 */
class Router: XRouter<Route> {

    /// Prepares route destinations.
    override func prepareForTransition(to route: Route) throws -> UIViewController {
        switch route {
        case .newsfeed: return newsfeedController.rootViewController
        case .login: return LoginFlowCoordinator().start()
        case .signup: return SignupFlowCoordinator().start()
        case .profile(let userID): return UserProfileViewController(withID: userID)
        }
    }

}

Use Router

// Navigate directly to a route
router.navigate(to: .newsfeed)

// Open a URL
router.openURL(url)

Advanced Usage

RxSwift

XRouter also supports the RxSwift framework out of the box. Bindings exist for navigate(to:), which returns a Completable, and openURL(_:), which returns a Single<Bool>.

router.rx.navigate(to: .loginFlow) // -> Completable
router.rx.openURL(url) // -> Single<Bool>

Transitions

XRouter supports manually defining transitions.

class Router: XRouter<Route> {

    /// Set the transition for routes.
    override func transition(for route: Route) -> RouteTransition {
        switch route {
        case .newsfeed: return .set     /* Uses UINavigationController(_:).setViewControllers(...) */
        case .profile: return .modal    /* Uses UIViewController(_:).present(...) */
        case default: return .inferred  /* Default. Use appropriate transition based on context. */
        }
    }
    
}

See Custom Transitions for details about how you can easily create and use custom transitions.

URL Support

XRouter provides support for deep links and universal links.

You only need to do one thing to add URL support for your routes. Implement the static method registerURLs:

enum Route: RouteType {

    /// Register URL host and path groups to map to routes.
    static func registerURLs() -> URLMatcherGroup<Route>? {
        return .group("store.example.com") {
            $0.map("products") { .allProducts }
            $0.map("user/*/logout") { .logout }

            $0.map("products/{category}/view") {
              try .products(category: $0.param("category"))
            }

            $0.map("user/{id}/profile") {
              try .viewProfile(withID: $0.param("id"))
            }
        }
    }

}

Then you can call the openURL(_:animated:completion:) and/or continue(_ userActivity:) methods, e.g. from in your AppDelegate:

extension AppDelegate {

    /// Handle deep links.
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
        return router.openURL(url, animated: false)
    }

    /// Handle universal links.
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        return router.continue(userActivity)
    }

}

Handling errors

If you handle all navigation errors in the same way, you can override the received(unhandledError:) method.

class Router: XRouter<Route> {

    override func received(unhandledError error: Error) {
        log.error("Oh no! An error occured: \(error)")
    }

}

Or you can set a custom completion handler for some individual navigation action:

router.navigate(to: .profilePage(withID: 24)) { (optionalError) in
    if let error = optionalError {
        print("Oh no, we couldn't go here because there was an error!")
    }
}

Custom Transitions

Here is an example using the popular Hero Transitions library.

Define your custom transitions:

  /// Hero cross fade transition
  let heroCrossFade = RouteTransition { (source, dest, animated, completion) in
      source.hero.isEnabled = true
      dest.hero.isEnabled = true
      dest.hero.modalAnimationType = .fade

      // Present the hero animation
      source.present(dest, animated: animated) {
          completion(nil)
      }
  }

And set the transition to your custom transition in your Router:

    override func transition(for route: Route) -> RouteTransition {
        if case Route.profile = route {
          return heroCrossFade
        }

        return .inferred
    }

Documentation

Complete documentation is available here.

Example

To run the example project, clone the repo, and run it in Xcode 10.

Requirements

Installation

CocoaPods

XRouter is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'XRouter'

Author

Reece Como, reece@hubr.io

License

XRouter is available under the MIT license. See the LICENSE file for more info.