diff --git a/src/loader.js b/src/loader.js index febead684002..62f13013e7fa 100644 --- a/src/loader.js +++ b/src/loader.js @@ -333,6 +333,7 @@ function setupModuleLoader(window) { * In order to make the definition easier, components enforce best practices like controllerAs * and default behaviors like scope isolation, restrict to elements and allow transclusion. * + *
* Here are a few examples of how you would usually define components: * * ```js @@ -357,7 +358,49 @@ function setupModuleLoader(window) { * * ``` * - * See {@link ng.$compileProvider#directive $compileProvider.directive()}. + *
+ * Components are also useful as route templates (e.g. when using + * {@link ngRoute ngRoute}): + * + * ```js + * var myMod = angular.module('myMod', ['ngRoute']); + * + * myMod.component('home', { + * template: '

Home

Hello, {{ home.user.name }} !

', + * controller: function() { + * this.user = {name: 'world'}; + * } + * }); + * + * myMod.config(function($routeProvider) { + * $routeProvider.when('/', { + * template: '' + * }); + * }); + * ``` + * + *
+ * When using {@link ngRoute.$routeProvider $routeProvider}, you can often avoid some + * boilerplate, by assigning the resolved dependencies directly on the route scope: + * + * ```js + * var myMod = angular.module('myMod', ['ngRoute']); + * + * myMod.component('home', { + * template: '

Home

Hello, {{ home.user.name }} !

', + * bindings: {user: '='} + * }); + * + * myMod.config(function($routeProvider) { + * $routeProvider.when('/', { + * template: '', + * resolve: {user: function($http) { return $http.get('...'); }} + * }); + * }); + * ``` + * + *
+ * See also {@link ng.$compileProvider#directive $compileProvider.directive()}. */ component: function(name, options) { function factory($injector) { diff --git a/src/ngRoute/route.js b/src/ngRoute/route.js index 1842948b1737..e47b53e3eca1 100644 --- a/src/ngRoute/route.js +++ b/src/ngRoute/route.js @@ -100,8 +100,17 @@ function $RouteProvider() { * If all the promises are resolved successfully, the values of the resolved promises are * injected and {@link ngRoute.$route#$routeChangeSuccess $routeChangeSuccess} event is * fired. If any of the promises are rejected the - * {@link ngRoute.$route#$routeChangeError $routeChangeError} event is fired. The map object - * is: + * {@link ngRoute.$route#$routeChangeError $routeChangeError} event is fired. + * For easier access to the resolved dependencies from the template, the `resolve` map will + * be available on the scope of the route, under `$resolve` (by default) or a custom name + * specified by the `resolveAs` property (see below). This can be particularly useful, when + * working with {@link angular.Module#component components} as route templates.
+ *
+ * **Note:** If your scope already contains a property with this name, it will be hidden + * or overwritten. Make sure, you specify an appropriate name for this property, that + * does not collide with other properties on the scope. + *
+ * The map object is: * * - `key` – `{string}`: a name of a dependency to be injected into the controller. * - `factory` - `{string|function}`: If `string` then it is an alias for a service. @@ -111,7 +120,10 @@ function $RouteProvider() { * `ngRoute.$routeParams` will still refer to the previous route within these resolve * functions. Use `$route.current.params` to access the new route parameters, instead. * - * - `redirectTo` – {(string|function())=} – value to update + * - `resolveAs` - `{string=}` - The name under which the `resolve` map will be available on + * the scope of the route. If omitted, defaults to `$resolve`. + * + * - `redirectTo` – `{(string|function())=}` – value to update * {@link ng.$location $location} path with and trigger route redirection. * * If `redirectTo` is a function, it will be called with the following parameters: @@ -124,13 +136,13 @@ function $RouteProvider() { * The custom `redirectTo` function is expected to return a string which will be used * to update `$location.path()` and `$location.search()`. * - * - `[reloadOnSearch=true]` - {boolean=} - reload route when only `$location.search()` + * - `[reloadOnSearch=true]` - `{boolean=}` - reload route when only `$location.search()` * or `$location.hash()` changes. * * If the option is set to `false` and url in the browser changes, then * `$routeUpdate` event is broadcasted on the root scope. * - * - `[caseInsensitiveMatch=false]` - {boolean=} - match routes without being case sensitive + * - `[caseInsensitiveMatch=false]` - `{boolean=}` - match routes without being case sensitive * * If the option is set to `true`, then the particular route can be matched without being * case sensitive @@ -260,7 +272,7 @@ function $RouteProvider() { * @property {Object} current Reference to the current route definition. * The route definition contains: * - * - `controller`: The controller constructor as define in route definition. + * - `controller`: The controller constructor as defined in the route definition. * - `locals`: A map of locals which is used by {@link ng.$controller $controller} service for * controller instantiation. The `locals` contain * the resolved values of the `resolve` map. Additionally the `locals` also contain: @@ -268,6 +280,10 @@ function $RouteProvider() { * - `$scope` - The current route scope. * - `$template` - The current route template HTML. * + * The `locals` will be assigned to the route scope's `$resolve` property. You can override + * the property name, using `resolveAs` in the route definition. See + * {@link ngRoute.$routeProvider $routeProvider} for more info. + * * @property {Object} routes Object with all route configuration Objects as its properties. * * @description