hubrioAU / Xrouter
Programming Languages
Projects that are alternatives of or similar to Xrouter
XRouter
Decouple your code with abstract routes, add powerful deep-linking and ditch the boilerplate.
Get Started
Define App Routes
Create an AppRoute+Config.swift
file with your abstract routes in it.
enum AppRoute: RouteType {
case newsfeed
case login
case signup
case profile(userID: Int)
}
Create a Router
Extend a concrete Router instance to resolve your view controllers.
class Router: XRouter<AppRoute> {
override func prepareDestination(for route: AppRoute) throws -> UIViewController {
switch route {
case .newsfeed: return
newsfeedController.rootViewController
case .login:
return LoginFlowCoordinator().start()
case .signup:
return SignupFlowCoordinator().start()
case let .profile(userID):
guard let profile = profilesRepository.fetch(userId) else {
throw NotFoundError("Could not find profile with that ID.")
}
return UserProfileViewController().configured(with: profile)
}
}
}
Use
// Navigate directly to a route
router.navigate(to: .profile(3355))
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>
Deep Link 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 AppRoute: 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
-->.login
-
https://example.com/signup
-->.signup
-
customScheme://myApp/qr-code?code=abcdef...
-->.openQRCode("abcdef...")
-
https://www.example.com/products
-->.allProducts
-
https://api.example.com/user/my-user-name/logout
-->.logout
enum AppRoute: RouteType {
static func registerURLs() -> URLMatcherGroup<AppRoute>? {
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 }
}
])
}
}
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: AppRoute) -> RouteTransition {
if case Route.profile = route {
return heroCrossFade
}
return .automatic
}
Documentation
Complete documentation is available here and is generated using Jazzy.
Example
To run the example project, clone the repo, and run it in Xcode 10.
Requirements
Installation
Swift Package Manager
XRouter is available through Swift Package Manager from version 2.0.1
onwards.
CocoaPods
XRouter is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'XRouter'
Author
Reece Como, [email protected]
License
XRouter is available under the MIT license. See the LICENSE file for more info.