Skip to content
This repository was archived by the owner on Mar 1, 2025. It is now read-only.

Commit 2206b99

Browse files
btfordbtford
committed
docs(guide/di): fix formatting and improve clarity
1 parent 989f6f2 commit 2206b99

File tree

1 file changed

+90
-88
lines changed

1 file changed

+90
-88
lines changed

‎docs/content/guide/di.ngdoc

+90-88
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
Dependency Injection (DI) is a software design pattern that deals with how code gets hold of its
88
dependencies.
99

10+
The Angular injector subsystem is in charge of service instantiation, resolution
11+
of dependencies, and provision of dependencies to components as requested.
12+
1013
For in-depth discussion about DI, see
1114
[Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection) at Wikipedia,
1215
[Inversion of Control](http://martinfowler.com/articles/injection.html) by Martin Fowler,
@@ -17,9 +20,7 @@ or read about DI in your favorite software design pattern book.
1720
There are only three ways an object or a function can get a hold of its dependencies:
1821

1922
1. The dependency can be created, typically using the `new` operator.
20-
2123
2. The dependency can be looked up by referring to a global variable.
22-
2324
3. The dependency can be passed in to where it is needed.
2425

2526

@@ -32,13 +33,13 @@ The third option is the most viable, since it removes the responsibility of loca
3233
dependency from the component. The dependency is simply handed to the component.
3334

3435
```js
35-
function SomeClass(greeter) {
36-
this.greeter = greeter;
37-
}
38-
39-
SomeClass.prototype.doSomething = function(name) {
40-
this.greeter.greet(name);
41-
}
36+
function SomeClass(greeter) {
37+
this.greeter = greeter;
38+
}
39+
40+
SomeClass.prototype.doSomething = function(name) {
41+
this.greeter.greet(name);
42+
}
4243
```
4344

4445
In the above example `SomeClass` is not concerned with locating the `greeter` dependency, it
@@ -56,50 +57,50 @@ construction and lookup of dependencies.
5657
Here is an example of using the injector service:
5758

5859
```js
59-
// Provide the wiring information in a module
60-
angular.module('myModule', []).
61-
62-
// Teach the injector how to build a 'greeter'
63-
// Notice that greeter itself is dependent on '$window'
64-
factory('greeter', function($window) {
65-
// This is a factory function, and is responsible for
66-
// creating the 'greet' service.
67-
return {
68-
greet: function(text) {
69-
$window.alert(text);
70-
}
71-
};
72-
});
73-
74-
// New injector is created from the module.
75-
// (This is usually done automatically by angular bootstrap)
76-
var injector = angular.injector(['myModule', 'ng']);
77-
78-
// Request any dependency from the injector
79-
var greeter = injector.get('greeter');
60+
// Provide the wiring information in a module
61+
angular.module('myModule', []).
62+
63+
// Teach the injector how to build a 'greeter'
64+
// Notice that greeter itself is dependent on '$window'
65+
factory('greeter', function($window) {
66+
// This is a factory function, and is responsible for
67+
// creating the 'greet' service.
68+
return {
69+
greet: function(text) {
70+
$window.alert(text);
71+
}
72+
};
73+
});
74+
75+
// New injector is created from the module.
76+
// (This is usually done automatically by angular bootstrap)
77+
var injector = angular.injector(['myModule', 'ng']);
78+
79+
// Request any dependency from the injector
80+
var greeter = injector.get('greeter');
8081
```
8182

8283
Asking for dependencies solves the issue of hard coding, but it also means that the injector needs
8384
to be passed throughout the application. Passing the injector breaks the [Law of Demeter](http://en.wikipedia.org/wiki/Law_of_Demeter). To remedy this, we turn the
8485
dependency lookup responsibility to the injector by declaring the dependencies as in this example:
8586

8687
```html
87-
<!-- Given this HTML -->
88-
<div ng-controller="MyController">
89-
<button ng-click="sayHello()">Hello</button>
90-
</div>
88+
<!-- Given this HTML -->
89+
<div ng-controller="MyController">
90+
<button ng-click="sayHello()">Hello</button>
91+
</div>
9192
```
92-
93+
9394
```js
94-
// And this controller definition
95-
function MyController($scope, greeter) {
96-
$scope.sayHello = function() {
97-
greeter.greet('Hello World');
98-
};
99-
}
100-
101-
// The 'ng-controller' directive does this behind the scenes
102-
injector.instantiate(MyController);
95+
// And this controller definition
96+
function MyController($scope, greeter) {
97+
$scope.sayHello = function() {
98+
greeter.greet('Hello World');
99+
};
100+
}
101+
102+
// The 'ng-controller' directive does this behind the scenes
103+
injector.instantiate(MyController);
103104
```
104105

105106
Notice that by having the `ng-controller` instantiate the class, it can satisfy all of the
@@ -123,9 +124,9 @@ The simplest way to get hold of the dependencies, is to assume that the function
123124
are the names of the dependencies.
124125

125126
```js
126-
function MyController($scope, greeter) {
127-
...
128-
}
127+
function MyController($scope, greeter) {
128+
// ...
129+
}
129130
```
130131

131132
Given a function the injector can infer the names of the service to inject by examining the
@@ -142,10 +143,10 @@ the function needs to be annotated with the `$inject` property. The `$inject` pr
142143
of service names to inject.
143144

144145
```js
145-
var MyController = function(renamed$scope, renamedGreeter) {
146-
...
147-
}
148-
MyController['$inject'] = ['$scope', 'greeter'];
146+
var MyController = function(renamed$scope, renamedGreeter) {
147+
...
148+
}
149+
MyController['$inject'] = ['$scope', 'greeter'];
149150
```
150151

151152
In this scenario the ordering of the values in the '$inject' array must match the ordering of the arguments to inject.
@@ -164,51 +165,52 @@ directives.
164165
For example:
165166

166167
```js
167-
someModule.factory('greeter', function($window) {
168-
...
169-
});
168+
someModule.factory('greeter', function($window) {
169+
// ...
170+
});
170171
```
171172

172173
Results in code bloat due to needing a temporary variable:
173174

174175
```js
175-
var greeterFactory = function(renamed$window) {
176-
...
177-
};
178-
179-
greeterFactory.$inject = ['$window'];
180-
181-
someModule.factory('greeter', greeterFactory);
176+
var greeterFactory = function(renamed$window) {
177+
// ...
178+
};
179+
180+
greeterFactory.$inject = ['$window'];
181+
182+
someModule.factory('greeter', greeterFactory);
182183
```
183184

184185
For this reason the third annotation style is provided as well.
185186

186187
```js
187-
someModule.factory('greeter', ['$window', function(renamed$window) {
188-
...
189-
}]);
188+
someModule.factory('greeter', ['$window', function(renamed$window) {
189+
// ...
190+
}]);
190191
```
191192

192193
Keep in mind that all of the annotation styles are equivalent and can be used anywhere in Angular
193194
where injection is supported.
194195

195196
## Where can I use DI?
196197

197-
DI is pervasive throughout Angular. It is typically used in controllers and factory methods.
198+
DI is pervasive throughout Angular. You can use it in controllers, services, directives, filters,
199+
animations, and `run` and `config` blocks.
198200

199201
### DI in controllers
200202

201-
Controllers are classes which are responsible for application behavior. The recommended way of
203+
Controllers are classes which are responsible for application behavior. The recommended way of
202204
declaring controllers is using the array notation:
203205

204206
```js
205-
someModule.controller('MyController', ['$scope', 'dep1', 'dep2', function($scope, dep1, dep2) {
207+
someModule.controller('MyController', ['$scope', 'dep1', 'dep2', function($scope, dep1, dep2) {
208+
...
209+
$scope.aMethod = function() {
206210
...
207-
$scope.aMethod = function() {
208-
...
209-
}
210-
...
211-
}]);
211+
}
212+
...
213+
}]);
212214
```
213215

214216
This avoids the creation of global functions for controllers and also protects against minification.
@@ -221,20 +223,20 @@ services, and filters. The factory methods are registered with the module, and t
221223
of declaring factories is:
222224

223225
```js
224-
angular.module('myModule', []).
225-
config(['depProvider', function(depProvider){
226-
...
227-
}]).
228-
factory('serviceId', ['depService', function(depService) {
229-
...
230-
}]).
231-
directive('directiveName', ['depService', function(depService) {
232-
...
233-
}]).
234-
filter('filterName', ['depService', function(depService) {
235-
...
236-
}]).
237-
run(['depService', function(depService) {
238-
...
239-
}]);
226+
angular.module('myModule', []).
227+
config(['depProvider', function(depProvider){
228+
...
229+
}]).
230+
factory('serviceId', ['depService', function(depService) {
231+
...
232+
}]).
233+
directive('directiveName', ['depService', function(depService) {
234+
...
235+
}]).
236+
filter('filterName', ['depService', function(depService) {
237+
...
238+
}]).
239+
run(['depService', function(depService) {
240+
...
241+
}]);
240242
```

0 commit comments

Comments
 (0)