Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit 2409212

Browse files
petebacondarwinpetebacondarwin
committed
docs(ngController): add formatting to controller as description and example
Adds to #7591
1 parent f1c7240 commit 2409212

File tree

1 file changed

+177
-162
lines changed

1 file changed

+177
-162
lines changed

‎src/ng/directive/ngController.js

+177-162
Original file line numberDiff line numberDiff line change
@@ -34,168 +34,183 @@
3434
* easily be called from the angular markup. Any changes to the data are automatically reflected
3535
* in the View without the need for a manual update.
3636
*
37-
* Two different declaration styles are included below: one which injects `scope` into the
38-
* controller, and another which instead binds methods and properties directly onto the controller
39-
* using `this`. The first option is more common in the Angular community, and is generally used
40-
* in boilerplates and in this guide. However, there are advantages to binding properties directly
41-
* to the controller and avoiding scope. Using `controller as` makes it obvious which controller
42-
* you are accessing in the template when multiple controllers apply to an element. Since there
43-
* is always a `.` in the bindings, you don't have to worry about prototypal inheritance masking
44-
* primitives.
45-
<example>
46-
<file name="index.html">
47-
<script>
48-
function SettingsController1() {
49-
this.name = "John Smith";
50-
this.contacts = [
51-
{type: 'phone', value: '408 555 1212'},
52-
{type: 'email', value: 'john.smith@example.org'} ];
53-
};
54-
55-
SettingsController1.prototype.greet = function() {
56-
alert(this.name);
57-
};
58-
59-
SettingsController1.prototype.addContact = function() {
60-
this.contacts.push({type: 'email', value: 'yourname@example.org'});
61-
};
62-
63-
SettingsController1.prototype.removeContact = function(contactToRemove) {
64-
var index = this.contacts.indexOf(contactToRemove);
65-
this.contacts.splice(index, 1);
66-
};
67-
68-
SettingsController1.prototype.clearContact = function(contact) {
69-
contact.type = 'phone';
70-
contact.value = '';
71-
};
72-
</script>
73-
<div id="ctrl-as-exmpl" ng-controller="SettingsController1 as settings">
74-
Name: <input type="text" ng-model="settings.name"/>
75-
[ <a href="" ng-click="settings.greet()">greet</a> ]<br/>
76-
Contact:
77-
<ul>
78-
<li ng-repeat="contact in settings.contacts">
79-
<select ng-model="contact.type">
80-
<option>phone</option>
81-
<option>email</option>
82-
</select>
83-
<input type="text" ng-model="contact.value"/>
84-
[ <a href="" ng-click="settings.clearContact(contact)">clear</a>
85-
| <a href="" ng-click="settings.removeContact(contact)">X</a> ]
86-
</li>
87-
<li>[ <a href="" ng-click="settings.addContact()">add</a> ]</li>
88-
</ul>
89-
</div>
90-
</file>
91-
<file name="protractor.js" type="protractor">
92-
it('should check controller as', function() {
93-
var container = element(by.id('ctrl-as-exmpl'));
94-
95-
expect(container.findElement(by.model('settings.name'))
96-
.getAttribute('value')).toBe('John Smith');
97-
98-
var firstRepeat =
99-
container.findElement(by.repeater('contact in settings.contacts').row(0));
100-
var secondRepeat =
101-
container.findElement(by.repeater('contact in settings.contacts').row(1));
102-
103-
expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
104-
.toBe('408 555 1212');
105-
expect(secondRepeat.findElement(by.model('contact.value')).getAttribute('value'))
106-
.toBe('john.smith@example.org');
107-
108-
firstRepeat.findElement(by.linkText('clear')).click();
109-
110-
expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
111-
.toBe('');
112-
113-
container.findElement(by.linkText('add')).click();
114-
115-
expect(container.findElement(by.repeater('contact in settings.contacts').row(2))
116-
.findElement(by.model('contact.value'))
117-
.getAttribute('value'))
118-
.toBe('[email protected]');
119-
});
120-
</file>
121-
</example>
122-
<example>
123-
<file name="index.html">
124-
<script>
125-
function SettingsController2($scope) {
126-
$scope.name = "John Smith";
127-
$scope.contacts = [
128-
{type:'phone', value:'408 555 1212'},
129-
{type:'email', value:'john.smith@example.org'} ];
130-
131-
$scope.greet = function() {
132-
alert($scope.name);
133-
};
134-
135-
$scope.addContact = function() {
136-
$scope.contacts.push({type:'email', value:'yourname@example.org'});
137-
};
138-
139-
$scope.removeContact = function(contactToRemove) {
140-
var index = $scope.contacts.indexOf(contactToRemove);
141-
$scope.contacts.splice(index, 1);
142-
};
143-
144-
$scope.clearContact = function(contact) {
145-
contact.type = 'phone';
146-
contact.value = '';
147-
};
148-
}
149-
</script>
150-
<div id="ctrl-exmpl" ng-controller="SettingsController2">
151-
Name: <input type="text" ng-model="name"/>
152-
[ <a href="" ng-click="greet()">greet</a> ]<br/>
153-
Contact:
154-
<ul>
155-
<li ng-repeat="contact in contacts">
156-
<select ng-model="contact.type">
157-
<option>phone</option>
158-
<option>email</option>
159-
</select>
160-
<input type="text" ng-model="contact.value"/>
161-
[ <a href="" ng-click="clearContact(contact)">clear</a>
162-
| <a href="" ng-click="removeContact(contact)">X</a> ]
163-
</li>
164-
<li>[ <a href="" ng-click="addContact()">add</a> ]</li>
165-
</ul>
166-
</div>
167-
</file>
168-
<file name="protractor.js" type="protractor">
169-
it('should check controller', function() {
170-
var container = element(by.id('ctrl-exmpl'));
171-
172-
expect(container.findElement(by.model('name'))
173-
.getAttribute('value')).toBe('John Smith');
174-
175-
var firstRepeat =
176-
container.findElement(by.repeater('contact in contacts').row(0));
177-
var secondRepeat =
178-
container.findElement(by.repeater('contact in contacts').row(1));
179-
180-
expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
181-
.toBe('408 555 1212');
182-
expect(secondRepeat.findElement(by.model('contact.value')).getAttribute('value'))
183-
.toBe('john.smith@example.org');
184-
185-
firstRepeat.findElement(by.linkText('clear')).click();
186-
187-
expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
188-
.toBe('');
189-
190-
container.findElement(by.linkText('add')).click();
191-
192-
expect(container.findElement(by.repeater('contact in contacts').row(2))
193-
.findElement(by.model('contact.value'))
194-
.getAttribute('value'))
195-
.toBe('[email protected]');
196-
});
197-
</file>
198-
</example>
37+
* Two different declaration styles are included below:
38+
*
39+
* * one binds methods and properties directly onto the controller using `this`:
40+
* `ng-controller="SettingsController1 as settings"`
41+
* * one injects `$scope` into the controller:
42+
* `ng-controller="SettingsController2"`
43+
*
44+
* The second option is more common in the Angular community, and is generally used in boilerplates
45+
* and in this guide. However, there are advantages to binding properties directly to the controller
46+
* and avoiding scope.
47+
*
48+
* * Using `controller as` makes it obvious which controller you are accessing in the template when
49+
* multiple controllers apply to an element.
50+
* * If you are writing your controllers as classes you have easier access to the properties and
51+
* methods, which will appear on the scope, from inside the controller code.
52+
* * Since there is always a `.` in the bindings, you don't have to worry about prototypal
53+
* inheritance masking primitives.
54+
*
55+
* This example demonstrates the `controller as` syntax.
56+
*
57+
* <example name="ngControllerAs">
58+
* <file name="index.html">
59+
* <div id="ctrl-as-exmpl" ng-controller="SettingsController1 as settings">
60+
* Name: <input type="text" ng-model="settings.name"/>
61+
* [ <a href="" ng-click="settings.greet()">greet</a> ]<br/>
62+
* Contact:
63+
* <ul>
64+
* <li ng-repeat="contact in settings.contacts">
65+
* <select ng-model="contact.type">
66+
* <option>phone</option>
67+
* <option>email</option>
68+
* </select>
69+
* <input type="text" ng-model="contact.value"/>
70+
* [ <a href="" ng-click="settings.clearContact(contact)">clear</a>
71+
* | <a href="" ng-click="settings.removeContact(contact)">X</a> ]
72+
* </li>
73+
* <li>[ <a href="" ng-click="settings.addContact()">add</a> ]</li>
74+
* </ul>
75+
* </div>
76+
* </file>
77+
* <file name="app.js">
78+
* function SettingsController1() {
79+
* this.name = "John Smith";
80+
* this.contacts = [
81+
* {type: 'phone', value: '408 555 1212'},
82+
* {type: 'email', value: 'john.smith@example.org'} ];
83+
* }
84+
*
85+
* SettingsController1.prototype.greet = function() {
86+
* alert(this.name);
87+
* };
88+
*
89+
* SettingsController1.prototype.addContact = function() {
90+
* this.contacts.push({type: 'email', value: 'yourname@example.org'});
91+
* };
92+
*
93+
* SettingsController1.prototype.removeContact = function(contactToRemove) {
94+
* var index = this.contacts.indexOf(contactToRemove);
95+
* this.contacts.splice(index, 1);
96+
* };
97+
*
98+
* SettingsController1.prototype.clearContact = function(contact) {
99+
* contact.type = 'phone';
100+
* contact.value = '';
101+
* };
102+
* </file>
103+
* <file name="protractor.js" type="protractor">
104+
* it('should check controller as', function() {
105+
* var container = element(by.id('ctrl-as-exmpl'));
106+
* expect(container.findElement(by.model('settings.name'))
107+
* .getAttribute('value')).toBe('John Smith');
108+
*
109+
* var firstRepeat =
110+
* container.findElement(by.repeater('contact in settings.contacts').row(0));
111+
* var secondRepeat =
112+
* container.findElement(by.repeater('contact in settings.contacts').row(1));
113+
*
114+
* expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
115+
* .toBe('408 555 1212');
116+
*
117+
* expect(secondRepeat.findElement(by.model('contact.value')).getAttribute('value'))
118+
* .toBe('john.smith@example.org');
119+
*
120+
* firstRepeat.findElement(by.linkText('clear')).click();
121+
*
122+
* expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
123+
* .toBe('');
124+
*
125+
* container.findElement(by.linkText('add')).click();
126+
*
127+
* expect(container.findElement(by.repeater('contact in settings.contacts').row(2))
128+
* .findElement(by.model('contact.value'))
129+
* .getAttribute('value'))
130+
* .toBe('[email protected]');
131+
* });
132+
* </file>
133+
* </example>
134+
*
135+
* This example demonstrates the "attach to `$scope`" style of controller.
136+
*
137+
* <example name="ngController">
138+
* <file name="index.html">
139+
* <div id="ctrl-exmpl" ng-controller="SettingsController2">
140+
* Name: <input type="text" ng-model="name"/>
141+
* [ <a href="" ng-click="greet()">greet</a> ]<br/>
142+
* Contact:
143+
* <ul>
144+
* <li ng-repeat="contact in contacts">
145+
* <select ng-model="contact.type">
146+
* <option>phone</option>
147+
* <option>email</option>
148+
* </select>
149+
* <input type="text" ng-model="contact.value"/>
150+
* [ <a href="" ng-click="clearContact(contact)">clear</a>
151+
* | <a href="" ng-click="removeContact(contact)">X</a> ]
152+
* </li>
153+
* <li>[ <a href="" ng-click="addContact()">add</a> ]</li>
154+
* </ul>
155+
* </div>
156+
* </file>
157+
* <file name="app.js">
158+
* function SettingsController2($scope) {
159+
* $scope.name = "John Smith";
160+
* $scope.contacts = [
161+
* {type:'phone', value:'408 555 1212'},
162+
* {type:'email', value:'john.smith@example.org'} ];
163+
*
164+
* $scope.greet = function() {
165+
* alert($scope.name);
166+
* };
167+
*
168+
* $scope.addContact = function() {
169+
* $scope.contacts.push({type:'email', value:'yourname@example.org'});
170+
* };
171+
*
172+
* $scope.removeContact = function(contactToRemove) {
173+
* var index = $scope.contacts.indexOf(contactToRemove);
174+
* $scope.contacts.splice(index, 1);
175+
* };
176+
*
177+
* $scope.clearContact = function(contact) {
178+
* contact.type = 'phone';
179+
* contact.value = '';
180+
* };
181+
* }
182+
* </file>
183+
* <file name="protractor.js" type="protractor">
184+
* it('should check controller', function() {
185+
* var container = element(by.id('ctrl-exmpl'));
186+
*
187+
* expect(container.findElement(by.model('name'))
188+
* .getAttribute('value')).toBe('John Smith');
189+
*
190+
* var firstRepeat =
191+
* container.findElement(by.repeater('contact in contacts').row(0));
192+
* var secondRepeat =
193+
* container.findElement(by.repeater('contact in contacts').row(1));
194+
*
195+
* expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
196+
* .toBe('408 555 1212');
197+
* expect(secondRepeat.findElement(by.model('contact.value')).getAttribute('value'))
198+
* .toBe('john.smith@example.org');
199+
*
200+
* firstRepeat.findElement(by.linkText('clear')).click();
201+
*
202+
* expect(firstRepeat.findElement(by.model('contact.value')).getAttribute('value'))
203+
* .toBe('');
204+
*
205+
* container.findElement(by.linkText('add')).click();
206+
*
207+
* expect(container.findElement(by.repeater('contact in contacts').row(2))
208+
* .findElement(by.model('contact.value'))
209+
* .getAttribute('value'))
210+
* .toBe('[email protected]');
211+
* });
212+
* </file>
213+
*</example>
199214
200215
*/
201216
var ngControllerDirective = [function() {

0 commit comments

Comments
 (0)