Views

Views define how the your application looks. It's should mostly be views that are responsible for what gets included into the DOM tree. For example, views create DOM elements such as headings, container elements, paragraphs and other elements that it fills with content. The content is usually given to the view by the controller (which, in turn, usually gets them from models).


Public functions for handling views


$views.add()

Adds (registers) a new view (but does not start it yet).
Arguments: [string] viewName, [function] constructor, [object] methods
$views.add('article', function(options) {
// this here is the constructor function of the view. here we can do something with options if we want to.
}, {
onStart: function() {
this.helloElement = $('.h1').show().html('Hello world!').appendTo('body');
},
onStop: function() {
this.helloElement.remove();
}
});


$views.start()

Instantiates a view, starts it and returns the view instance.
Arguments: [string] viewName, [mixed] options
Returns: [viewInstance]
var someView = $views.start('article', { key: 'value', key2: 'value2', key3: { subkey1: 'subvalue' } });

By doing this, you can start a view called article. When you start a view, a new instance of that view is created and returned to you (loaded into the someView variable in the example above). This means you can access the view methods directly from the controller like this: someView.[methodName]();


Passing variables to views

The second argument (called options) is meant for passing variables to the view. The keys (values) you pass in the second argument will end up being available from the constructor function of the view. In addition to that, these keys (and values) will get prototyped to that view instance, meaning they are available anywhere from the view via this.key and this.key2 and this.key3 . The prototyping only happens when the passed keys do not override any of the native (previously prototyped) methods.


$views.stop()

Stops a view instance.
Arguments: [viewInstance]
Returns: [boolean] true if the view was stopped
$views.stop(someView);
Note: you can also stop views directly through their instances like this: someView.stop();


Common functions available from within view instances


this.listen()

Starts a new listener. (Note: this function is only available from within the scope of a view or a controller instance)
Arguments: [string] eventName, [function] callback
this.listen('uri.changed', function() { alert('Someone changed the URI!'); });
The example above would register a new listener function that gets triggered whenever the 'uri.changed' event occurs. (Note: the 'uri.changed' event is a common event that occurs automatically every time the application URI is changed.)
You can also bind multiple listeners to the same event within one view.

All listeners are deleted upon stopping the view instance.

this.trigger()

Triggers an event. (Note: this function is only available from within the scope of a view or a controller instance)
Arguments: [string] eventName, [mixed] data
this.trigger('someEvent', { key1: 'data1', key2: 'data2' });
The example above would trigger an event called 'someEvent'. All listeners that are bound to that event get executed at that point.

Events scope
All events listened to and triggered from views are shared throughout the application. This means you can trigger an event from a view and listen to that event from a controller, and vice versa.