Skip to content

Commit ba32907

Browse files
elbomanelboman
committed
chore(docs): update documentation for 0.4.0
update API doc update README add 0.3.x > 0.4.x migration guide
1 parent a837f46 commit ba32907

File tree

4 files changed

+284
-31
lines changed

4 files changed

+284
-31
lines changed

‎README.md

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
# UI-Router-React [![travis build][travis-badge]][travis] [![npm package][npm-badge]][npm]
1+
<div align="center">
2+
<img src="/logo/logo.png" height="150"/>
23

3-
<img src="/logo/logo.png" height="150"/>
4+
# UI-Router-React
5+
6+
[![travis build][travis-badge]][travis] [![npm package][npm-badge]][npm]
7+
</div>
48

59
UI-Router provides extremely flexible, state based routing to the [React](https://facebook.github.io/react/) ecosystem.
610

@@ -13,6 +17,7 @@ UI-Router applications are modeled as a hierarchical tree of states. UI-Router p
1317
- [Tutorials and Docs](/docs)
1418
- [UI-Router website](https://ui-router.github.io/)
1519
- [Changelog](/CHANGELOG.md)
20+
- [Upgrading from `0.3.x` to `0.4.x`](/docs/upgrading-from-0.3.x-to-0.4.x.md)
1621

1722
## Getting started
1823
The UI-Router package is distributed using [npm](https://www.npmjs.com/), the node package manager.
@@ -21,36 +26,31 @@ The UI-Router package is distributed using [npm](https://www.npmjs.com/), the no
2126
npm install --save ui-router-react
2227
```
2328

24-
Import the `UIRouterReact` into your project, create a new instance and start the router!
29+
Import `UIRouter` into your project, define some states and you're good to go!
30+
2531
```jsx
2632
import React from 'react';
2733
import ReactDOM from 'react-dom';
28-
import UIRouterReact, {UIView} from 'ui-router-react';
34+
import {UIRouter, UIView, pushStateLocationPlugin} from 'ui-router-react';
2935
import Home from './components/Home';
3036

31-
// Create a new instance of the Router
32-
const router = new UIRouterReact();
33-
34-
// Register state
35-
router.stateRegistry.register({
36-
name: 'home',
37-
url: '/home',
38-
component: Home
39-
});
40-
41-
// Setup html5Mode: There are two configuration modes which control the format
42-
// of the URL in the browser address bar: hashLocation mode (the default)
43-
// and the HTML5 mode which is based on using the HTML5 History API.
44-
// WARNING: this is a temporary API and will likely change in the future versions!
45-
router.html5Mode(true);
46-
47-
// Start the router
48-
router.start();
37+
// define your states
38+
const states = [{
39+
name: 'home',
40+
url: '/home',
41+
component: Home
42+
}];
4943

44+
// select your plugins
45+
const plugins = [
46+
pushStateLocationPlugin
47+
];
5048

5149
ReactDOM.render(
52-
<UIView/>,
53-
document.getElementById('root')
50+
<UIRouter plugins={plugins} states={states}>
51+
<UIView/>
52+
</UIRouter>,
53+
document.getElementById('root')
5454
);
5555
```
5656

‎docs/API.md

Lines changed: 116 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
- [`urlRouterProvider`](#urlrouterprovider-urlrouterprovider)
1111
- [`viewService`](#viewservice-viewservice)
1212
- [`start()`](#start-void)
13-
- [`html5mode()`](#html5modemode-boolean-void)
13+
- [`plugin()`](#plugin-uirouterplugin)
14+
- [`html5mode()`](#html5modemode-boolean-void) - *deprecated*
1415

1516
- [State Declaration](#state-declaration)
1617
- [`abstract`](#abstract-boolean)
@@ -28,6 +29,7 @@
2829
- [`views`](#views-object)
2930

3031
- [Components](#components)
32+
- [`<UIRouter>`](#uirouter)
3133
- [`<UIView>`](#uiview)
3234
- [`<UISref>`](#uisref)
3335
- [`<UISrefActive>`](#uisrefactive)
@@ -36,6 +38,11 @@
3638

3739
- [Transitions](#transitions)
3840

41+
- [Plugins](#plugins)
42+
- [`pushStateLocationPlugin`](#pushStateLocationPlugin)
43+
- [`hashLocationPlugin`](#hashLocationPlugin)
44+
- [`memoryLocationPlugin`](#memoryLocationPlugin)
45+
3946
- [Utilities](#utilities)
4047
- [`trace`](#trace)
4148

@@ -108,14 +115,16 @@ Take a look at the [ViewService Class](https://ui-router.github.io/docs/latest/c
108115
#### `start()`: void
109116
Starts the router. It tells the router to listen for state changes and to sync the url accordingly.
110117

118+
#### `plugin()`: UIRouterPlugin
119+
Register a plugin in the router instance, the plugin is returned by the function.
120+
111121
#### `html5mode(mode: boolean)`: void
112122

123+
**Deprecated in 0.4.0!**
124+
113125
By default UI-Router works with a `HashLocation` history implementation.
114126
If `mode` is true, the HTML5 `PushStateLocation` will be used instead.
115127

116-
> WARNING, html5mode() is a temporary API and will likely change in the future.
117-
> Future versions of UI-Router React will provide a way to specify custom history implementation.
118-
119128
## State Declaration
120129
A state declaration object is used to register a new state. It is registered via the `stateRegistry`.
121130

@@ -400,12 +409,94 @@ views: {
400409
401410
## Components
402411
412+
### `<UIRouter>`
413+
414+
Main router component that handles router instance and initialization.
415+
416+
```jsx
417+
render(
418+
<UIRouter plugins={[•••]} states={[•••]}>
419+
<UIView />
420+
</UIRouter>,
421+
document.getElementById('root')
422+
);
423+
```
424+
425+
#### Props
426+
427+
##### `children`: element
428+
429+
You may define a single child element. Descendants of this component will have access to the router instance via React context.
430+
431+
##### `plugins`: array
432+
433+
Plugins to apply to the router instance. By default, the component applies the `servicesPlugin` which is in charge of handling the DI mechanism as well as the promises implementation.
434+
435+
In order for the router to work, you need to specify a location plugin.
436+
The library by default provides three location implementation plugins: `hash`, `pushState` and `memory`.
437+
438+
There are other plugins that extend the router base functionalities and you can also write your own plugin.
439+
440+
##### `states`: array
441+
442+
You may provide an array of state definition that are registered right after the router is initialized.
443+
444+
##### `config`: function
445+
446+
THe config prop accepts a function that will be called with the newly router instance as argument.
447+
You can use this function to configure the router:
448+
449+
```jsx
450+
const configRouter = router => {
451+
router.urlRouterProvider.otherwise("/home");
452+
}
453+
454+
render(
455+
<UIRouter plugins={[•••]} states={[•••]} config={configRouter}>
456+
<UIView />
457+
</UIRouter>,
458+
document.getElementById('root')
459+
);
460+
```
461+
462+
##### `router`: UIRouterReact
463+
464+
Since UI-Router is framework agnostic, you can set-up the router manually in "vanilla" ui-router, and pass the instance to the component.
465+
This way the component will skip the previous props and just use the provided instance.
466+
467+
```jsx
468+
import {UIRouterReact, UIRouter, UIView, servicesPlugin, pushStateLocationPlugin} from 'ui-router-react';
469+
470+
const someState = { name: 'some', url: '', component: SomeComponent };
471+
// create instance
472+
const router = new UIRouterReact();
473+
// activate plugins
474+
router.plugin(servicesPlugin);
475+
router.plugin(pushStateLocationPlugin);
476+
// register states
477+
router.stateRegistry.register(someState);
478+
// start the router
479+
router.start();
480+
481+
ReactDOM.render(
482+
<UIRouter router={router}>
483+
<UIView />
484+
</UIRouter>,
485+
document.getElementById("root")
486+
);
487+
```
488+
489+
> NB: since you are manually bootstrapping the router, you must register the `servicesPlugin` as well as the location plugin of your choice (in this example the `pushStateLocationPlugin`).
490+
403491
### `<UIView>`
404-
The view component renders your state components when a state is active.
492+
493+
The view component renders your state components when a state is active. It must be a descendant of `<UIRouter>` component in order to work.
405494
406495
```jsx
407496
render(
408-
<UIView/>
497+
<UIRouter {•••}>
498+
<UIView/>
499+
</UIRouter>,
409500
document.getElementById('root')
410501
);
411502
```
@@ -531,6 +622,25 @@ The transitions are always inject in the state components via the `transition` p
531622
532623
Take a look at the [Transition Class](https://ui-router.github.io/docs/latest/classes/transition.transition-1.html) for more info.
533624
625+
## Plugins
626+
627+
Plugins are a handy way to extend UI-Router functionalities. The router internally uses a DI mechanism as well as a Promise implementation.
628+
Both are implemented as the `servicesPlugin`.
629+
630+
Location implementation are also implemented as plugins:
631+
632+
### `pushStateLocationPlugin`
633+
634+
Location strategy via html5 `pushState` API.
635+
636+
### `hashLocationPlugin`
637+
638+
Location strategy via url hash portion (i.e. `myurl.com/#/home`).
639+
640+
### `memoryLocationPlugin`
641+
642+
Location strategy via in-memory object, useful for environments where a location is not present (server-side code for SSR).
643+
534644
## Utilities
535645
536646
### `trace`

‎docs/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# Tables of Contents
22

33
- [Tutorials](https://ui-router.github.io/react/#tutorials)
4-
- [API](API.md)
4+
- [API](API.md)
5+
- [Upgrading from `0.3.x` to `0.4.x`](upgrading-from-0.3.x-to-0.4.x.md)

0 commit comments

Comments
 (0)