Add powerful deep-linking, simplify navigation and ditch the expensive boilerplate.
Complete documentation is available here and is generated using Jazzy.
XRouter is available via Swift Package Manager version 2.0.1 onwards.
XRouter is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'XRouter'Create a file containing the routes for your application.
enum Route: RouteType {
case login
case profile(userID: Int)
}Configure a concrete instance of XRouter to resolve a standalone view controller, or start a modal flow by passing a navigation controller.
class Router: XRouter<Route> {
override func prepareDestination(for route: Route) throws -> UIViewController {
switch route {
case .login:
return AuthLoginFlowCoordinator().navigationController
case .profile(let userID):
return UserProfileViewController(profile: try repo.fetch(user: userID))
}
}
}router.navigate(to: .profile(userID: 3355))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 {
static func registerURLs() -> URLMatcherGroup<Route>? {
return .group {
$0.map("/products") { .allProducts }
$0.map("/user/*/logout") { .logout }
$0.map("/products/{cat}/view") { try .products(category: $0.path("cat")) }
$0.map("/user/{id}/profile") {
try .viewProfile(withID: $0.path("id"), parameters: $0.query)
}
}
}
}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)
}
}You can even define more advanced URL routing. For example, these rules could be used to match:
http://example.com/login-->.loginhttps://example.com/signup-->.signupcustomScheme://myApp/qr-code?code=abcdef...-->.openQRCode("abcdef...")https://www.example.com/products-->.allProductshttps://api.example.com/user/my-user-name/logout-->.logout
enum Route: RouteType {
static func registerURLs() -> URLMatcherGroup<Route>? {
return .init(matchers: [
.host("example.com") {
$0.map("/login") { .login }
$0.map("/signup") { .signup }
},
.scheme("customScheme") {
$0.map("/qr-code") { .openQRCode($0.query("code")) }
},
.group {
$0.map("/products") { .allProducts }
$0.map("/user/*/logout") { .logout }
}
])
}
}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!")
}
}Here is an example using the popular Hero Transitions library.
Define your custom transitions:
/// Perform a cross-fade transition using Hero library.
static let heroCrossFade = RouteTransition { (source, destination, animated, completion) in
source.hero.isEnabled = true
destination.hero.isEnabled = true
destination.hero.modalAnimationType = .fade
/* Present the hero animation */
source.present(destination, animated: animated) {
completion(nil)
}
}And set the transition to your custom transition in your Router:
override func transition(for route: Route) -> RouteTransition {
if case .profile = route {
return .heroCrossFade
}
return .automatic
}XRouter also supports Rx 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>To run the example project, clone the repo, and run it in the latest version of Xcode.
XRouter is available under the MIT license. See the LICENSE file for more info.