diff --git a/README.md b/README.md index 7bc7a6e68..a1a5ce411 100644 --- a/README.md +++ b/README.md @@ -1,175 +1,171 @@ -[![Build Status](https://travis-ci.org/angular-ui/ui-router.png?branch=master)](https://travis-ci.org/angular-ui/ui-router) +# AngularUI Router  [![Build Status](https://travis-ci.org/angular-ui/ui-router.png?branch=master)](https://travis-ci.org/angular-ui/ui-router) -# UI-Router +#### The de-facto solution to flexible routing with nested views +--- +**[Download 0.2.0](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)**) **|** +**[Learn](#resources) |** +**[Discuss](https://groups.google.com/forum/#!categories/angular-ui/router) |** +**[Get Help](http://stackoverflow.com/questions/ask?tags=angularjs,angular-ui-router) |** +**[Report an Issue](#report-an-issue) |** +**[Contribute](#contribute)** -####Finally a de-facto solution to nested views and routing. -* Last release 0.2.0: [Compressed](http://angular-ui.github.io/ui-router/release/angular-ui-router.min.js) / [Uncompressed](http://angular-ui.github.io/ui-router/release/angular-ui-router.js) +--- +AngularUI Router is a routing framework for [AngularJS](http://angularjs.org), which allows you to organize the +parts of your interface into a [*state machine*](https://en.wikipedia.org/wiki/Finite-state_machine). Unlike the +[`$route` service](http://docs.angularjs.org/api/ngRoute.$route) in Angular core, which is organized around URL +routes, UI-Router is organized around [*states*](https://github.com/angular-ui/ui-router/blob/master/sample/states.js#L28-L269), +which may optionally have routes, as well as other behavior, attached. -**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. +States are bound to *named*, *nested* and *parallel views*, allowing you to powerfully manage your application's interface. -## Main Goal -To evolve the concept of an [angularjs](http://angularjs.org/) [***route***](http://docs.angularjs.org/api/ng.$routeProvider) into a more general concept of a ***state*** for managing complex application UI states. +- +**Warning:** *UI-Router is pre-beta and under active development. As such, while this library is well-tested, the API is subject +to change. Using it in a project that requires guaranteed stability is not recommended.* -## Main Features -1. **Robust State Management** ->`$state` and `$stateProvider` -2. **More Powerful Views** ->`ui-view` directive (used in place of `ng-view`) +## Get Started -3. **Nested Views** ->load templates that contain nested `ui-view`s as deep as you'd like. +**(1)** Get UI-Router in one of 3 ways: + - clone & [build](#developing) this repository + - [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)) + - or via **[Bower](http://bower.io/)**: by running `$ bower install angular-ui-router` from your console -4. **Routing** ->States can map to URLs (though it's not required) +**(2)** Include `angular-ui-router.js` (or `angular-ui-router.min.js`) in your `index.html`, after including Angular itself -5. **Named Views** ->`
` +**(3)** Add `'ui.router'` to your main module's list of dependencies -6. **Multiple Parallel Views** -> -``` -
-
-``` - - -*Basically, do whatever you want with states and routes.* - - -## Resources - -* [In-Depth Overview](https://github.com/angular-ui/ui-router/wiki) -* [API Quick Reference](https://github.com/angular-ui/ui-router/wiki/Quick-Reference) -* [Sample App](http://angular-ui.github.com/ui-router/sample/) ([Source](https://github.com/angular-ui/ui-router/tree/master/sample)) -* [FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions) - -## Quick Start - -### Setup +When you're done, your setup should look similar to the following: -1. Get ui-router: ->* with bower: `bower install angular-ui-router` ->* fork this repo ->* download the latest release ([compressed](http://angular-ui.github.io/ui-router/release/angular-ui-router.min.js) | [uncompressed](http://angular-ui.github.io/ui-router/release/angular-ui-router.js)) - -1. Add angular-ui-router.min.js to your index.html -> +> ```html - + - - -``` - -2. Set `ui.router` as a dependency in your module. Note: Use `ui.state` if using v0.0.1. -> -```javascript -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. +The majority of UI-Router's power is in its ability to nest states & views. -1. Follow [Setup](https://github.com/angular-ui/ui-router#setup) instructions above. +**(1)** First, follow the [setup](#get-started) instructions detailed above. + +**(2)** Then, add a [`ui-view` directive](https://github.com/angular-ui/ui-router/wiki/Quick-Reference#ui-view) to the `` of your app. -2. Add a `ui-view` to your app. > ```html
- - Route 1 - Route 2 + + State 1 + State 2 ``` -3. 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. +**(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 `` 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. + > ```html - -

Route 1

+ +

State 1

-Show List +Show List
``` ```html - -

Route 2

+ +

State 2

-Show List +Show List
``` -4. Add some child templates. *These* will get plugged into the `ui-view` of their parent state templates. +**(4)** Next, we'll add some child templates. *These* will get plugged into the `ui-view` of their parent state templates. + +> ```html - -

List of Route 1 Items

+ +

List of State 1 Items

    -
  • {{item}}
    • +
  • {{ item }}
``` + +> ```html - -

List of Route 2 Things

+ +

List of State 2 Things

    -
  • {{thing}}
    • +
  • {{ thing }}
``` -5. Now let's wire it all up. Set up your states in the module config: +**(5)** Finally, we'll wire it all up with `$stateProvider`. Set up your states in the module config, as in the following: + + > ```javascript -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"]; - } - }) +myApp.config(function($stateProvider, $urlRouterProvider) { + // + // For any unmatched url, redirect to /state1 + $urlRouterProvider.otherwise("/state1"); + // + // Now set up the states + $stateProvider + .state('state1', { + url: "/state1", + templateUrl: "partials/state1.html" + }) + .state('state1.list', { + url: "/list", + templateUrl: "partials/1.list.html", + controller: function($scope) { + $scope.items = ["A", "List", "Of", "Items"]; + } + }) + .state('state2', { + url: "/state2", + templateUrl: "partials/state2.html" }) + .state('state2.list', { + url: "/list", + templateUrl: "partials/state2.list.html", + controller: function($scope) { + $scope.things = ["A", "Set", "Of", "Things"]; + } + }) + }); ``` -4. See this quick start example in action. +**(6)** See this quick start example in action. >**[Go to Quick Start Plunker for Nested States & Views](http://plnkr.co/edit/u18KQc?p=preview)** -5. This only scratches the surface! You've only seen Nested Views. +**(7)** This only scratches the surface >**[Dive Deeper!](https://github.com/angular-ui/ui-router/wiki)** ### 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. +Another great feature is the ability to have multiple `ui-view`s view per template. -1. Follow [Setup](https://github.com/angular-ui/ui-router#setup) instructions above. +**Pro Tip:** *While mulitple parallel views are a powerful feature, you'll often be able to manage your +interfaces more effectively by nesting your views, and pairing those views with nested states.* -2. Add one or more `ui-view` to your app, give them names. +**(1)** Follow the [setup](#get-started) instructions detailed above. + +**(2)** Add one or more `ui-view` to your app, give them names. > ```html @@ -177,69 +173,99 @@ Another handy feature is the ability to have more than one view per template. Pl
- Route 1 - Route 2 + State 1 + State 2 ``` -3. Set up your states in the module config: +**(3)** Set up your states in the module config: > ```javascript myapp.config(function($stateProvider, $routeProvider){ - $stateProvider - .state('index', { - url: "", - views: { - "viewA": { - template: "index.viewA" - }, - "viewB": { - template: "index.viewB" - } - } - }) - .state('route1', { - url: "/route1", - views: { - "viewA": { - template: "route1.viewA" - }, - "viewB": { - template: "route1.viewB" - } - } - }) - .state('route2', { - url: "/route2", - views: { - "viewA": { - template: "route2.viewA" - }, - "viewB": { - template: "route2.viewB" - } - } - }) + $stateProvider + .state('index', { + url: "", + views: { + "viewA": { template: "index.viewA" }, + "viewB": { template: "index.viewB" } + } + }) + .state('route1', { + url: "/route1", + views: { + "viewA": { template: "route1.viewA" }, + "viewB": { template: "route1.viewB" } + } }) + .state('route2', { + url: "/route2", + views: { + "viewA": { template: "route2.viewA" }, + "viewB": { template: "route2.viewB" } + } + }) +}); ``` -4. See this quick start example in action. +**(4)** See this quick start example in action. >**[Go to Quick Start Plunker for Multiple & Named Views](http://plnkr.co/edit/SDOcGS?p=preview)** -5. This only scratches the surface! You've only seen Named Views and Parallel Views. ->**[Dive Deeper!](https://github.com/angular-ui/ui-router/wiki)** + +## Resources + +* [In-Depth Overview](https://github.com/angular-ui/ui-router/wiki) +* [API Quick Reference](https://github.com/angular-ui/ui-router/wiki/Quick-Reference) +* [Sample App](http://angular-ui.github.com/ui-router/sample/) ([Source](https://github.com/angular-ui/ui-router/tree/master/sample)) +* [FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions) + + +## Report an Issue + +Help us make UI-Router better! If you think you might have found a bug, or some other weirdness, start by making sure +it hasn't already been reported. You can [search through existing issues](https://github.com/angular-ui/ui-router/search?q=wat%3F&type=Issues) +to see if someone's reported one similar to yours. + +If not, then [create a plunkr](http://plnkr.co/edit/u18KQc?p=preview) that demonstrates the problem (try to use as little code +as possible: the more minimalist, the faster we can debug it). + +Next, [create a new issue](https://github.com/angular-ui/ui-router/issues/new) that briefly explains the problem, +and provides a bit of background as to the circumstances that triggered it. Don't forget to include the link to +that plunkr you created! + +Finally, if you're unsure how a feature is used, or are encountering some unexpected behavior that you aren't sure +is a bug, it's best to talk it out in the +[Google Group](https://groups.google.com/forum/#!categories/angular-ui/router) or on +[StackOverflow](http://stackoverflow.com/questions/ask?tags=angularjs,angular-ui-router) before reporting it. This +keeps development streamlined, and helps us focus on building great software. + + +## Contribute + +**(1)** See the **[Developing](#developing)** section below, to get the development version of UI-Router up and running on your local machine. + +**(2)** Check out the [roadmap](https://github.com/angular-ui/ui-router/issues/milestones) to see where the project is headed, and if your feature idea fits with where we're headded. + +**(3)** If you're not sure, [open an RFC](https://github.com/angular-ui/ui-router/issues/new?title=RFC:%20My%20idea) to get some feedback on your idea. + +**(4)** Finally, commit some code and open a pull request. Code & commits should abide by the following rules: + +- *Always* have test coverage for new features (or regression tests for bug fixes), and *never* break existing tests +- Commits should represent one logical change each; if a feature goes through multiple iterations, squash your commits down to one +- Changes should always respect the coding style of the project + + ## Developing -UI-Router uses grunt >= 0.4.x make sure to upgrade your environment and read the +UI-Router uses grunt >= 0.4.x. Make sure to upgrade your environment and read the [Migration Guide](http://gruntjs.com/upgrading-from-0.3-to-0.4). Dependencies for building from source and running tests: * [grunt-cli](https://github.com/gruntjs/grunt-cli) - run: `$ npm install -g grunt-cli` -* Then install development dependencies with: `$ npm install` +* Then, install the development dependencies by running `$ npm install` from the project directory -There is a number of targets in the gruntfile that is used to building the solution, documents etc. +There are a number of targets in the gruntfile that are used to generating different builds: * `grunt`: Perform a normal build, runs jshint and karma tests * `grunt build`: Perform a normal build