forked from angular/angular.js
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathstep_03.ngdoc
290 lines (220 loc) · 10.6 KB
/
step_03.ngdoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
@ngdoc tutorial
@name 3 - Components
@step 3
@description
<ul doc-tutorial-nav="3"></ul>
In the previous step, we saw how a controller and a template worked together to convert a static
HTML page into a dynamic view. This is a very common pattern in Single-Page Applications in general
(and AngularJS applications in particular):
* Instead of creating a static HTML page on the server, the client-side code "takes over" and
interacts dynamically with the view, updating it instantly to reflect changes in model data or
state, usually as a result of user interaction (we'll see an example shortly in
{@link step_05 step 5}).
The **template** (the part of the view containing the bindings and presentation logic) acts as a
blueprint for how our data should be organized and presented to the user.
The **controller** provides the context in which the bindings are evaluated and applies behavior
and logic to our template.
There are still a couple of areas we can do better:
1. What if we want to reuse the same functionality in a different part of our application ?<br />
We would need to duplicate the whole template (including the controller). This is error-prone and
hurts maintainability.
2. The scope, that glues our controller and template together into a dynamic view, is not isolated
from other parts of the page. What this means is that a random, unrelated change in a different
part of the page (e.g. a property-name conflict) could have unexpected and hard-to-debug side
effects on our view.
(OK, this might not be a real concern in our minimal example, but it **is** a valid concern for
bigger, real-world applications.)
<div doc-tutorial-reset="3"></div>
## Components to the rescue!
Since this combination (template + controller) is such a common and recurring pattern, AngularJS
provides an easy and concise way to combine them together into reusable and isolated entities,
known as _components_.
Additionally, AngularJS will create a so called _isolate scope_ for each instance of our component,
which means no prototypal inheritance and no risk of our component affecting other parts of the
application or vice versa.
<div class="alert alert-info">
<p>
Since this is an introductory tutorial, we are not going to dive deep into all features provided
by AngularJS **components**. You can read more about components and their usage patterns in the
[Components](guide/component) section of the Developer Guide.
</p>
<p>
In fact, one could think of components as an opinionated and stripped-down version of their more
complex and verbose (but powerful) siblings, **directives**, which are AngularJS's way of teaching
HTML new tricks. You can read all about them in the [Directives](guide/directive) section of the
Developer Guide.
</p>
<p>
(**Note:** Directives are an advanced topic, so you might want to postpone studying them, until
you have mastered the basics.)
</p>
</div>
To create a component, we use the {@link angular.Module#component .component()} method of an
{@link module AngularJS module}. We must provide the name of the component and the Component
Definition Object (CDO for short).
Remember that (since components are also directives) the name of the component is in `camelCase`
(e.g. `myAwesomeComponent`), but we will use `kebab-case` (e.g. `my-awesome-component`) when
referring to it in our HTML. (See [here][case-styles] for a description of different case styles.)
In its simplest form, the CDO will just contain a template and a controller. (We can actually omit
the controller and AngularJS will create a dummy controller for us. This is useful for simple
"presentational" components, that don't attach any behavior to the template.)
Let's see an example:
```js
angular.
module('myApp').
component('greetUser', {
template: 'Hello, {{$ctrl.user}}!',
controller: function GreetUserController() {
this.user = 'world';
}
});
```
```html
<body>
<!-- The following line is how to use the `greetUser` component above in your html doc. -->
<greet-user></greet-user>
</body>
```
Now, every time we include `<greet-user></greet-user>` in our view, AngularJS will expand it into a
DOM sub-tree constructed using the provided `template` and managed by an instance of the specified
controller.
But wait, where did that `$ctrl` come from and what does it refer to ?
For reasons already mentioned (and for other reasons that are out of the scope of this tutorial), it
is considered a good practice to avoid using the scope directly. We can (and should) use our
controller instance; i.e. assign our data and methods on properties of our controller (the "`this`"
inside the controller constructor), instead of directly to the scope.
From the template, we can refer to our controller instance using an alias. This way, the context of
evaluation for our expressions is even more clear. By default, components use `$ctrl` as the
controller alias, but we can override it, should the need arise.
There are more options available, so make sure you check out the
{@link ng.$compileProvider#component API Reference}, before using `.component()` in your own
applications.
## Using Components
Now that we know how to create components, let's refactor the HTML page to make use of our newly
acquired skill.
<br />
**`app/index.html`:**
```html
<html ng-app="phonecatApp">
<head>
...
<script src="lib/angular/angular.js"></script>
<script src="app.js"></script>
<script src="phone-list.component.js"></script>
</head>
<body>
<!-- Use a custom component to render a list of phones -->
<phone-list></phone-list> <!-- This tells AngularJS to instantiate a `phoneList` component here. -->
</body>
</html>
```
<br />
**`app/app.js`:**
```js
// Define the `phonecatApp` module
angular.module('phonecatApp', []);
```
<br />
**`app/phone-list.component.js`:**
```js
// Register `phoneList` component, along with its associated controller and template
angular.
module('phonecatApp').
component('phoneList', { // This name is what AngularJS uses to match to the `<phone-list>` element.
template:
'<ul>' +
'<li ng-repeat="phone in $ctrl.phones">' +
'<span>{{phone.name}}</span>' +
'<p>{{phone.snippet}}</p>' +
'</li>' +
'</ul>',
controller: function PhoneListController() {
this.phones = [
{
name: 'Nexus S',
snippet: 'Fast just got faster with Nexus S.'
}, {
name: 'Motorola XOOM™ with Wi-Fi',
snippet: 'The Next, Next Generation tablet.'
}, {
name: 'MOTOROLA XOOM™',
snippet: 'The Next, Next Generation tablet.'
}
];
}
});
```
Voilà! The resulting output should look the same, but let's see what we have gained:
* Our phone list is reusable. Just drop `<phone-list></phone-list>` anywhere in the page to get a
list of phones.
* Our main view (`index.html`) is cleaner and more declarative. Just by looking at it, we know there
is a list of phones. We are not bothered with implementation details.
* Our component is isolated and safe from "external influences". Likewise, we don't have to worry,
that we might accidentally break something in some other part of the application. What happens
inside our component, stays inside our component.
* It's easier to test our component in isolation.
<img class="diagram" src="img/tutorial/tutorial_03.png">
<div class="alert alert-info">
<p>**A note on file naming:**</p>
<p>
It is a good practice to distinguish different types of entities by suffix. In this tutorial, we
are using the `.component` suffix for components, so the definition of a `someComponent`
component would be in a file named `some-component.component.js`.
</p>
</div>
## Testing
Although we have combined our controller with a template into a component, we still can (and should)
unit test the controller separately, since this is where our application logic and data reside.
In order to retrieve and instantiate a component's controller, AngularJS provides the
{@link ngMock.$componentController $componentController} service.
<div class="alert alert-info">
The `$controller` service that we used in the previous step can only instantiate controllers that
were registered by name, using the `.controller()` method. We could have registered our component
controller this way, too, if we wanted to. Instead, we chose to define it inline — inside
the CDO — to keep things localized, but either way works equally well.
</div>
<br />
**`app/phone-list.component.spec.js`:**
```js
describe('phoneList', function() {
// Load the module that contains the `phoneList` component before each test
beforeEach(module('phonecatApp'));
// Test the controller
describe('PhoneListController', function() {
it('should create a `phones` model with 3 phones', inject(function($componentController) {
var ctrl = $componentController('phoneList');
expect(ctrl.phones.length).toBe(3);
}));
});
});
```
The test retrieves the controller associated with the `phoneList` component, instantiates it and
verifies that the phones array property on it contains three records. Note that the data is now on
the controller instance itself, not on a `scope`.
### Running Tests
Same as before, execute `npm test` to run the tests and then watch the files for changes.
## Experiments
<div></div>
* Try the experiments from the previous step, this time on the `phoneList` component.
* Add a couple more phone lists on the page, by just adding more `<phone-list></phone-list>`
elements in `index.html`. Now add another binding to the `phoneList` component's template:
```js
template:
'<p>Total number of phones: {{$ctrl.phones.length}}</p>' +
'<ul>' +
...
```
Reload the page and watch the new "feature" propagate to all phone lists. In real-world
applications, where the phone lists could appear on several different pages, being able to change
or add something in one place (e.g. a component's template) and have that change propagate
throughout the application, is a big win.
## Summary
You have learned how to organize your application and presentation logic into isolated, reusable
components. Let's go to {@link step_04 step 4} to learn how to organize our code in directories and
files, so it remains easy to locate as our application grows.
<ul doc-tutorial-nav="3"></ul>
[case-styles]: https://en.wikipedia.org/wiki/Letter_case#Special_case_styles
[jasmine-docs]: https://jasmine.github.io/api/3.3/global
[jasmine-home]: https://jasmine.github.io/
[karma]: https://karma-runner.github.io/
[mvc-pattern]: https://en.wikipedia.org/wiki/Model–View–Controller