# angular.service.$route

Work in Progress This page is currently being revised. It might be incomplete or contain inaccuracies.

## Description

Watches `$location.hashPath` and tries to map the hash to an existing route definition. It is used for deep-linking URLs to controllers and views (HTML partials).

The `$route` service is typically used in conjunction with `ng:view` widget.

## Dependencies

- `$location`

## Methods

- ### onChange(fn)

  Register a handler function that will be called when route changes

  #### Parameters

  - `fn – {function()} –`

    Function that will be called when `$route.current` changes.

  #### Returns

  `{function()}` –

  The registered function.

- ### otherwise(params)

  Sets route definition that will be used on route change when no other route definition is matched.

  #### Parameters

  - `params – {Object} –`

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

- ### parent(scope)

  Sets a scope to be used as the parent scope for scopes created on route change. If not set, defaults to the root scope.

  #### Parameters

  - `scope – {Scope} –`

    Scope to be used as parent for newly created `$route.current.scope` scopes.

- ### reload()

  Causes `$route` service to reload (and recreate the `$route.current` scope) upon the next eval even if `$location` hasn't changed.

- ### when(path, params)

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

  #### Parameters

  - `path – {string} –`

    Route path (matched against `$location.hash`)

  - `params – {Object} –`

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

    Object properties:

    - `controller` â `{function()=}` â Controller fn that should be associated with newly created scope.
    - `template` â `{string=}` â path to an html template that should be used by `ng:view` or `ng:include` widgets.

    - `redirectTo` â {(string|function())=} â value to update `$location` hash with and trigger route redirection.

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

      - `{Object.<string>}` - route parameters extracted from the current `$location.hashPath` by applying the current route template.
      - `{string}` - current `$location.hash`
      - `{string}` - current `$location.hashPath`
      - `{string}` - current `$location.hashSearch`

      The custom `redirectTo` function is expected to return a string which will be used to update `$location.hash`.

  #### Returns

  `{Object}` –

  route object

## Properties

- ### current

  Reference to the current route definition.

- ### routes

  Array of all configured routes.

## Example

This example shows how changing the URL hash causes the `$route` to match a route against the URL, and the `[[ng:include]]` pulls in the partial. Try changing the URL in the input box to see changes.

         <script>
           function MainCntl($route, $location) {
             this.$route = $route;
             this.$location = $location;

             $route.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
             $route.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
             $route.onChange(function() {
               $route.current.scope.params = $route.current.params;
             });
           }

           function BookCntl() {
             this.name = "BookCntl";
           }

           function ChapterCntl() {
             this.name = "ChapterCntl";
           }
         </script>

         <div ng:controller="MainCntl">
           Choose:
           <a href="#/Book/Moby">Moby</a> |
           <a href="#/Book/Moby/ch/1">Moby: Ch1</a> |
           <a href="#/Book/Gatsby">Gatsby</a> |
           <a href="#/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a><br/>
           $location.hashPath: <input type="text" name="$location.hashPath" size="80" />
           <pre>$route.current.template = {{$route.current.template}}</pre>
           <pre>$route.current.params = {{$route.current.params}}</pre>
           <pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
           <hr />
           <ng:view></ng:view>
         </div>