In angular, a controller is a JavaScript function(type/class) that is used to augment instances of
angular Scope, excluding the root scope. When you or angular create a new
child scope object via the scope.$new
API , there is an
option to pass in a controller as a method argument. This will tell angular to associate the
controller with the new scope and to augment its behavior.
Use controllers to:
Typically, when you create an application you need to set up an initial state for an angular scope.
Angular applies (in the sense of JavaScript's Function#apply
) the controller constructor function
to a new angular scope object, which sets up an initial scope state. This means that angular never
creates instances of the controller type (by invoking the new
operator on the controller
constructor). Constructors are always applied to an existing scope object.
You set up the initial state of a scope by creating model properties. For example:
function GreetingCtrl() { this.greeting = 'Hola!'; }
The GreetingCtrl
controller creates a greeting
model which can be referred to in a template.
When a controller function is applied to an angular scope object, the this
of the controller
function becomes the scope of the angular scope object, so any assignment to this
within the
controller function happens on the angular scope object.
Behavior on an angular scope object is in the form of scope method properties available to the template/view. This behavior interacts with and modifies the application model.
As discussed in the Model section of this guide, any
objects (or primitives) assigned to the scope become model properties. Any functions assigned to
the scope, along with any prototype methods of the controller type, become functions available in
the template/view, and can be invoked via angular expressions and ng:
event handlers (e.g. ng:click
). These controller methods are always evaluated within the
context of the angular scope object that the controller function was applied to (which means that
the this
keyword of any controller method is always bound to the scope that the controller
augments). This is how the second task of adding behavior to the scope is accomplished.
In general, a controller shouldn't try to do too much. It should contain only the business logic needed for a single view.
The most common way to keep controllers slim is by encapsulating work that doesn't belong to controllers into services and then using these services in controllers via dependency injection. This is discussed in the Dependency Injection Services sections of this guide.
Do not use controllers for:
You can associate controllers with scope objects explicitly via the scope.$new
api or implicitly via the ng:controller directive
or $route service
.
To illustrate how the controller component works in angular, let's create a little app with the following components:
spice
spice
The message in our template contains a binding to the spice
model, which by default is set to the
string "very". Depending on which button is clicked, the spice
model is set to chili
or
jalapeño
, and the message is automatically updated by data-binding.
<body ng:controller="SpicyCtrl"> <button ng:click="chiliSpicy()">Chili</button> <button ng:click="jalapenoSpicy()">Jalapeño</button> <p>The food is {{spice}} spicy!</p> </body> function SpicyCtrl() { this.spice = 'very'; this.chiliSpicy = function() { this.spice = 'chili'; } } SpicyCtrl.prototype.jalapenoSpicy = function() { this.spice = 'jalapeño'; }
Things to notice in the example above:
ng:controller
directive is used to (implicitly) create a scope for our template, and the
scope is augmented (managed) by the SpicyCtrl
controller.SpicyCtrl
is just a plain JavaScript function. As an (optional) naming convention the name
starts with capital letter and ends with "Ctrl" or "Controller".this
in the SpicyCtrl
function is bound to the scope that the
controller augments.this
creates or updates the model.chiliSpicy
method) or
as prototype methods of the controller constructor function(the jalapenoSpicy
method)body
element and and its
children).Controller methods can also take arguments, as demonstrated in the following variation of the previous example.
<body ng:controller="SpicyCtrl"> <input ng:model="customSpice" value="wasabi"> <button ng:click="spicy('chili')">Chili</button> <button ng:click="spicy(customSpice)">Custom spice</button> <p>The food is {{spice}} spicy!</p> </body> function SpicyCtrl() { this.spice = 'very'; this.spicy = function(spice) { this.spice = spice; } }
Notice that the SpicyCtrl
controller now defines just one method called spicy
, which takes one
argument called spice
. The template then refers to this controller method and passes in a string
constant 'chili'
in the binding for the first button and a model property spice
(bound to an
input box) in the second button.
Controller inheritance in angular is based on Scope
inheritance. Let's
have a look at an example:
<body ng:controller="MainCtrl"> <p>Good {{timeOfDay}}, {{name}}!</p> <div ng:controller="ChildCtrl"> <p>Good {{timeOfDay}}, {{name}}!</p> <p ng:controller="BabyCtrl">Good {{timeOfDay}}, {{name}}!</p> </body> function MainCtrl() { this.timeOfDay = 'morning'; this.name = 'Nikki'; } function ChildCtrl() { this.name = 'Mattie'; } function BabyCtrl() { this.timeOfDay = 'evening'; this.name = 'Gingerbreak Baby'; }
Notice how we nested three ng:controller
directives in our template. This template construct will
result in 4 scopes being created for our view:
MainCtrl
scope, which contains timeOfDay
and name
modelsChildCtrl
scope, which shadows the name
model from the previous scope and inherits the
timeOfDay
modelBabyCtrl
scope, which shadows both the timeOfDay
model defined in MainCtrl
and name
model defined in the ChildCtrlInheritance works between controllers in the same way as it does with models. So in our previous examples, all of the models could be replaced with controller methods that return string values.
Note: Standard prototypical inheritance between two controllers doesn't work as one might expect, because as we mentioned earlier, controllers are not instantiated directly by angular, but rather are applied to the scope object.
The way to test a controller depends upon how complicated the controller is.
new
operator and test away. For example:Controller Function:
function myController() { this.spices = [{"name":"pasilla", "spiciness":"mild"}, {"name":"jalapeno", "spiceiness":"hot hot hot!"}, {"name":"habanero", "spiceness":"LAVA HOT!!"}]; this.spice = "habanero"; }
Controller Test:
describe('myController function', function() { describe('myController', function() { var ctrl; beforeEach(function() { ctrl = new myController(); }); it('should create "spices" model with 3 spices', function() { expect(ctrl.spices.length).toBe(3); }); it('should set the default value of spice', function() { expect(ctrl.spice).toBe('habanero'); }); }); });
scope.$new(MyController)
. Test the controller using $eval
, if necessary.