Jump to content

Controllers

Overview

Controllers are special modules that handle specific functionality on specific pages. They are not necessarily reusable in different contexts, although some may be. A controller is initialized on an individual element, and that element becomes the controller's scope. A controller responds to user events (such as click) and events triggered by UI widgets or sub-controllers, and manipulates its scope element accordingly.

The scope of a controllers functionality is entirely flexible. A controller might be initialized on a very small fragment of the page and perform just one task, or it might be initialized on a main wrapper and handle functionality that applies to the whole page. A controller can be initialized on an element even if it's a descendent of another element with a controller; this is a common pattern whereby the child controller can emit events that the parent controller can respond to.

Generally, keep a controller narrowly focused on one aspect of the page. If a controller ends up handing distinct and unrelated functionality, split it into smaller controllers.

Creating a controller

A controller is registered in a slightly different way to standard modules; instead, an object literal is passed to the method ips.controller.register: 

;( function($, _, undefined){
	"use strict";

	ips.controller.register('type.controllerID', {
		initialize: function () {
			// Controller events are initialized here
		}
	});
}(jQuery, _));

A controller, at the very least, must define an initialize method, which is called when the controller is initialized on an element. The initialize method should set up events that are handled by this controller only; if other initialization tasks are necessary, it is recommended that you define a setup method within the controller, and call that at the start or end of the initialize method as appropriate.

Within the controller definition, this refers to the controller instance. That means controller methods can be called internally with this.someMethod().

A reference to the element that the controller is initialized on (its scope) is available with the scope property: 

// An example which hides the element
this.scope.hide();

Method and property names

For clarity, it is recommended that event handler method names (i.e. the handlers to events you set up in initialize) are not prefixed with an underscore, while other methods and properties of the controller are. This helps create a clear distinction between core functionality of the controller (the event handlers) and supporting methods.

Handling events

Event handling is the core purpose of a controller. There are three special methods available for watching and triggering events. Two are named after their jQuery counterparts, but add controller-specific behavior.

this.on

Used for watching and responding to events. 

this.on( [element elem,] string eventType [, selector delegate], function callback );
  • elem
    A reference to the element on which the event will be watched for. If not specified, this.scope is used by default.
  • eventType
    The event being watched for. This can be a default browser event, like click, or events from widgets and models, like menuItemSelected.
  • delegate
    A delegate selector can optionally be specified. See the jQuery documentation for more information.
  • callback
    A callback function, called when this event is observed. The function specified here is automatically bound to this, so internal methods can be passed simply by referencing them like so: 
    this.on( 'click', this.internalMethod );

 

this.trigger

Used to emit events that originate from this controller (specifically, the scope element). 

this.trigger( [element elem,] string eventType [, object data] );
  • elem
    A reference to the element on which the event will be triggered. If not specified, this.scope is used by default.
  • eventType
    The event being triggered.
  • data
    An object containing data relevant to the event.

 

this.triggerOn

Used to emit events directly on sub-controllers from a parent controller. 

this.triggerOn( string controllerName, string eventType [, object data] );
  • controllerName
    The controller name to find and trigger the event on. The wildcard character (*) is supported at the end of this parameter and the event will be triggered on all matching controllers. Examples: 
    core.front.core.comment
core.front.core.*
core.*
  • eventType
    The event being triggered.
  • data
    An object containing data relevant to the event.
Edited by Rikki
  Report Guide


Invision Community © 2024 IPS, Inc.
×
×
  • Create New...