Skip to content

Commit cdb70e6

Browse files
nateabelenateabele
committed
Rewrote readme for improve consistency and cohesion
- Added top-level navigation - Added 'report an issue' section - Updated code examples to use latest APIs
1 parent c534cfb commit cdb70e6

File tree

1 file changed

+143
-123
lines changed

1 file changed

+143
-123
lines changed

‎README.md

+143-123
Original file line numberDiff line numberDiff line change
@@ -1,188 +1,191 @@
1-
[![Build Status](https://travis-ci.org/angular-ui/ui-router.png?branch=master)](https://travis-ci.org/angular-ui/ui-router)
1+
# AngularUI Router  [![Build Status](https://travis-ci.org/angular-ui/ui-router.png?branch=master)](https://travis-ci.org/angular-ui/ui-router)
22

3-
# UI-Router
3+
#### The de-facto solution to flexible routing with nested views
4+
---
5+
**[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)**) **|**
6+
**[Discuss](https://groups.google.com/forum/#!categories/angular-ui/router) |**
7+
**[Get Help](http://stackoverflow.com/questions/ask?tags=angularjs,angular-ui-router) |**
8+
**[Report an Issue](#report-an-issue) |**
9+
**[Contribute](#developing)**
410

5-
####Finally a de-facto solution to nested views and routing.
6-
* 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)
11+
---
712

13+
AngularUI Router is a routing framework for [AngularJS](http://angularjs.org), which allows you to organize the
14+
parts of your interface into a [*state machine*](https://en.wikipedia.org/wiki/Finite-state_machine). Unlike the
15+
[`$route` service](http://docs.angularjs.org/api/ngRoute.$route) in Angular core, which is organized around URL
16+
routes, UI-Router is organized around [*states*](https://github.com/angular-ui/ui-router/blob/master/sample/states.js#L28-L269),
17+
which may optionally have routes, as well as other behavior, attached.
818

9-
**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.
19+
States are bound to *named*, *nested* and *parallel views*, allowing you to powerfully manage your application's interface.
1020

11-
## Main Goal
12-
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.
21+
-
22+
**Warning:** *UI-Router is pre-beta and under active development. As such, while this library is well-tested, the API is subject
23+
to change. Using it in a project that requires guaranteed stability is not recommended.*
1324

14-
## Main Features
15-
1. **Robust State Management**
16-
>`$state` and `$stateProvider`
1725

18-
2. **More Powerful Views**
19-
>`ui-view` directive (used in place of `ng-view`)
26+
## Get Started
2027

21-
3. **Nested Views**
22-
>load templates that contain nested `ui-view`s as deep as you'd like.
28+
**(1)** Get UI-Router in one of 3 ways:
29+
- clone & [build](#developing) this repository
30+
- [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))
31+
- or via **[Bower](http://bower.io/)**: by running `$ bower install angular-ui-router` from your console
2332

24-
4. **Routing**
25-
>States can map to URLs (though it's not required)
33+
**(2)** Include `angular-ui-router.js` (or `angular-ui-router.min.js`) in your `index.html`, after including Angular itself
2634

27-
5. **Named Views**
28-
>`<div ui-view="chart">`
35+
**(3)** Add `'ui.router'` to your main module's list of dependencies
2936

30-
6. **Multiple Parallel Views**
31-
>
32-
```
33-
<div ui-view="chart1">
34-
<div ui-view="chart2">
35-
```
36-
37-
38-
*Basically, do whatever you want with states and routes.*
39-
40-
41-
## Resources
42-
43-
* [In-Depth Overview](https://github.com/angular-ui/ui-router/wiki)
44-
* [API Quick Reference](https://github.com/angular-ui/ui-router/wiki/Quick-Reference)
45-
* [Sample App](http://angular-ui.github.com/ui-router/sample/) ([Source](https://github.com/angular-ui/ui-router/tree/master/sample))
46-
* [FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions)
47-
48-
## Quick Start
37+
When you're done, your setup should look similar to the following:
4938

50-
### Setup
51-
52-
1. Get ui-router:
53-
>* with bower: `bower install angular-ui-router`
54-
>* fork this repo
55-
>* 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))
56-
57-
1. Add angular-ui-router.min.js to your index.html
58-
>
39+
>
5940
```html
6041
<!doctype html>
61-
<html ng-app="myapp">
42+
<html ng-app="myApp">
6243
<head>
63-
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.0.6/angular.min.js"></script>
64-
<script src="angular-ui-router.min.js"></script> <!-- Insert after main angular.js file -->
65-
```
66-
67-
2. Set `ui.router` as a dependency in your module. Note: Use `ui.state` if using v0.0.1.
68-
>
69-
```javascript
70-
var myapp = angular.module('myapp', ['ui.router'])
44+
<script src="//ajax.googleapis.com/ajax/libs/angularjs/1.1.5/angular.min.js"></script>
45+
<script src="js/angular-ui-router.min.js"></script>
46+
<script>
47+
var myApp = angular.module('myapp', ['ui.router']);
48+
</script>
49+
...
50+
</head>
51+
<body>
52+
...
53+
</body>
54+
</html>
7155
```
7256

7357
### Nested States & Views
7458

75-
The great majority of ui-router's power is its ability to nest states & views.
59+
The majority of UI-Router's power is in its ability to nest states & views.
7660

77-
1. Follow [Setup](https://github.com/angular-ui/ui-router#setup) instructions above.
61+
**(1)** First, follow the [setup](#get-started) instructions detailed above.
62+
63+
**(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 app.
7864

79-
2. Add a `ui-view` to your app.
8065
>
8166
```html
8267
<!-- index.html -->
8368
<body>
84-
<div ui-view></div>
85-
<!-- Also a way to navigate -->
86-
<a href="#/route1">Route 1</a>
87-
<a href="#/route2">Route 2</a>
69+
<ui-view></ui-view>
70+
<!-- We'll also add some navigation: -->
71+
<a ui-sref="state1">State 1</a>
72+
<a ui-sref="state2">State 2</a>
8873
</body>
8974
```
9075

91-
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.
76+
**(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.
77+
9278
>
9379
```html
94-
<!-- route1.html -->
95-
<h1>Route 1</h1>
80+
<!-- partials/state1.html -->
81+
<h1>State 1</h1>
9682
<hr/>
97-
<a href="#/route1/list">Show List</a>
98-
<div ui-view></div>
83+
<a ui-sref="state1.list">Show List</a>
84+
<ui-view></ui-view>
9985
```
10086
```html
101-
<!-- route2.html -->
102-
<h1>Route 2</h1>
87+
<!-- partials/state2.html -->
88+
<h1>State 2</h1>
10389
<hr/>
104-
<a href="#/route2/list">Show List</a>
105-
<div ui-view></div>
90+
<a ui-sref="state2.list">Show List</a>
91+
<ui-view></ui-view>
10692
```
10793

108-
4. Add some child templates. *These* will get plugged into the `ui-view` of their parent state templates.
94+
**(4)** Next, we'll add some child templates. *These* will get plugged into the `ui-view` of their parent state templates.
95+
96+
>
10997
```html
110-
<!-- route1.list.html -->
111-
<h3>List of Route 1 Items</h3>
98+
<!-- partials/state1.list.html -->
99+
<h3>List of State 1 Items</h3>
112100
<ul>
113-
<li ng-repeat="item in items">{{item}}</li>
101+
<li ng-repeat="item in items">{{ item }}</li>
114102
</ul>
115103
```
104+
105+
>
116106
```html
117-
<!-- route2.list.html -->
118-
<h3>List of Route 2 Things</h3>
107+
<!-- partials/state2.list.html -->
108+
<h3>List of State 2 Things</h3>
119109
<ul>
120-
<li ng-repeat="thing in things">{{thing}}</li>
110+
<li ng-repeat="thing in things">{{ thing }}</li>
121111
</ul>
122112
```
123113

124-
5. Now let's wire it all up. Set up your states in the module config:
114+
**(5)** Finally, we'll wire it all up with `$stateProvider`. Set up your states in the module config, as in the following:
115+
116+
125117
>
126118
```javascript
127-
myapp.config(function($stateProvider, $urlRouterProvider){
128-
//
129-
// For any unmatched url, send to /route1
130-
$urlRouterProvider.otherwise("/route1")
131-
//
132-
// Now set up the states
133-
$stateProvider
134-
.state('route1', {
135-
url: "/route1",
136-
templateUrl: "route1.html"
137-
})
138-
.state('route1.list', {
139-
url: "/list",
140-
templateUrl: "route1.list.html",
141-
controller: function($scope){
142-
$scope.items = ["A", "List", "Of", "Items"];
143-
}
144-
})
145-
.state('route2', {
146-
url: "/route2",
147-
templateUrl: "route2.html"
148-
})
149-
.state('route2.list', {
150-
url: "/list",
151-
templateUrl: "route2.list.html",
152-
controller: function($scope){
153-
$scope.things = ["A", "Set", "Of", "Things"];
154-
}
155-
})
119+
myApp.config(function($stateProvider, $urlRouterProvider) {
120+
//
121+
// For any unmatched url, redirect to /state1
122+
$urlRouterProvider.otherwise("/state1");
123+
//
124+
// Now set up the states
125+
$stateProvider
126+
.state('state1', {
127+
url: "/state1",
128+
templateUrl: "partials/state1.html"
129+
})
130+
.state('state1.list', {
131+
url: "/list",
132+
templateUrl: "partials/1.list.html",
133+
controller: function($scope) {
134+
$scope.items = ["A", "List", "Of", "Items"];
135+
}
136+
})
137+
.state('state2', {
138+
url: "/state2",
139+
templateUrl: "partials/state2.html"
156140
})
141+
.state('state2.list', {
142+
url: "/list",
143+
templateUrl: "partials/state2.list.html",
144+
controller: function($scope) {
145+
$scope.things = ["A", "Set", "Of", "Things"];
146+
}
147+
})
148+
});
157149
```
158150

159-
4. See this quick start example in action.
151+
**(6)** See this quick start example in action.
160152
>**[Go to Quick Start Plunker for Nested States & Views](http://plnkr.co/edit/u18KQc?p=preview)**
161153
162-
5. This only scratches the surface! You've only seen Nested Views.
154+
**(7)** This only scratches the surface
163155
>**[Dive Deeper!](https://github.com/angular-ui/ui-router/wiki)**
164156
165157

158+
## Resources
159+
160+
* [In-Depth Overview](https://github.com/angular-ui/ui-router/wiki)
161+
* [API Quick Reference](https://github.com/angular-ui/ui-router/wiki/Quick-Reference)
162+
* [Sample App](http://angular-ui.github.com/ui-router/sample/) ([Source](https://github.com/angular-ui/ui-router/tree/master/sample))
163+
* [FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions)
164+
165+
166166
### Multiple & Named Views
167167

168-
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.
168+
Another great feature is the ability to have multiple `<ui-view />`s view per template.
169+
170+
**Pro Tip:** *While mulitple parallel views are a powerful feature, you'll often be able to manage your
171+
interfaces more effectively by nesting your views, and pairing those views with nested states.*
169172

170-
1. Follow [Setup](https://github.com/angular-ui/ui-router#setup) instructions above.
173+
**(1)** Follow the [setup](#get-started) instructions detailed above.
171174

172-
2. Add one or more `ui-view` to your app, give them names.
175+
**(2)** Add one or more `ui-view` to your app, give them names.
173176
>
174177
```html
175178
<!-- index.html -->
176179
<body>
177-
<div ui-view="viewA"></div>
178-
<div ui-view="viewB"></div>
180+
<ui-view name="viewA"></div>
181+
<ui-view name="viewB"></div>
179182
<!-- Also a way to navigate -->
180-
<a href="#/route1">Route 1</a>
181-
<a href="#/route2">Route 2</a>
183+
<a ui-sref="state1">State 1</a>
184+
<a ui-sref="state2">State 2</a>
182185
</body>
183186
```
184187

185-
3. Set up your states in the module config:
188+
**(3)** Set up your states in the module config:
186189
>
187190
```javascript
188191
myapp.config(function($stateProvider, $routeProvider){
@@ -223,23 +226,40 @@ myapp.config(function($stateProvider, $routeProvider){
223226
})
224227
```
225228

226-
4. See this quick start example in action.
229+
**(4)** See this quick start example in action.
227230
>**[Go to Quick Start Plunker for Multiple & Named Views](http://plnkr.co/edit/SDOcGS?p=preview)**
228231
229-
5. This only scratches the surface! You've only seen Named Views and Parallel Views.
230-
>**[Dive Deeper!](https://github.com/angular-ui/ui-router/wiki)**
232+
## Report an Issue
233+
234+
Help us make UI-Router better! If you think you might have found a bug, or some other weirdness, start by making sure
235+
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)
236+
to see if someone's reported one similar to yours.
237+
238+
If not, then [create a plunkr](http://plnkr.co/edit/u18KQc?p=preview) that demonstrates the problem (try to use as little code
239+
as possible: the more minimalist, the faster we can debug it).
240+
241+
Next, [create a new issue](https://github.com/angular-ui/ui-router/issues/new) that briefly explains the problem,
242+
and provides a bit of background as to the circumstances that triggered it. Don't forget to include the link to
243+
that plunkr you created!
244+
245+
Finally, if you're unsure how a feature is used, or are encountering some unexpected behavior that you aren't sure
246+
is a bug, it's best to talk it out in the
247+
[Google Group](https://groups.google.com/forum/#!categories/angular-ui/router) or on
248+
[StackOverflow](http://stackoverflow.com/questions/ask?tags=angularjs,angular-ui-router) before reporting it. This
249+
keeps development streamlined, and helps us focus on building great software.
250+
231251

232252
## Developing
233253

234-
UI-Router uses <code>grunt >= 0.4.x</code> make sure to upgrade your environment and read the
254+
UI-Router uses <code>grunt >= 0.4.x</code>. Make sure to upgrade your environment and read the
235255
[Migration Guide](http://gruntjs.com/upgrading-from-0.3-to-0.4).
236256

237257
Dependencies for building from source and running tests:
238258

239259
* [grunt-cli](https://github.com/gruntjs/grunt-cli) - run: `$ npm install -g grunt-cli`
240260
* Then install development dependencies with: `$ npm install`
241261

242-
There is a number of targets in the gruntfile that is used to building the solution, documents etc.
262+
There are a number of targets in the gruntfile that is used to building the solution, documents etc.
243263

244264
* `grunt`: Perform a normal build, runs jshint and karma tests
245265
* `grunt build`: Perform a normal build

0 commit comments

Comments
 (0)