afm-client/bower_components/angular-ui-router/README.md

   1 # AngularUI Router &nbsp;[![Build Status](https://travis-ci.org/angular-ui/ui-router.svg?branch=master)](https://travis-ci.org/angular-ui/ui-router)
   2
   3 #### The de-facto solution to flexible routing with nested views
   4 ---
   5 **[Download 0.2.17](http://angular-ui.github.io/ui-router/release/angular-ui-router.js)** (or **[Minified](http://angular-ui.github.io/ui-router/release/angular-ui-router.min.js)**) **|**
   6 **[Guide](https://github.com/angular-ui/ui-router/wiki) |**
   7 **[API](http://angular-ui.github.io/ui-router/site) |**
   8 **[Sample](http://angular-ui.github.com/ui-router/sample/) ([Src](https://github.com/angular-ui/ui-router/tree/gh-pages/sample)) |**
   9 **[FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions) |**
  10 **[Resources](#resources) |**
  11 **[Report an Issue](https://github.com/angular-ui/ui-router/blob/master/CONTRIBUTING.md#report-an-issue) |**
  12 **[Contribute](https://github.com/angular-ui/ui-router/blob/master/CONTRIBUTING.md#contribute) |**
  13 **[Help!](http://stackoverflow.com/questions/ask?tags=angularjs,angular-ui-router) |**
  14 **[Discuss](https://groups.google.com/forum/#!categories/angular-ui/router)**
  15
  16 ---
  17
  18 AngularUI Router is a routing framework for [AngularJS](http://angularjs.org), which allows you to organize the
  19 parts of your interface into a [*state machine*](https://en.wikipedia.org/wiki/Finite-state_machine). Unlike the
  20 [`$route` service](http://docs.angularjs.org/api/ngRoute.$route) in the Angular ngRoute module, which is organized around URL
  21 routes, UI-Router is organized around [*states*](https://github.com/angular-ui/ui-router/wiki),
  22 which may optionally have routes, as well as other behavior, attached.
  23
  24 States are bound to *named*, *nested* and *parallel views*, allowing you to powerfully manage your application's interface.
  25
  26 Check out the sample app: http://angular-ui.github.io/ui-router/sample/
  27
  28 -
  29 **Note:** *UI-Router is under active development. As such, while this library is well-tested, the API may change. Consider using it in production applications only if you're comfortable following a changelog and updating your usage accordingly.*
  30
  31
  32 ## Get Started
  33
  34 **(1)** Get UI-Router in one of the following ways:
  35  - clone & [build](CONTRIBUTING.md#developing) this repository
  36  - [download the release](http://angular-ui.github.io/ui-router/release/angular-ui-router.js) (or [minified](http://angular-ui.github.io/ui-router/release/angular-ui-router.min.js))
  37  - [link to cdn](http://cdnjs.com/libraries/angular-ui-router)
  38  - via **[jspm](http://jspm.io/)**: by running `$ jspm install angular-ui-router` from your console
  39  - or via **[npm](https://www.npmjs.org/)**: by running `$ npm install angular-ui-router` from your console
  40  - or via **[Bower](http://bower.io/)**: by running `$ bower install angular-ui-router` from your console
  41  - or via **[Component](https://github.com/component/component)**: by running `$ component install angular-ui/ui-router` from your console
  42
  43 **(2)** Include `angular-ui-router.js` (or `angular-ui-router.min.js`) in your `index.html`, after including Angular itself (For Component users: ignore this step)
  44
  45 **(3)** Add `'ui.router'` to your main module's list of dependencies (For Component users: replace `'ui.router'` with `require('angular-ui-router')`)
  46
  47 When you're done, your setup should look similar to the following:
  48
  49 >
  50 ```html
  51 <!doctype html>
  52 <html ng-app="myApp">
  53 <head>
  54     <script src="//ajax.googleapis.com/ajax/libs/angularjs/1.1.5/angular.min.js"></script>
  55     <script src="js/angular-ui-router.min.js"></script>
  56     <script>
  57         var myApp = angular.module('myApp', ['ui.router']);
  58         // For Component users, it should look like this:
  59         // var myApp = angular.module('myApp', [require('angular-ui-router')]);
  60     </script>
  61     ...
  62 </head>
  63 <body>
  64     ...
  65 </body>
  66 </html>
  67 ```
  68
  69 ### [Nested States & Views](http://plnkr.co/edit/u18KQc?p=preview)
  70
  71 The majority of UI-Router's power is in its ability to nest states & views.
  72
  73 **(1)** First, follow the [setup](#get-started) instructions detailed above.
  74
  75 **(2)** Then, add a [`ui-view` directive](https://github.com/angular-ui/ui-router/wiki/Quick-Reference#ui-view) to the `<body />` of your app.
  76
  77 >
  78 ```html
  79 <!-- index.html -->
  80 <body>
  81     <div ui-view></div>
  82     <!-- We'll also add some navigation: -->
  83     <a ui-sref="state1">State 1</a>
  84     <a ui-sref="state2">State 2</a>
  85 </body>
  86 ```
  87
  88 **(3)** You'll notice we also added some links with [`ui-sref` directives](https://github.com/angular-ui/ui-router/wiki/Quick-Reference#ui-sref). In addition to managing state transitions, this directive auto-generates the `href` attribute of the `<a />` element it's attached to, if the corresponding state has a URL. Next we'll 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.
  89
  90 >
  91 ```html
  92 <!-- partials/state1.html -->
  93 <h1>State 1</h1>
  94 <hr/>
  95 <a ui-sref="state1.list">Show List</a>
  96 <div ui-view></div>
  97 ```
  98 ```html
  99 <!-- partials/state2.html -->
 100 <h1>State 2</h1>
 101 <hr/>
 102 <a ui-sref="state2.list">Show List</a>
 103 <div ui-view></div>
 104 ```
 105
 106 **(4)** Next, we'll add some child templates. *These* will get plugged into the `ui-view` of their parent state templates.
 107
 108 >
 109 ```html
 110 <!-- partials/state1.list.html -->
 111 <h3>List of State 1 Items</h3>
 112 <ul>
 113   <li ng-repeat="item in items">{{ item }}</li>
 114 </ul>
 115 ```
 116
 117 >
 118 ```html
 119 <!-- partials/state2.list.html -->
 120 <h3>List of State 2 Things</h3>
 121 <ul>
 122   <li ng-repeat="thing in things">{{ thing }}</li>
 123 </ul>
 124 ```
 125
 126 **(5)** Finally, we'll wire it all up with `$stateProvider`. Set up your states in the module config, as in the following:
 127
 128
 129 >
 130 ```javascript
 131 myApp.config(function($stateProvider, $urlRouterProvider) {
 132   //
 133   // For any unmatched url, redirect to /state1
 134   $urlRouterProvider.otherwise("/state1");
 135   //
 136   // Now set up the states
 137   $stateProvider
 138     .state('state1', {
 139       url: "/state1",
 140       templateUrl: "partials/state1.html"
 141     })
 142     .state('state1.list', {
 143       url: "/list",
 144       templateUrl: "partials/state1.list.html",
 145       controller: function($scope) {
 146         $scope.items = ["A", "List", "Of", "Items"];
 147       }
 148     })
 149     .state('state2', {
 150       url: "/state2",
 151       templateUrl: "partials/state2.html"
 152     })
 153     .state('state2.list', {
 154       url: "/list",
 155       templateUrl: "partials/state2.list.html",
 156       controller: function($scope) {
 157         $scope.things = ["A", "Set", "Of", "Things"];
 158       }
 159     });
 160 });
 161 ```
 162
 163 **(6)** See this quick start example in action.
 164 >**[Go to Quick Start Plunker for Nested States & Views](http://plnkr.co/edit/u18KQc?p=preview)**
 165
 166 **(7)** This only scratches the surface
 167 >**[Dive Deeper!](https://github.com/angular-ui/ui-router/wiki)**
 168
 169
 170 ### [Multiple & Named Views](http://plnkr.co/edit/SDOcGS?p=preview)
 171
 172 Another great feature is the ability to have multiple `ui-view`s view per template.
 173
 174 **Pro Tip:** *While multiple parallel views are a powerful feature, you'll often be able to manage your
 175 interfaces more effectively by nesting your views, and pairing those views with nested states.*
 176
 177 **(1)** Follow the [setup](#get-started) instructions detailed above.
 178
 179 **(2)** Add one or more `ui-view` to your app, give them names.
 180 >
 181 ```html
 182 <!-- index.html -->
 183 <body>
 184     <div ui-view="viewA"></div>
 185     <div ui-view="viewB"></div>
 186     <!-- Also a way to navigate -->
 187     <a ui-sref="route1">Route 1</a>
 188     <a ui-sref="route2">Route 2</a>
 189 </body>
 190 ```
 191
 192 **(3)** Set up your states in the module config:
 193 >
 194 ```javascript
 195 myApp.config(function($stateProvider) {
 196   $stateProvider
 197     .state('index', {
 198       url: "",
 199       views: {
 200         "viewA": { template: "index.viewA" },
 201         "viewB": { template: "index.viewB" }
 202       }
 203     })
 204     .state('route1', {
 205       url: "/route1",
 206       views: {
 207         "viewA": { template: "route1.viewA" },
 208         "viewB": { template: "route1.viewB" }
 209       }
 210     })
 211     .state('route2', {
 212       url: "/route2",
 213       views: {
 214         "viewA": { template: "route2.viewA" },
 215         "viewB": { template: "route2.viewB" }
 216       }
 217     })
 218 });
 219 ```
 220
 221 **(4)** See this quick start example in action.
 222 >**[Go to Quick Start Plunker for Multiple & Named Views](http://plnkr.co/edit/SDOcGS?p=preview)**
 223
 224
 225 ## Resources
 226
 227 * [In-Depth Guide](https://github.com/angular-ui/ui-router/wiki)
 228 * [API Reference](http://angular-ui.github.io/ui-router/site)
 229 * [Sample App](http://angular-ui.github.com/ui-router/sample/) ([Source](https://github.com/angular-ui/ui-router/tree/gh-pages/sample))
 230 * [FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions)
 231 * [Slides comparing ngRoute to ui-router](http://slid.es/timkindberg/ui-router#/)
 232 * [UI-Router Extras / Addons](http://christopherthielen.github.io/ui-router-extras/#/home) (@christopherthielen)
 233
 234 ### Videos
 235
 236 * [Introduction Video](https://egghead.io/lessons/angularjs-introduction-ui-router) (egghead.io)
 237 * [Tim Kindberg on Angular UI-Router](https://www.youtube.com/watch?v=lBqiZSemrqg)
 238 * [Activating States](https://egghead.io/lessons/angularjs-ui-router-activating-states) (egghead.io)
 239 * [Learn Angular.js using UI-Router](http://youtu.be/QETUuZ27N0w) (LearnCode.academy)
 240
 241
 242
 243 ## Reporting issues and Contributing
 244
 245 Please read our [Contributor guidelines](CONTRIBUTING.md) before reporting an issue or creating a pull request.