README.md

IKRouter

What does it do?

Once you have made your UIViewControllers conform to Routable you can register them with the parameters that they represent in your registered url-scheme routes. IKRouter is then able to create an array of UIViewControllers for you to display when a valid url is handled. All you need to do then is display them!

IKRouter can also handle routes in the traditional way by simply registering a route and handling it with a funciton/closure and the two methods can also be used together.

An example route is:

myapp://project/:projectId/item/:itemId

Note that routes must include the scheme (myapp://), url parameters need to be prefixed with a colon (:) and query strings dont need to be included when registering a route as they are included when the route is matched.

Using Routables

To use the Routables to automatically create your UI stack

1. Make any UIViewController that can be linked to a route parameter conform to Routable.
2. Register these with your IKRouter instance.
3. Register the routes that use those parameters.
4. Handle the chain of UIViewControllers via the routableHandler closure/function.

The Routable protocol

The Routable protocol consists of a single simple method which when give a MatchedRoute returns an instance of the Routable.

protocol Routable {
    static func instanceForRoute(route: MatchedRoute) -> Routable?
}

MatchedRoute instances provide all the details needed to pass information through to Routables like matched parameters and their values as well as query string.

Routable Example

Once your UIViewControllers are Routable simply do the following:

let navController = UINavigationController()
let router = IKRouter()
router
    .registerRoutableWithParameter(ProjectViewController.self, parameter: ":projectId")
    .registerRoutableWithParameter(ItemViewController.self, parameter: ":itemId")
    .registerRouteHandler("myapp://project/:projectId/item/:itemId")
    .registerRouteHandler("myapp://project/:projectId")
    .routableHandler = { match, viewControllers in
        navController.setViewControllers(viewControllers, animated: true)
    }

Things to note about using Routable

• As many routes can be registered as you want in any combination as long as each one is:
  • Unique
  • Has a Routable registered for all parameters
• If a route comes through and there is a parameter without a Routable the default handler will be used (if provided)
• When registering a route there is a handler parameter. This can be omitted when using Routables.

Non Routable Example

If you have routes which might not suit the automatic functionality provided by Routables you can also register individual routes with their own handlers

let router = IKRouter()
router
    .registerRouteHandler("myapp://project/:projectId/item/:itemId") { match in
        //create view controllers and show here...
        return true
    }
    .registerRouteHandler("myapp://project/:projectId/users/:userId") { match in
        //create view controllers and show here...
        return true /* return false if we didn't handle the route */
    }

NOTE: The handler for each route is used here (unlike above)

UIViewController Presentation

Every app has a slightly different UI hierarchy/architecture... for this reason IKRouter does not provide and automatic handling of UIViewController presentation but instead allows you to handle that yourself. Instead I have provided a UINavigationController extension that you can use to display the stack in different ways.

Currently there is just a simple method that will take a stack of UIViewControllers; push all but the last and present the last item in the stack like so:

router.routableHandler = { match, viewControllers in
    navController.setViewControllersPresentingLast(viewControllers, animatedSet: true, animatedPresent: true)
}

If there are other means of displaying a stack you think would be useful here feel free to add an issue or pull request, both are welcome!

Installation

Install via cocoapods by adding the following to your Podfile

pod "IKRouter", "~>1.0"

or manually by adding the source files from the IKRouter subfolder to your project.

The rest...

There is an included app so you can see it in action.