UI-Router

####Finally a de-facto solution to nested views and routing.

We recommend the latest beta 0.0.2 (Guide and Docs are already updated to 0.0.2): Build the Project Locally
Last release 0.0.1: Compressed / Uncompressed

Warning: UI-Router is in active development. The API is highly subject to change. It is not recommended to use this library on projects that require guaranteed stability.

Main Goal

To evolve the concept of an angularjs route into a more general concept of a state for managing complex application UI states.

Main Features

Robust State Management

$state and $stateProvider

More Powerful Views

ui-view directive (used in place of ng-view)

Nested Views

load templates that contain nested ui-views as deep as you'd like.

Routing

States can map to URLs (though it's not required)

Named Views

<div ui-view="chart">

Multiple Parallel Views

<div ui-view="chart1">
<div ui-view="chart2">

Basically, do whatever you want with states and routes.

Resources

Note: Quick Starts, Guide and API Ref are pre-updated for v0.0.2 release.

Quick Start

Setup

Get ui-router:

with bower: bower install angular-ui-router

fork this repo

download the latest release (compressed | uncompressed)

Add angular-ui-router.min.js to your index.html

<!doctype html>
<html ng-app="myapp">
<head>
      <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.0.6/angular.min.js"></script>
      <script src="angular-ui-router.min.js"></script> <!-- Insert after main angular.js file -->

Set ui.router as a dependency in your module. Note: Use ui.state if using v0.0.1.

var myapp = angular.module('myapp', ['ui.router'])

Nested States & Views

The great majority of ui-router's power is its ability to nest states & views.

Follow Setup instructions above.
Add a ui-view to your app.

<!-- index.html -->
<body>
    <div ui-view></div>
    <!-- Also a way to navigate -->
    <a href="#/route1">Route 1</a>
    <a href="#/route2">Route 2</a>
</body>

Add some templates. These will plug into the ui-view within index.html. Notice that they have their own ui-view as well! That is the key to nesting states and views.

<!-- route1.html -->
<h1>Route 1</h1>
<hr/>
<a href="#/route1/list">Show List</a>
<div ui-view></div>

<!-- route2.html -->
<h1>Route 2</h1>
<hr/>
<a href="#/route2/list">Show List</a>
<div ui-view></div>

Add some child templates. These will get plugged into the ui-view of their parent state templates.

<!-- route1.list.html -->
<h3>List of Route 1 Items</h3>
<ul>
  <li ng-repeat="item in items">{{item}}</li>
</ul>

<!-- route2.list.html -->
<h3>List of Route 2 Things</h3>
<ul>
  <li ng-repeat="thing in things">{{thing}}</li>
</ul>

Now let's wire it all up. Set up your states in the module config:

myapp.config(function($stateProvider, $urlRouterProvider){
      //
      // For any unmatched url, send to /route1
      $urlRouterProvider.otherwise("/route1") 
      //
      // Now set up the states
      $stateProvider
        .state('route1', {
            url: "/route1",
            templateUrl: "route1.html"
        })
          .state('route1.list', {
              url: "/list",
              templateUrl: "route1.list.html",
              controller: function($scope){
                $scope.items = ["A", "List", "Of", "Items"];
              }
          })          
        .state('route2', {
            url: "/route2",
            templateUrl: "route2.html"
        })
          .state('route2.list', {
              url: "/list",
              templateUrl: "route2.list.html",
              controller: function($scope){
                $scope.things = ["A", "Set", "Of", "Things"];
              }
          })
    })

See this quick start example in action.

Go to Quick Start Plunker for Nested States & Views

This only scratches the surface! You've only seen Nested Views.

Dive Deeper!

Multiple & Named Views

Another handy feature is the ability to have more than one view per template. Please note: 95% of the time Nested States & Views is the pattern you'll be looking for, opposed to using multiple views per template.

Follow Setup instructions above.
Add one or more ui-view to your app, give them names.

<!-- index.html -->
<body>
    <div ui-view="viewA"></div>
    <div ui-view="viewB"></div>
    <!-- Also a way to navigate -->
    <a href="#/route1">Route 1</a>
    <a href="#/route2">Route 2</a>
</body>

Set up your states in the module config:

myapp.config(function($stateProvider){
  $stateProvider
		.state('index', {
			url: "", // root route
			views: {
				"viewA": {
					templateUrl: "index.viewA.html"
				},
				"viewB": {
					templateUrl: "index.viewB.html"
				}
			}
		})
		.state('route1', {
			url: "/route1",
			views: {
				"viewA": {
					templateUrl: "route1.viewA.html"
				},
				"viewB": {
					templateUrl: "route1.viewB.html"
				}
			}
		})
		.state('route2', {
			url: "/route2",
			views: {
				"viewA": {
					templateUrl: "route2.viewA.html"
				},
				"viewB": {
					templateUrl: "route2.viewB.html"
				}
			}
		})
})

See this quick start example in action.

Go to Quick Start Plunker for Multiple & Named Views

This only scratches the surface! You've only seen Named Views and Parallel Views.

Dive Deeper!

Developing

UI-Router uses grunt >= 0.4.x make sure to upgrade your environment and read the Migration Guide.

Dependencies for building from source and running tests:

grunt-cli - run: $ npm install -g grunt-cli
Then install development dependencies with: $ npm install

There is a number of targets in the gruntfile that is used to building the solution, documents etc.

grunt: Perform a normal build, runs jshint and karma tests
grunt build: Perform a normal build
grunt dist: Perform a clean build and generate documentation
grunt dev: Run dev server (sample app) and watch for changes, builds and runs karma tests on changes.

chiefjester / ui-router