Namespace RouteMap

RouteMap
Defined in: routemap.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	RouteMap RouteMap holds an internal table of route patterns and method names in addition to some adding/removing/utility methods and a handler for request routing.

Method Summary
Method Attributes	Method Name and Description
<static>	RouteMap.add(rule) adds a rule to the internal table of routes and methods
<private>	compile(route) builds the internal representation of a rule based on the route definition
<static>	RouteMap.context(scope) overrides the context where listener methods are sought, the default scope is `window` (in a browser setting), returns the current context, if no `scope` object is passed in, just returns current context without setting context
<static>	RouteMap.current() returns the parsed (see #parse) currently accessed route; after listeners have finished firing, `current` and `last` are the same
<static>	RouteMap.default_handler() this function is fired when no rule is matched by a URL, by default it does nothing, but it could be set up to handle things like `404` responses on the server-side or bad hash fragments in the browser
<static>	RouteMap.get() URL grabber function, defaults to checking the URL fragment (`hash`); this function should be overwritten in a server-side environment; this method is called by RouteMap.handler; without `window.location.hash` it will return `'/'`
<static>	RouteMap.go(hash) in a browser setting, it changes `window.location.hash`, in other settings, it should be overwritten to do something useful (if necessary); it will not throw an error if `window` does not exist
<static>	RouteMap.handler() main handler function for routing, this should be bound to `hashchange` events in the browser, or (in conjunction with updating RouteMap.get) used with the HTML5 `history` API, it detects all the matching route patterns, parses the URL parameters and fires their methods with the arguments from the parsed URL; the timing of RouteMap.current and RouteMap.last being set is as follows (pseudo-code): path: get_route // RouteMap.get parsed: parse path // #parse current: longest parsed // RouteMap.current parsed: pre_dispatch parsed // RouteMap.pre_dispatch current: longest parsed // reset current fire matched rules in parsed last: current // RouteMap.last `RouteMap.handler` calls #parse and does not catch any errors that function throws
<static>	RouteMap.hash(rule, params) returns a URL fragment by applying parameters to a rule; uses #compile and does not catch any errors thrown by that function
<static>	RouteMap.last() returns the parsed (see #parse) last accessed route; when route listeners are being called, `last` is the previously accessed route, after listeners have finished firing, the current parsed route replaces `last`'s value
<private>	merge() merges one or more objects into a new object by value (nothing is a reference), useful for cloning
<static>	RouteMap.parse() parses a URL fragment into a data structure only if there is a route whose pattern matches the fragment
<private>	parse(path) parses a path and returns a list of objects that contain argument dictionaries, methods, and raw hash values
<static>	RouteMap.post_add(compiled) this function is called by RouteMap.add, it receives a compiled rule object, e.g.
<static>	RouteMap.pre_dispatch(parsed) like RouteMap.post_add this function can be overwritten to add application-specific code into route mapping, it is called before a route begins being dispatched to all matching rules; it receives the list of matching parsed route objects (#parse) and is expected to return it; one application of this function might be to set application-wide variables like debug flags
<static>	RouteMap.prefix(prefix) if a string is passed in, it overwrites the prefix that is removed from each URL before parsing; primarily used for hashbang (`#!`); either way, it returns the current prefix
<static>	RouteMap.remove(rule) counterpart to RouteMap.add, removes a rule specification; * `remove` uses #compile and does not catch any errors thrown by that function

Namespace Detail

RouteMap

RouteMap holds an internal table of route patterns and method names in addition to some adding/removing/utility methods and a handler for request routing.

It does not have any dependencies and is written in "plain old" JS, but it does require JS 1.8 array methods, so if the environment it will run in does not have those, the reference implementations from Mozilla should be supplied external to this library.

It is designed to be used in both a browser setting and a server-side context (for example in node.js).

LICENSING INFORMATION:

Copyright 2011 OpenGamma Inc. and the OpenGamma group of companies
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Author: Afshin Darian.

Throws:
{Error}: if JS 1.8 Array.prototype methods don't exist

See:: OpenGamma; Apache License, Version 2.0; Mozilla Developer Network

Method Detail

<static> {undefined} RouteMap.add(rule)

adds a rule to the internal table of routes and methods

Parameters:

{Object} rule

rule specification

{String} rule.route

route pattern definition; there are three types of pattern arguments: scalars, keyvals, and stars; scalars are individual values in a URL (all URL values are separate by the '/' character), keyvals are named values, e.g. 'foo=bar', and star values are wildcards; so for example, the following pattern represents all the possible options:

'/foo/:id/:sub?/attr:/subattr:?/rest:*'

the ? means that argument is optional, the star rule is named rest but it could have just simply been left as *, which means the resultant dictionary would have put the wildcard remainder into args['*'] instead of args.rest; so the following URL would match the pattern above:

/foo/23/45/attr=something/subattr=something_else

when its method is called, it will receive this arguments dictionary:

{
     id:'23',
     subid:'45',
     attr:'something',
     subattr:'something_else',
     rest:''
}

add uses #compile and does not catch any errors thrown by that function

{String} rule.method

listener method for this route

Throws:
{TypeError}: if rule.route or rule.method are not strings or empty strings
{Error}: if rule has already been added

See:: RouteMap.post_add

<private> compile(route)

builds the internal representation of a rule based on the route definition

Parameters:
{String} route

Throws:
{SyntaxError}: if any portion of a rule definition follows a * directive
{SyntaxError}: if a required scalar follows an optional scalar
{SyntaxError}: if a rule cannot be parsed

Returns:

{Object} a compiled object, for example, the rule '/foo/:id/type:?/rest:*' would return an object of the form:

{
    page:'/foo',
    rules:{
        keyvals:[{name: 'type', required: false}],
        scalars:[{name: 'id', required: true}],
        star:'rest' // false if not defined
    }
}

See:: RouteMap.add; RouteMap.hash; RouteMap.remove

<static> RouteMap.context(scope)

overrides the context where listener methods are sought, the default scope is window (in a browser setting), returns the current context, if no scope object is passed in, just returns current context without setting context

Parameters:
{Object} scope: the scope within which methods for mapped routes will be looked for

Returns:: {Object} the current context within which RouteMap searches for handlers

<static> {Object} RouteMap.current()

returns the parsed (see #parse) currently accessed route; after listeners have finished firing, current and last are the same

Returns:: {Object} the current parsed URL object

See:: RouteMap.last

<static> {undefined} RouteMap.default_handler()

this function is fired when no rule is matched by a URL, by default it does nothing, but it could be set up to handle things like 404 responses on the server-side or bad hash fragments in the browser

<static> {String} RouteMap.get()

URL grabber function, defaults to checking the URL fragment (hash); this function should be overwritten in a server-side environment; this method is called by RouteMap.handler; without window.location.hash it will return '/'

Returns:: {String} by default, this returns a subset of the URL hash (everything after the first '/' character ... if nothing follows a slash, it returns '/'); if overwritten, it must be a function that returns URL path strings (beginning with '/') to match added rules

<static> {undefined} RouteMap.go(hash)

in a browser setting, it changes window.location.hash, in other settings, it should be overwritten to do something useful (if necessary); it will not throw an error if window does not exist

Parameters:
{String} hash: the hash fragment to go to

<static> {undefined} RouteMap.handler()

main handler function for routing, this should be bound to hashchange events in the browser, or (in conjunction with updating RouteMap.get) used with the HTML5 history API, it detects all the matching route patterns, parses the URL parameters and fires their methods with the arguments from the parsed URL; the timing of RouteMap.current and RouteMap.last being set is as follows (pseudo-code):

path: get_route             // RouteMap.get
parsed: parse path          // #parse
current: longest parsed     // RouteMap.current
parsed: pre_dispatch parsed // RouteMap.pre_dispatch
current: longest parsed     // reset current
fire matched rules in parsed
last: current               // RouteMap.last

RouteMap.handler calls #parse and does not catch any errors that function throws

See:: RouteMap.pre_dispatch

<static> {String} RouteMap.hash(rule, params)

returns a URL fragment by applying parameters to a rule; uses #compile and does not catch any errors thrown by that function

Parameters:
{Object} rule: the rule specification; it typically looks like:
{route:'/foo', method:'bar'}
but only route is strictly necessary
{Object} params: a dictionary of argument key/value pairs required by the rule

Throws:
{TypeError}: if a required parameter is not present

Returns:: {String} URL fragment resulting from applying arguments to rule pattern

<static> {Object} RouteMap.last()

returns the parsed (see #parse) last accessed route; when route listeners are being called, last is the previously accessed route, after listeners have finished firing, the current parsed route replaces last's value

Returns:: {Object} the last parsed URL object, will be null on first load

See:: RouteMap.current

<private> {Object} merge()

merges one or more objects into a new object by value (nothing is a reference), useful for cloning

Throws:
{TypeError}: if one of the arguments is not a mergeable object (i.e. a primitive, null or array)

Returns:: {Object} a merged object

<static> {Object} RouteMap.parse()

parses a URL fragment into a data structure only if there is a route whose pattern matches the fragment

Throws:
{TypeError}: if hash is not a string, is empty, or does not contain a '/' character
{SyntaxError}: if hash cannot be parsed by #parse

Returns:: {Object} of the form:
{page:'/foo', args:{bar:'some_value'}}
only if a rule with the route: '/foo/:bar' has already been added

<private> {Array} parse(path)

parses a path and returns a list of objects that contain argument dictionaries, methods, and raw hash values

Parameters:
{String} path

Throws:
{TypeError}: if the method specified by a rule specification does not exist during parse time

Returns:: {Array} a list of parsed objects in descending order of matched hash length

<static> {Object} RouteMap.post_add(compiled)

this function is called by RouteMap.add, it receives a compiled rule object, e.g. for the rule:

{route:'/foo/:id/:sub?/attr:/subattr:?/rest:*', method:'console.log'}

post_add would receive the following object:

{
    method:'console.log',
    rules:{
        scalars:[{name:'id',required:true},{name:'sub',required:false}],
        keyvals:[{name:'attr',required:true},{name:'subattr',required:false}],
        star:'rest'
    },
    raw:'/foo/:id/:sub?/attr:/subattr:?/rest:*'
}

and it is expected to pass back an object of the same format; it can be overwritten to post-process added rules e.g. to add extra default application-wide parameters; by default, it simply returns what was passed into it

Parameters:
{Object} compiled: the compiled rule

Returns:: {Object} the default function returns the exact object it received; a custom function needs to an object that is of the same form (but could possibly have more or fewer parameters, etc.)

<static> {Array} RouteMap.pre_dispatch(parsed)

like RouteMap.post_add this function can be overwritten to add application-specific code into route mapping, it is called before a route begins being dispatched to all matching rules; it receives the list of matching parsed route objects (#parse) and is expected to return it; one application of this function might be to set application-wide variables like debug flags

Parameters:
{Array} parsed: the parsed request

Returns:: {Array} a list of the same form as the one it receives

<static> {undefined} RouteMap.prefix(prefix)

if a string is passed in, it overwrites the prefix that is removed from each URL before parsing; primarily used for hashbang (#!); either way, it returns the current prefix

Parameters:
{String} prefix: (optional) the prefix string

<static> {undefined} RouteMap.remove(rule)

counterpart to RouteMap.add, removes a rule specification; * remove uses #compile and does not catch any errors thrown by that function

Parameters:
{Object} rule: the rule specification that was used in RouteMap.add

Throws:
{TypeError}: if rule.route or rule.method are not strings or empty strings