Merging mapQuery and mapRoute

[darscan]

Firstly, thanks for the kick-ass library. I've written 2 similar (based on Sinatra) "router" libraries and wasn't happy with either implementation. Yours looks good.

I'm not sure how useful mapQuery is by itself.. or perhaps I misunderstand its use.. regardless, here's how I imagine query parameters to work for mapRoute:

router.mapRoute( '/hello/:name', CustomRouteEvent.HELLO );

router.eventDispatcher.addEventListener( CustomRouteEvent.HELLO, function( event : RouteEvent ) : void {
    event.route.value; // => '/hello/awesome?page=2'
    event.route.params( 'name' ); // => awesome
    event.route.params( 'page' ); // => 2
} );

router.route( '/hello/awesome?page=2' );

As with Sinatra, both path segments and query parameters can be found in the params hash.

Perhaps mapQuery has another use-case that I'm missing however.

Also.. I'm not sure I'm a fan of event.route.params being a method. I might prefer params to be an actual hash (basic object):

var params:Object = event.route.params;
params['name']; // => awesome
params.page; // => 2

Anyhoo, nice work. Look forward to trying it out.

[jeremyruppel]

Hey Shaun, thanks for the feedback.

You're right that for query string parameters that simply alter a route's behavior, like pagination, mapQuery doesn't serve much of a purpose. The method was written to handle query string parameters that would behave more as routes themselves, like:

router.mapQuery( { page : 'about' }, CustomRouteEvent.ABOUT );
router.mapQuery( { page : 'contact' }, CustomRouteEvent.CONTACT );

As opposed to:

router.mapRoute( '/', CustomRouteEvent.PAGE );

router.eventDispatcher.addEventListener( CustomRouteEvent.PAGE, function( event : RouteEvent ) : void
{
    switch( event.route.params( 'page' ) )
    {
        case 'about' : // do something for the about route...
        case 'contact' : // do something for the contact route...
    }
} );

The use case in mind behind this was for sites that weren't necessarily making use of any particular url-hashing scheme, but needed to provide different entry points via the url. Say, http://mysite.com/?page=about versus http://mysite.com/?page=contact.

On the other side of your first point, you're absolutely right that query string parameters following routes need to be made available in the route's parameters. Thanks for pointing that out, I don't have a good explanation for why I haven't written that in yet. I'll definitely be adding this functionality soon.

As far as the route's params being a method versus a straight hash, I definitely considered it at first. I can see benefits to both approaches. A hash is much more familiar to people coming from Sinatra, you can iterate over it, etc. But with a method I can and should (but currently do not) provide some helpful errors to identify missing keys as opposed to a straight NRE. (Would that really be any more helpful than an NRE? is the real question...) So, I guess what I'm saying is I'm totally on the fence about this one. If people want the hash, I'm cool with that. Are there any other arguments I'm missing to support changing it to a hash?

[fljot]

jeremyruppel,

I would say, give developer a choice. Params as object and getParam(name:String):String method.