# `when` ( service in module `ng` )

## Description

Adds a new route definition to the `$route` service.

## Parameters

- `path – {string} –`

  Route path (matched against `$location.path` ). If `$location.path` contains redundant trailing slash or is missing one, the route will still match and the `$location.path` will be updated to add or drop the trailing slash to exactly match the route definition.

  - `path` can contain named groups starting with a colon ( `:name` ). All characters up to the next slash are matched and stored in `$routeParams` under the given `name` when the route matches.
  - `path` can contain named groups starting with a star ( `*name` ). All characters are eagerly stored in `$routeParams` under the given `name` when the route matches.

  For example, routes like `/color/:color/largecode/*largecode/edit` will match `/color/brown/largecode/code/with/slashs/edit` and extract:

  - `color: brown`
  - `largecode: code/with/slashs` .
- `route – {Object} –`

  Mapping information to be assigned to `$route.current` on route match.

  Object properties:

  - `controller` – `{(string|function()=}` – Controller fn that should be associated with newly created scope or the name of a `registered controller` if passed as a string.
  - `controllerAs` – `{string=}` – A controller alias name. If present the controller will be published to scope under the `controllerAs` name.
  - `template` – `{string=|function()=}` – html template as a string or function that returns an html template as a string which should be used by `ngView` or `ngInclude` directives. This property takes precedence over `templateUrl` .

    If `template` is a function, it will be called with the following parameters:

    - `{Array.
      ` - route parameters extracted from the current `$location.path()` by applying the current route
  - `templateUrl` – `{string=|function()=}` – path or function that returns a path to an html template that should be used by `ngView`.

    If `templateUrl` is a function, it will be called with the following parameters:

    - `{Array.
      ` - route parameters extracted from the current `$location.path()` by applying the current route
  - `resolve` - `{Object.=}` - An optional map of dependencies which should be injected into the controller. If any of these dependencies are promises, they will be resolved and converted to a value before the controller is instantiated and the `$routeChangeSuccess` event is fired. 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. Otherwise if function, then it is `injected` and the return value is treated as the dependency. If the result is a promise, it is resolved before its value is injected into the controller.
  - `redirectTo` – {(string|function())=} – value to update `$location` path with and trigger route redirection.

    If `redirectTo` is a function, it will be called with the following parameters:

    - `{Object.}` - route parameters extracted from the current `$location.path()` by applying the current route templateUrl.
    - `{string}` - current `$location.path()`
    - `{Object}` - current `$location.search()`

    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() 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

    If the option is set to `true` , then the particular route can be matched without being case sensitive

## Returns

`{Object}` –

self