usage

Controllers

Controllers are just regular event handlers! The only difference is that jquery-claypool decorates the event object with some handy, dandy, mvc to help you cleanly separate your event handling from your presentation and data access functions. We will cover these functions here because they will generally only ever be used in your controllers, but first lets go over a couple things that will help you avoid common mistakes if you are new to mvc.

Aggregating Event Scope State

The primary goal of the controller is to aggregate some data to pass to the view. The data may be cached, gotten via ajax, entirely made up, or all of the above. It is aggregated in a new object which is passed to the view or passed along to other controllers if control is forwarded. The aggregated data is called event scoped state because the aggregation is not persistent, and disappears when the event propogation is complete.

Leave Presentation to the Experts

Controllers are free to peruse all the info they want in the DOM but they should leave the presentation to the views. It's not a steadfast rule, sometimes a controller will modify the DOM, but usually only in ways you don't see.

options

event.m().v().c().render(callback)

The title say's it well, but you should check out the specifics here.

Name	Type
event.m( )	Returns: Object
overloaded function getters and setters of the event model. chainable setters.
event.v( )	Returns: Object
overloaded function getters and setters of the event view. chainable setters. relates to which method will be used by event.render
event.c( )	Returns: Object
getter and setter to introspect the current controller and forward control to other controllers. setter is chainable.
event.render( )	Returns: Object
triggers jquery-claypool to resolve the view instance and call the view method.
event.params( )	Returns: Object
returns all route params as an object or a single route param by name.
event.reset( )	Returns: chainable
resets the internal m, v, c settings to the initial state.

examples

Building a Good and Lazy Controller

Let's start by creating a simple closure that will define our controller.

/*
 * @file app/controllers/hello.js
 * @description You can feel free to use your 
 *     own writing style, we are providing an
 *     example not a rigid requirement of how to
 *     you have to write event handers.  If you 
 *     want to take advantage of the mvc scanners
 *     (and keep the global scope clean) you should
 *     use a closure and single top-level namespace.
 *     In this example we use 'MyApp'
 */
(function($, $C){
    
    $C.Hello = function(options){
        $.extend(true, this, options);
    };

    $.extend($C.Hello.prototype, {
        handle: function(event){
           //event handling code here
        }
    });
    
})(jQuery, MyApp.Controllers);

This is a good lazy controller because it doesn't actively do anything when the anonymous closure is executed other than define itself.

A Presumptuous Controller

Lets start using this mvc thing a little but keep it real simple.

handle: function(event){
    event.m({
       first_name:'chris',
       last_name:'thatcher',
       order:[{
          type:'pizza,
          opts:['cheese', 'anchovies', 'pineapple', 'black beans'],
          quantity: 5
       }]
    }).render();
}

WoW! That was amazing! But very presumptuous, because I would have wanted some hamburger on it today as well...

A Thoughtful Controller

Lets dive in.

handle: function(event){
    event.
       v('.think').                 //show activity in progress
       render(function(){           //mvc callback after '.think'
          $.$('#pizzaModel').order( //order the pizza via ajax
              event.params(),       //(mmm hamburger)
              function(model){      //ajax callback from model
                  event.
                     m(model).      //json summary of order
                     v('.update').  //update the page
                     render();
              });
       });
}

OMG! How thoughtful indeed.