usage

Routes are used to describe a collection of related events, and provide a map that delegates the event to one or many application controllers.

There are several reasons why routing is a common pattern in popular application frameworks. The first reason is that routes are an excellent place to undertand, at a high level, an application features and where each feature is implemented. The second is that jquery-claypool can create a couple low-level controllers that have knowledge of all application events, so the application controllers can remain dormant until relevant events show up in the router.

options

hijax:a | hijax:form | hijax:event | hijax:input | hijax:button

There are several common option among all routers which we will describe first here. Additional aptions are described under each specific router below. Don't forget if these routers aren't enough you can create additional router types with the developer plugin $.router .

The event is the usual event jquery would pass if you had attached to events directly to your own controller, but jquery-claypool decorates it with some additional convenience methods. See event .

Name	Type
id	String
An application scope unique identifier.
active	Boolean	Default: true
Live binding to the DOM. This simply means that if this is a selector based router, then all live DOM changes are reflected and bound to the router when matched.
filter	String
The filter is appended to the selector (for example the primary selector for the hijax:a router is a). The filter can be any string which when concatenated with the primary selector is a valid jquery selector. The hijax:event router is not selector based so it makes no sense for it to honor this option.
stopPropagation	Boolean	Default: true
Stops the propagation of the event.
preventDefault	Boolean	Default: true
Prevents the default browser behavior.
strategy	String	Default: 'first'
Either 'all' or 'first'. This is similar to udp versus tcp routers on the web. 'first' simply the router will stop at the first match and route the event, while 'all' will continue down the list of available routes and continue to delegate the routes that match.
hijaxMap	Array
An array of objects, each object specifying a route. The options for a hijaxMap are generally specific to the router, so see each specific router below for details.

hijaxMap

The hijaxMap is an array of objects, and the expected options of each object varies only slightly between routers. Some routers use a href or action attribute so the route uses the option name 'urls', while some use the element id so the routes hijaxMap uses 'ids', and finally the event router uses 'event'.

Name	Type
urls|ids|event	String
A regular expression matching the route specific attribute of target links (for example href, action, id, or event name). Supports capturing expressions
controller	String
The application id of the controller to route the event to
action	String	Default: 'handle'
The name of the method that will be invoked on the target controller.

capturing expressions on routes

Most application framweorks that provide routers also allow a special syntax to allow the developer to specify captured expression in the route expression. All routes are regular expressions by two special syntaxes are check for before the expression is compiled.

• |:name|
  word expressions can be used to specify the name a portion of the expression will use to capture any word boundary match (a-zA-Z0-9_)+ The captured value will be available via the event.params('name') or event.params()['name']
• <:name(regexp):>
  any expressions can be used to specify the name used to store the captured match against the custom regxp provided inside the paranthesis.

/**
 * An example hijaxMap 
 *      This example shows the use of capturing expressions 
 *      which you may find in either the hijax:a or hijax:form 
 *      routers.  The hijax:input and hijax:button routers 
 *      would be similar but use 'ids' instead of 'urls'.  
 *      The event router does not use capturing expressions. 
 */
hijaxMap:
   [{
        urls:"examples/<:id([0-9]5-[a-z]3):>/$", 
        controller:"#quizController", 
        action:"score"
    },&#x7B;
        urls:"hello/|:name|/$", 
        controller:"#helloController", 
        action:"sayHello"}]

So assuming we had some marup like this

<a href="#hello/chris">say hello</a>

Then clicking that link would be routed to our controller.

(function($, $C){

    $C.Hello = function(options){
       //initialize the instance
       $.extend(true, this, options);
    };

    $.extend($C.Hello.prototype,{
        sayHello: function(event){
           var name = event.param('name');
           //name is 'chris'
        }
    });
})(jQuery, MyApp.Controllers);

hijax:a

hijax:a routes allow you to intercept click events on html hyperlinks. The match is based on regular expression tests against the href attribute. You can specify named parameters in the regular expression which will be passed are named parameters to a closure scope function, decorated on the event, event.param("name").

hijaxMap

Name	Type
urls	String
A regular expression matching the href attribute of target links. Supports capturing expressions

/*
 * @file app/configs/routes.js
 */
(function($){
    
    $.routes({
        //,.. other routes
        "hijax:a" : [{
            id:"#example-hash-routes",
            active: true,
            filter:"[href*=#]",
            stopPropagation:true,
            preventDefault:true,
            strategy:"first",
            hijaxMap:
                [{urls:"examples/|:id|/$", controller:"#quizController", action:"show"},
                {urls:"hello/|:name|/$", controller:"#helloController", action:"sayHello"}]
        /*,.. other hijax:a routes*/]
        //,.. other routes
    });
    
})(jQuery);

example

So assuming we had some mark up like this

<a href="#hello/chris">say hello</a>

Then clicking that link would be routed to our link controller.

(function($, $C){

    $C.Hello = function(options){
       //initialize the instance
       $.extend(true, this, options);
    };

    $.extend($C.Hello.prototype,{
        sayHello: function(event){
           var name = event.param('name');
           //name is 'chris'
        }
    });
})(jQuery, MyApp.Controllers);

hijax:form

hijax:form routes allow you to intercept submit events on html forms. The match is based on regular expression tests against the action attribute.

hijaxMap

Name	Type
urls	String
A regular expression matching the action attribute of target forms. Supports capturing expressions

/*
 * @file app/configs/routes.js
 */
(function($){
    
    $.routes({
        //,.. other routes
        "hijax:form" : [{
            id:"#example-form-routes",
            active: true,
            filter:"[action*=myapp]",
            stopPropagation:true,
            preventDefault:true,
            strategy:"first",
            hijaxMap:
                [{urls:"edit/|:id|/$", controller:"#quizController", action:"show"},
                {urls:"hello/|:name|/$", controller:"#helloController", action:"sayHello"}]
        }/*,.. other hijax:form routes*/]
        //,.. other routes
    });
    
})(jQuery);

example

So assuming we had some markup like this:

<form action="myapp/hello/chris" method='post'>
  <input type='submit' value='say hello'/>
</form>

Then clicking that submit button would be routed to our form controller.

(function($, $C){

    $C.Hello = function(options){
       //initialize the instance
       $.extend(true, this, options);
    };

    $.extend($C.Hello.prototype,{
        sayHello: function(event){
           var name = event.param('name');
           //name is 'chris'
        }
    });
})(jQuery, MyApp.Controllers);

hijax:button

hijax:button routes allow you to intercept click events on html inputs with type='button'. The match is based on regular expression tests against the id attribute.

hijaxMap

Name	Type
ids	String
A regular expression matching the id attribute of target buttons. Supports capturing expressions

/*
 * @file app/configs/routes.js
 */
(function($){
    
    $.routes({
        //,.. other routes
        "hijax:button" : [{
            id:"#example-dialog-routes",
            active: true,
            filter:"[id*=dialog]",
            stopPropagation:true,
            preventDefault:true,
            strategy:"all",
            hijaxMap:
               [{ids:"show/|:id|$", controller:"#dialogController", action:"show"},
               {ids:"hide/|:id|$", controller:"#dialogController", action:"hide"},
               {ids:"close/|:id|$", controller:"#dialogController", action:"close"}]
        }/*,.. other hijax:button routes*/]
        //,.. other routes
    });
    
})(jQuery);

example

So assuming we had some markup like this:

<form id='mydialog'>
   <input id='dialog/show/123-456-7' type='button' value='0'/>
   <input id='dialog/hide/123-456-7' type='button' value='_'/>
   <input id='dialog/close/123-456-7' type='button' value='X'/>
</form>

Then clicking the 'X' button would be routed to our dialog controller.

(function($, $C){

    $C.Dialog = function(options){
       //initialize the instance
       $.extend(true, this, options);
    };

    $.extend($C.Dialog.prototype,{
        close: function(event){
           var id = event.param('id');
           //id is '123-456-7'
        }
    });
})(jQuery, MyApp.Controllers);

hijax:input

hijax:input routes allow you to intercept blur events on html inputs. The match is based on regular expression tests against the id attribute.

hijaxMap

Name	Type
ids	String
A regular expression matching the id attribute of target inputs. Supports capturing expressions

/*
 * @file app/configs/routes.js
 */
(function($){
    
    $.routes({
        //,.. other routes
        "hijax:input" : [{
            id:"#example-dialog-routes",
            active: true,
            filter:"[type=text][id*=register]",
            stopPropagation:true,
            preventDefault:true,
            strategy:"all",
            hijaxMap:
               [{ids:"/|:id|/|:field_name|$", controller:"#registrationController", action:"validate"}]
        }/*,.. other hijax:input routes*/]
        //,.. other routes
    });
    
})(jQuery);

example

So assuming we had some markup like this:

<form id='registration'>
   <input id='register/123-456-7/zipcode' type='text' value=''/>
   <input id='register/123-456-7/first_name' type='text' value=''/>
   <input id='register/123-456-7/last_name' type='text' value=''/>
</form>

Then typing into text area and tabbing to the next, an event would be routed to our event controller.

(function($, $C){

    $C.Register = function(options){
       //initialize the instance
       $.extend(true, this, options);
    };

    $.extend($C.Register.prototype,{
        validate: function(event){
           var field_name = event.param('field_name');
           if(field_name == 'zipcode'){
              //make sure its valid or set a flash message
           }
        }
    });
})(jQuery, MyApp.Controllers);

hijax:event

hijax:event routes allow you to intercept custom events in your application. The match is based on an exact match since the event name must be supplied to the router exactly so that it may bind to the events. It is unique among application routers because it does not provide regular expression support.

hijaxMap

Name	Type
ids	String
A string matching exactly the name of the target events

/*
 * @file app/configs/routes.js
 */
(function($){
    
    $.routes({
        //,.. other routes
        "hijax:event" : [{
            id:"#example-event-routes",
            stopPropagation:true,
            preventDefault:true,
            strategy:"all",
            hijaxMap:
                [{event:"autosave", controller:"#quizController", action:"save"},
                {event:"hello", controller:"#helloController", action:"sayHello"}]
        }/*,.. other hijax:event routes*/]
        //,.. other routes
    });
    
})(jQuery);

example

So assuming we had some jquery like this:

$(document).trigger('hello', ['chris']);

Then our event router will send the event on to our application controller.

(function($, $C){

    $C.Hello = function(options){
       //initialize the instance
       $.extend(true, this, options);
    };

    $.extend($C.Hello.prototype,{
        sayHello: function(event, name){
           //name is 'chris'
        }
    });
})(jQuery, MyApp.Controllers);