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

Commit b49ddf9

Browse files
vojtajinavojtajina
committed
docs($route, ng:view): Fix the examples to work on jsfiddle, update docs
1 parent 1084ccf commit b49ddf9

File tree

2 files changed

+182
-129
lines changed

2 files changed

+182
-129
lines changed

Diff for: ‎src/service/route.js

+115-83
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,22 @@
11
'use strict';
22

3+
34
/**
45
* @ngdoc object
5-
* @name angular.module.ng.$route
6-
* @requires $location
7-
* @requires $routeParams
8-
*
9-
* @property {Object} current Reference to the current route definition.
10-
* @property {Array.<Object>} routes Array of all configured routes.
6+
* @name angular.module.ng.$routeProvider
7+
* @function
118
*
129
* @description
13-
* Watches `$location.url()` and tries to map the path to an existing route
14-
* definition. It is used for deep-linking URLs to controllers and views (HTML partials).
15-
*
16-
* The `$route` service is typically used in conjunction with {@link angular.module.ng.$compileProvider.directive.ng:view ng:view}
17-
* widget and the {@link angular.module.ng.$routeParams $routeParams} service.
1810
*
19-
* @example
20-
This example shows how changing the URL hash causes the <tt>$route</tt>
21-
to match a route against the URL, and the <tt>[[ng:include]]</tt> pulls in the partial.
22-
23-
<doc:example>
24-
<doc:source jsfiddle="false">
25-
<script>
26-
function MainCntl($route, $routeParams, $location) {
27-
this.$route = $route;
28-
this.$location = $location;
29-
this.$routeParams = $routeParams;
30-
31-
$route.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
32-
$route.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
33-
}
34-
35-
function BookCntl($routeParams) {
36-
this.name = "BookCntl";
37-
this.params = $routeParams;
38-
}
39-
40-
function ChapterCntl($routeParams) {
41-
this.name = "ChapterCntl";
42-
this.params = $routeParams;
43-
}
44-
</script>
45-
46-
<div ng:controller="MainCntl">
47-
Choose:
48-
<a href="#/Book/Moby">Moby</a> |
49-
<a href="#/Book/Moby/ch/1">Moby: Ch1</a> |
50-
<a href="#/Book/Gatsby">Gatsby</a> |
51-
<a href="#/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a><br/>
52-
<pre>$location.path() = {{$location.path()}}</pre>
53-
<pre>$route.current.template = {{$route.current.template}}</pre>
54-
<pre>$route.current.params = {{$route.current.params}}</pre>
55-
<pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
56-
<pre>$routeParams = {{$routeParams}}</pre>
57-
<hr />
58-
<ng:view></ng:view>
59-
</div>
60-
</doc:source>
61-
<doc:scenario>
62-
</doc:scenario>
63-
</doc:example>
11+
* Used for configuring routes. See {@link angular.module.ng.$route $route} for an example.
6412
*/
6513
function $RouteProvider(){
6614
var routes = {};
6715

6816
/**
6917
* @ngdoc method
70-
* @name angular.module.ng.$route#when
71-
* @methodOf angular.module.ng.$route
18+
* @name angular.module.ng.$routeProvider#when
19+
* @methodOf angular.module.ng.$routeProvider
7220
*
7321
* @param {string} path Route path (matched against `$location.hash`)
7422
* @param {Object} route Mapping information to be assigned to `$route.current` on route
@@ -97,15 +45,8 @@ function $RouteProvider(){
9745
* - `[reloadOnSearch=true]` - {boolean=} - reload route when only $location.search()
9846
* changes.
9947
*
100-
* If the option is set to false and url in the browser changes, then
101-
* $routeUpdate event is emited on the current route scope. You can use this event to
102-
* react to {@link angular.module.ng.$routeParams} changes:
103-
*
104-
* function MyCtrl($route, $routeParams) {
105-
* this.$on('$routeUpdate', function() {
106-
* // do stuff with $routeParams
107-
* });
108-
* }
48+
* If the option is set to `false` and url in the browser changes, then
49+
* `$routeUpdate` event is broadcasted on the root scope.
10950
*
11051
* @returns {Object} route object
11152
*
@@ -121,8 +62,8 @@ function $RouteProvider(){
12162

12263
/**
12364
* @ngdoc method
124-
* @name angular.module.ng.$route#otherwise
125-
* @methodOf angular.module.ng.$route
65+
* @name angular.module.ng.$routeProvider#otherwise
66+
* @methodOf angular.module.ng.$routeProvider
12667
*
12768
* @description
12869
* Sets route definition that will be used on route change when no other route definition
@@ -137,6 +78,106 @@ function $RouteProvider(){
13778

13879
this.$get = ['$rootScope', '$location', '$routeParams',
13980
function( $rootScope, $location, $routeParams) {
81+
82+
/**
83+
* @ngdoc object
84+
* @name angular.module.ng.$route
85+
* @requires $location
86+
* @requires $routeParams
87+
*
88+
* @property {Object} current Reference to the current route definition.
89+
* @property {Array.<Object>} routes Array of all configured routes.
90+
*
91+
* @description
92+
* Is used for deep-linking URLs to controllers and views (HTML partials).
93+
* It watches `$location.url()` and tries to map the path to an existing route definition.
94+
*
95+
* You can define routes through {@link angular.module.ng.$routeProvider $routeProvider}'s API.
96+
*
97+
* The `$route` service is typically used in conjunction with {@link angular.module.ng.$compileProvider.directive.ng:view ng:view}
98+
* directive and the {@link angular.module.ng.$routeParams $routeParams} service.
99+
*
100+
* @example
101+
This example shows how changing the URL hash causes the `$route` to match a route against the
102+
URL, and the `ng:view` pulls in the partial.
103+
104+
Note that this example is using {@link angular.module.ng.$compileProvide.directive.script inlined templates}
105+
to get it working on jsfiddle as well.
106+
107+
<doc:example module="route">
108+
<doc:source>
109+
<script type="text/ng-template" id="examples/book.html">
110+
controller: {{name}}<br />
111+
Book Id: {{params.bookId}}<br />
112+
</script>
113+
114+
<script type="text/ng-template" id="examples/chapter.html">
115+
controller: {{name}}<br />
116+
Book Id: {{params.bookId}}<br />
117+
Chapter Id: {{params.chapterId}}
118+
</script>
119+
120+
<script>
121+
angular.module('route', [], function($routeProvider, $locationProvider) {
122+
$routeProvider.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
123+
$routeProvider.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
124+
125+
// configure html5 to get links working on jsfiddle
126+
$locationProvider.html5Mode(true);
127+
});
128+
129+
function MainCntl($scope, $route, $routeParams, $location) {
130+
$scope.$route = $route;
131+
$scope.$location = $location;
132+
$scope.$routeParams = $routeParams;
133+
}
134+
135+
function BookCntl($scope, $routeParams) {
136+
$scope.name = "BookCntl";
137+
$scope.params = $routeParams;
138+
}
139+
140+
function ChapterCntl($scope, $routeParams) {
141+
$scope.name = "ChapterCntl";
142+
$scope.params = $routeParams;
143+
}
144+
</script>
145+
146+
<div ng:controller="MainCntl">
147+
Choose:
148+
<a href="/Book/Moby">Moby</a> |
149+
<a href="/Book/Moby/ch/1">Moby: Ch1</a> |
150+
<a href="/Book/Gatsby">Gatsby</a> |
151+
<a href="/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a> |
152+
<a href="/Book/Scarlet">Scarlet Letter</a><br/>
153+
154+
<ng:view></ng:view>
155+
<hr />
156+
157+
<pre>$location.path() = {{$location.path()}}</pre>
158+
<pre>$route.current.template = {{$route.current.template}}</pre>
159+
<pre>$route.current.params = {{$route.current.params}}</pre>
160+
<pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
161+
<pre>$routeParams = {{$routeParams}}</pre>
162+
</div>
163+
</doc:source>
164+
<doc:scenario>
165+
it('should load and compile correct template', function() {
166+
element('a:contains("Moby: Ch1")').click();
167+
var content = element('.doc-example-live ng\\:view').text();
168+
expect(content).toMatch(/controller\: ChapterCntl/);
169+
expect(content).toMatch(/Book Id\: Moby/);
170+
expect(content).toMatch(/Chapter Id\: 1/);
171+
172+
element('a:contains("Scarlet")').click();
173+
content = element('.doc-example-live ng\\:view').text();
174+
expect(content).toMatch(/controller\: BookCntl/);
175+
expect(content).toMatch(/Book Id\: Scarlet/);
176+
});
177+
</doc:scenario>
178+
</doc:example>
179+
*/
180+
140181
/**
141182
* @ngdoc event
142183
* @name angular.module.ng.$route#$beforeRouteChange
@@ -147,12 +188,6 @@ function $RouteProvider(){
147188
*
148189
* @param {Route} next Future route information.
149190
* @param {Route} current Current route information.
150-
*
151-
* The `Route` object extends the route definition with the following properties.
152-
*
153-
* * `scope` - The instance of the route controller.
154-
* * `params` - The current {@link angular.module.ng.$routeParams params}.
155-
*
156191
*/
157192

158193
/**
@@ -165,12 +200,6 @@ function $RouteProvider(){
165200
*
166201
* @param {Route} current Current route information.
167202
* @param {Route} previous Previous route information.
168-
*
169-
* The `Route` object extends the route definition with the following properties.
170-
*
171-
* * `scope` - The instance of the route controller.
172-
* * `params` - The current {@link angular.module.ng.$routeParams params}.
173-
*
174203
*/
175204

176205
/**
@@ -196,8 +225,11 @@ function $RouteProvider(){
196225
* @methodOf angular.module.ng.$route
197226
*
198227
* @description
199-
* Causes `$route` service to reload (and recreate the `$route.current` scope) upon the next
200-
* eval even if {@link angular.module.ng.$location $location} hasn't changed.
228+
* Causes `$route` service to reload the current route even if
229+
* {@link angular.module.ng.$location $location} hasn't changed.
230+
*
231+
* As a result of that, {@link angular.module.ng.$compileProvider.directive.ng:view ng:view}
232+
* creates new scope, reinstantiates the controller.
201233
*/
202234
reload: function() {
203235
dirty++;

Diff for: ‎src/widgets.js

+67-46
Original file line numberDiff line numberDiff line change
@@ -475,61 +475,82 @@ var ngNonBindableDirective = valueFn({ terminal: true });
475475
*
476476
* @description
477477
* # Overview
478-
* `ng:view` is a widget that complements the {@link angular.module.ng.$route $route} service by
478+
* `ng:view` is a directive that complements the {@link angular.module.ng.$route $route} service by
479479
* including the rendered template of the current route into the main layout (`index.html`) file.
480480
* Every time the current route changes, the included view changes with it according to the
481481
* configuration of the `$route` service.
482482
*
483-
* This widget provides functionality similar to {@link angular.module.ng.$compileProvider.directive.ng:include ng:include} when
484-
* used like this:
485-
*
486-
* <ng:include src="$route.current.template" scope="$route.current.scope"></ng:include>
487-
*
488-
*
489-
* # Advantages
490-
* Compared to `ng:include`, `ng:view` offers these advantages:
491-
*
492-
* - shorter syntax
493-
* - more efficient execution
494-
* - doesn't require `$route` service to be available on the root scope
495-
*
496483
*
497484
* @example
498485
<doc:example module="ngView">
499-
<doc:source jsfiddle="false">
500-
<script>
501-
function BootstrapCtrl() {}
502-
function OverviewCtrl() {}
503-
504-
angular.module('ngView', [])
505-
.config(function($routeProvider) {
506-
$routeProvider.when('/overview',
507-
{ controller: OverviewCtrl,
508-
template: 'partials/guide/dev_guide.overview.html'});
509-
$routeProvider.when('/bootstrap',
510-
{ controller: BootstrapCtrl,
511-
template: 'partials/guide/dev_guide.bootstrap.auto_bootstrap.html'});
512-
});
513-
</script>
514-
<div>
515-
<a href="overview">overview</a> |
516-
<a href="bootstrap">bootstrap</a> |
517-
<a href="undefined">undefined</a>
518-
519-
<br/>
520-
521-
The view is included below:
522-
<hr/>
523-
<ng:view></ng:view>
524-
</div>
486+
<doc:source>
487+
<script type="text/ng-template" id="examples/book.html">
488+
controller: {{name}}<br />
489+
Book Id: {{params.bookId}}<br />
490+
</script>
491+
492+
<script type="text/ng-template" id="examples/chapter.html">
493+
controller: {{name}}<br />
494+
Book Id: {{params.bookId}}<br />
495+
Chapter Id: {{params.chapterId}}
496+
</script>
497+
498+
<script>
499+
angular.module('ngView', [], function($routeProvider, $locationProvider) {
500+
$routeProvider.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
501+
$routeProvider.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
502+
503+
// configure html5 to get links working on jsfiddle
504+
$locationProvider.html5Mode(true);
505+
});
506+
507+
function MainCntl($scope, $route, $routeParams, $location) {
508+
$scope.$route = $route;
509+
$scope.$location = $location;
510+
$scope.$routeParams = $routeParams;
511+
}
512+
513+
function BookCntl($scope, $routeParams) {
514+
$scope.name = "BookCntl";
515+
$scope.params = $routeParams;
516+
}
517+
518+
function ChapterCntl($scope, $routeParams) {
519+
$scope.name = "ChapterCntl";
520+
$scope.params = $routeParams;
521+
}
522+
</script>
523+
524+
<div ng:controller="MainCntl">
525+
Choose:
526+
<a href="/Book/Moby">Moby</a> |
527+
<a href="/Book/Moby/ch/1">Moby: Ch1</a> |
528+
<a href="/Book/Gatsby">Gatsby</a> |
529+
<a href="/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a> |
530+
<a href="/Book/Scarlet">Scarlet Letter</a><br/>
531+
532+
<ng:view></ng:view>
533+
<hr />
534+
535+
<pre>$location.path() = {{$location.path()}}</pre>
536+
<pre>$route.current.template = {{$route.current.template}}</pre>
537+
<pre>$route.current.params = {{$route.current.params}}</pre>
538+
<pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
539+
<pre>$routeParams = {{$routeParams}}</pre>
540+
</div>
525541
</doc:source>
526542
<doc:scenario>
527-
it('should load templates', function() {
528-
element('.doc-example-live a:contains(overview)').click();
529-
expect(element('.doc-example-live ng\\:view').text()).toMatch(/Developer Guide: Overview/);
530-
531-
element('.doc-example-live a:contains(bootstrap)').click();
532-
expect(element('.doc-example-live ng\\:view').text()).toMatch(/Developer Guide: Initializing Angular: Automatic Initialization/);
543+
it('should load and compile correct template', function() {
544+
element('a:contains("Moby: Ch1")').click();
545+
var content = element('.doc-example-live ng\\:view').text();
546+
expect(content).toMatch(/controller\: ChapterCntl/);
547+
expect(content).toMatch(/Book Id\: Moby/);
548+
expect(content).toMatch(/Chapter Id\: 1/);
549+
550+
element('a:contains("Scarlet")').click();
551+
content = element('.doc-example-live ng\\:view').text();
552+
expect(content).toMatch(/controller\: BookCntl/);
553+
expect(content).toMatch(/Book Id\: Scarlet/);
533554
});
534555
</doc:scenario>
535556
</doc:example>

0 commit comments

Comments
 (0)