usage

Views

Views update the DOM. jquery-claypool doesn't come with any DOM manipulation strategies because jquery already provides everything you need to gracefully manipulate the dom. There are also already several templating plugins for jquery like srender and jtemplates. are a couple conventions you should know about so you can take full advantage of the view pattern in jquery-claypool

Views Are jQuery

It's true, they love the dom so much they attach themselves to it, and are in fact jQuery instances. how does this happen so magically? Well, if I have a view named 'Hello', it will automatically attach itself to the dom node with the id 'hello' when ever it appears in the dom (using live binding). This convention can be customized to allow a single view to attach to many nodes, but in general if a view is singular on the page it is identified by id.

Views Are Not jQuery

A View is not obligated to be a dom node, often a View is responsible for rendering one, two, or ten similar nodes, and it may render them selectively or all together. The important design goal of the view is that it simply consolidate visible updates to the DOM so the events net visual result can be isolated clearly.

options

model

Views refer to the parameter passed to them as the 'model'. The Views model is really only an aggregation of state information that was provided by the controller, not a Model (which is usually a data access object with some validation routines) The 'model' is just an object, each named value provided entirely at the discretion of the controller, and perhaps embellished by a filter.
See also event.m()

The model (lower case m) can also be refered to as the request scope , or the event scope . It is born with the event, and disappears when the event controller flow is ended.

The model will always include an array named 'flash'. this concept was lovingly borrowed from Rails. The array should be an array of objects, each object containing an hash of name/value pairs that are intended to provide feed back about incorrect or invalid user input or errors from controllers and models.
See also event.flash()

examples

think update

yes, think AND update. there is no steadfast rules, though by default the controller will pass the model to the view method 'update' unless you specify another method. we do recommend you usually have at least two methods for views though, so one method 'think' can be used to let the interface know the view is about to be updated. eg show a spinner or flash a color or block the ui component or display a message etc.

Building a jQuery View

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

/*
 * @file app/views/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 views.  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($, $V){
    
    $V.Hello = function(options){
        $.extend(true, this, options);
     };

    $.extend($V.Hello.prototype, {
        update: function(model){
           //update the dom here
         }
     });
    
 })(jQuery, MyApp.Views);
        

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

A Presumptuous View

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

    update: function(model){
        // recall 'this' is a jquery context
        // because the instance is auto-magically
        // attached to $('#hello')
        $('.msg', this).text('Hi there world!');
    }
        

WoW! That was amazing! But very presumptuous, because I am not really the world just a modest fella... Note: A view does not always need to be attached to a dom node..., and often will use information passed from the controller to update a particular node. This is more common when there are many 'like' elements on a page whose rendering is all managed by a single view.

A Thoughtful View

Lets dive in.

think: function(){
    $('.msg', this).text('learning about you!');
},
update: function(model){
    $('.msg', this).text('Hi there '+model.username);
}
        

Note that model.username is a named piece of data that was provided by the controller using

        event.m({username:'chuck norris'});
        

templates

Templates are also described in detail app/templates
Templates are often used by views to render content to the dom. jquery-claypool has not requirements that you use or don't use templates, but simply makes it a very easy to integrate with your prefered View technology.
That said, we encourage the use of templates in projects where html and css development is managed by folks who are not javascript experts. It simply provides an additional measure of seperation and clarity for those will manage markup and style changes.