Controllers make your applications work,
they control your application behavior. All event handling and
application logic should happen in the controllers. Controllers are
not usually responsible for creating any DOM elements but they do
pass them around between views from time to time (only between the
views the controller "owns").
Public functions for
handling controllers
$controllers.add()
Adds
(registers) a new controller (but does not start it yet).
Arguments: [string] controllerName,
[function] constructor, [object] methods
$controllers.add('articles', function(options) {
// this here is the constructor function of the controller. here we
can do something with options if we want to.
}, {
onStart: function() {
this.helloView = views.start('someView', { text: 'Hello World'
});
},
onStop: function() {
this.helloView.stop();
}
});
$controllers.start()
Starts
the application, or starts a specific controller.
Arguments: (optional) [string]
controllerName, [mixed] options
Returns: [controllerInstance]
var someController = controllers.start('article', { key: 'value',
key2: 'value2', key3: { subkey1: 'subvalue' } });
By doing this, you can start a
controller called article. When
you start a controller, a new instance of that controller is
created and returned to you (loaded into the someController variable in the example
above). This means you can access the controller methods directly
from the controller like this: someController.[methodName]();
Calling $controllers.start() with
no arguments
If you
omit the controllerName and pass no arguments to the
$controllers.start() function, Maverick tries to find the
controller that is routed to the current URI based on the
routes.
Passing
variables to controllers
The second argument (called options)
is meant for passing variables to the controller. The keys (values)
you pass in the second argument will end up being available from
the constructor function of the controller. In addition to that,
these keys (and values) will get prototyped to that controller
instance, meaning they are available anywhere from the controller
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.
$controllers.stop()
Stops a
controller instance.
Arguments:
[controllerInstance]
Returns: [boolean] true if the
controller was stopped
$controllers.stop(someController);
Note: you can also stop controllers directly through their
instances like this: someController.stop();
$controllers.autoStart()
Enable/disable the automatic URI to
controller routing (which is enabled by default)
Arguments: [boolean] enabled
$controllers.autoStart(false);
This is extremely useful when you want to
intercept the URI to controller routing or build your
own.
Note: the demo application bundled with
the download also disables the automatic URI to controller routing
to keep the navigation bar in the top area of the application
persistent across any URI changes and only change the
contentContainer element's contents.
Common functions
available from within controller instances
this.listen()
Starts a new
listener. (Note: this function is only available from within the
scope of a controller or a view 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 controller.
All listeners are deleted upon stopping
the controller instance.
this.trigger()
Triggers an
event. (Note: this function is only available from within the scope
of a controller or a view 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
controllers are shared throughout the application. This means you
can trigger an event from a controller and listen to that event
from a view, and vice versa.