diff options
Diffstat (limited to 'web/src/vendor/react-router/docs/api/components')
7 files changed, 503 insertions, 0 deletions
diff --git a/web/src/vendor/react-router/docs/api/components/DefaultRoute.md b/web/src/vendor/react-router/docs/api/components/DefaultRoute.md new file mode 100644 index 00000000..6607832b --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/DefaultRoute.md @@ -0,0 +1,55 @@ +API: `DefaultRoute` (component) +=============================== + +A route that is active when the parent route's path matches exactly. Or, +in other words, the default child route for a parent. + +Note, this is not a `NotFoundRoute`. It is only active when the parent's +route path is matched exactly. + +Props +----- + +See [Route::props][routeProps] + +Example +------- + +```xml +<Routes> + <Route path="/" handler={App}> + + <!-- + when the url is `/`, this handler will be active, or in other + words, will be `this.props.activeRouteHandler in the `App` handler + --> + <DefaultRoute handler={Home}/> + + <Route name="about" handler={About}/> + <Route name="users" handler={Users}> + <Route name="user" handler={User} path="/user/:id"/> + + <!-- when the url is `/users`, this will be active --> + <DefaultRoute handler={UsersIndex}/> + + </Route> + </Route> +</Routes> +``` + +This is all really just a shortcut for the less intuitive version of the +same functionality: + +```xml +<!-- no path or name on what was previously the "users" route --> +<Route handler={Users}> + <!-- the path moved down to the child --> + <Route name="users-index" path="/users" handler={UsersIndex}/> + <Route name="user" handler={User} path="/user/:id"/> +</Route> +``` + +`DefaultRoute` feels more natural, so you can name and transition to the +parent route. + + [routeProps]:/docs/api/components/Route.md#props diff --git a/web/src/vendor/react-router/docs/api/components/Link.md b/web/src/vendor/react-router/docs/api/components/Link.md new file mode 100644 index 00000000..9c5bfd12 --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/Link.md @@ -0,0 +1,71 @@ +API: `Link` (component) +========================= + +Creates an anchor tag that links to a route in the application. Also +gets the `active` class automatically when the route matches. If you +change the path of your route, you don't have to change your links. + +Props +----- + +### `to` + +The name of the route to link to, or a full URL. + +### `params` + +Object, the parameters to fill in the dynamic segments of your route. + +#### Example + +```js +// given a route config like this +<Route name="user" path="/user/:userId"/> + +// create a link with this +<Link to="user" params={{userId: "123"}}/> + +// though, if your user properties match up to the dynamic segements: +<Link to="user" params={user}/> +``` + +### `query` + +Object, Query parameters to add to the link. Access query parameters in +your route handler with `this.props.query`. + +### `activeClassName` + +The className a `Link` receives when it's route is active. Defaults to +`active`. + +### `onClick` + +A custom handler for the click event. Works just like a handler on an `<a>` +tag - calling `e.preventDefault()` or returning `false` will prevent the +transition from firing, while `e.stopPropagation()` will prevent the event +from bubbling. + +### *others* + +You can also pass props you'd like to be on the `<a>` such as a title, id, or className. + +Example +------- + +Given a route like `<Route name="user" path="/users/:userId"/>`: + +```xml +<Link to="user" params={{userId: user.id}} query={{foo: bar}}>{user.name}</Link> +<!-- becomes one of these depending on your router and if the route is +active --> +<a href="/users/123?foo=bar" class="active">Michael</a> +<a href="#/users/123?foo=bar">Michael</a> + +<!-- or if you have the full url already, you can just pass that in --> +<Link to="/users/123?foo=bar">{user.name}</Link> + +<!-- change the activeClassName --> +<Link activeClassName="current" to="user" params={{userId: user.id}}>{user.name}</Link> +``` + diff --git a/web/src/vendor/react-router/docs/api/components/NotFoundRoute.md b/web/src/vendor/react-router/docs/api/components/NotFoundRoute.md new file mode 100644 index 00000000..366c78b4 --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/NotFoundRoute.md @@ -0,0 +1,36 @@ +API: `NotFoundRoute` (component) +=============================== + +When a parent's URL partially matches, but none of the children do, a +`NotFoundRoute` will be matched and its handler rendered at any level of +your route/view hierarchy. + +Props +----- + +See [Route::props][routeProps] + +Example +------- + +```xml +<Routes> + <Route path="/" handler={App}> + <Route name="course" path="course/:courseId" handler={Course}> + <Route name="course-dashboard" path="dashboard" /> + + <!-- ie: `/course/123/foo` --> + <NotFoundRoute handler={CourseRouteNotFound} /> + </Route> + + <!-- ie: `/flkjasdf` --> + <NotFoundRoute handler={NotFound} /> + </Route> +</Routes> +``` + +The last `NotFoundRoute` will render inside the `App`, the first will +rendering inside of `Course`. + + [routeProps]:/docs/api/components/Route.md#props + diff --git a/web/src/vendor/react-router/docs/api/components/Redirect.md b/web/src/vendor/react-router/docs/api/components/Redirect.md new file mode 100644 index 00000000..a31222a0 --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/Redirect.md @@ -0,0 +1,59 @@ +API: `Redirect` (component) +=========================== + +Configures a redirect for a path in your route declarations. + +Props +----- + +### `from` + +The path you want to redirect from, including dynamic segments. Defaults +to `*` so you can redirect anything not found to somewhere else. + +### `to` + +The `name` of the route you want to redirect to. + +Example +------- + +```xml +<!-- + lets say we want to change from `/profile/123` to `/about/123` + and redirect `/get-in-touch` to `/contact` +--> +<Routes> + <Route handler={App}> + <Route name="contact" handler={Contact}/> + <Route name="about-user" path="about/:userId" handler={UserProfile}/> + <Route name="course" path="course/:courseId"> + <Route name="course-dashboard" path="dashboard" handler={Dashboard}/> + <Route name="course-assignments" path="assignments" handler={Assignments}/> + <!-- + anything like `/course/123/invalid` redirects to + `/course/123/dashboard` + --> + <Redirect to="course-dashboard" /> + </Route> + </Route> + + <!-- `/get-in-touch` -> `/contact` --> + <Redirect from="get-in-touch" to="contact" /> + <!-- `/profile/123` -> `/about/123` --> + <Redirect from="profile/:userId" to="about-user" /> +</Routes> +``` + +Note that the `<Redirect/>` can be placed anywhere in the route +hierarchy, if you'd prefer the redirects to be next to their respective +routes. + +```xml +<Routes> + <Route handler={App}> + <Route name="contact" handler={Contact}/> + <Redirect from="get-in-touch" to="contact" /> + </Route> +</Routes> +``` diff --git a/web/src/vendor/react-router/docs/api/components/Route.md b/web/src/vendor/react-router/docs/api/components/Route.md new file mode 100644 index 00000000..b1f3ba9b --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/Route.md @@ -0,0 +1,105 @@ +API: `Route` (component) +========================= + +Configuration component to declare your application's routes and view hierarchy. + +Props +----- + +### `name` + +The name of the route, used in the `Link` component and the router's +transition methods. + +### `path` + +The path used in the URL. If left undefined, the path will be defined by +the `name`, and if there is no name, will default to `/`. + +Please refer to the [Path Matching Guide][path-matching] to learn more +about supported path matching syntax. + +### `handler` + +The component to be rendered when the route is active. + +### `addHandlerKey` + +Defaults to `false`. + +If you have dynamic segments in your URL, a transition from `/users/123` +to `/users/456` does not call `getInitialState`, `componentWillMount` or +`componentWillUnmount`. If you are using those lifecycle hooks to fetch +data and set state, you will also need to implement +`componentWillReceiveProps` on your handler, just like any other +component with changing props. This way, you can leverage the +performance of the React DOM diff algorithm. Look at the `Contact` +handler in the `master-detail` example. + +If you'd rather be lazy, set this to `true` and the router will add a +key to your route, causing all new DOM to be built, and then the life +cycle hooks will all be called. + +You will want this to be `true` if you're doing animations with React's +TransitionGroup component. + +### `preserveScrollPosition` + +If `true`, the router will not scroll the window up when the route is +transitioned to. Defaults to `false`. Ignored if the parent `<Routes/>` +has been set to `true`. + +### `children` + +Routes can be nested. When a child route matches, the parent route's +handler will have the child route's handler available as +`this.props.activeRouteHandler`. You can then render it in the parent +passing in any additional props as needed. + +### `[prop]` + +Any additional, user-defined, properties will be become properties of +the rendered handler. + +#### Example: + +```js +var App; +var foo = "hello"; + +var routes = ( + <Routes> + // pass `foo` to `something` + <Route handler={App} something={foo}/> + </Routes> +); + +App = React.createClass({ + render: function() { + // access `something` on props + return <div>{this.props.something}</div> + } +}); + +React.renderComponent(routes, document.body); +document.body.innerHTML // -> <div>hello</div> +``` + +Example +------- + +```xml +<Routes> + <!-- path defaults to '/' since no name or path provided --> + <Route handler={App}> + <!-- path is automatically assigned to the name since it is omitted --> + <Route name="about" handler={About}/> + <Route name="users" handler={Users}> + <!-- note the dynamic segment in the path --> + <Route name="user" handler={User} path="/user/:id"/> + </Route> + </Route> +</Routes> +``` + + [path-matching]:/docs/guides/path-matching.md diff --git a/web/src/vendor/react-router/docs/api/components/RouteHandler.md b/web/src/vendor/react-router/docs/api/components/RouteHandler.md new file mode 100644 index 00000000..e39fad94 --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/RouteHandler.md @@ -0,0 +1,108 @@ +API: `RouteHandler` (component) +=============================== + +The component supplied to a route is called a "Route Handler". They are +rendered when their route is active. There are some special props and +static methods available to these components. + +Props +----- + +### `activeRouteHandler(extraProps)` + +Render the active nested route handler with this property, passing in +additional properties as needed. This is the mechanism by which you get +effortless nested UI. + +#### Example + +```js +var App = React.createClass({ + render: function() { + <div> + <h1>Address Book</h1> + {/* the active child route handler will be rendered here */} + {/* you can "trickle down" props to the active child */} + <this.props.activeRouteHandler someProp="foo" /> + </div> + } +}); + +var Contact = React.createClass({ + render: function() { + return <h1>{this.props.params.id}</h1> + } +}); + +var routes = ( + <Routes> + <Route handler={App}> + <Route name="contact" path="/contact/:id" handler={Contact}> + </Route> + </Routes> +); + +React.renderComponent(routes, document.body); +``` + +### `params` + +When a route has dynamic segments like `<Route path="users/:userId"/>`, +the dynamic values from the url are available at +`this.props.params.userId`, etc. + +### `query` + +The query parameters from the url. + +Static Lifecycle Methods +------------------------ + +You can define static methods on your route handlers that will be called +during route transitions. + +### `willTransitionTo(transition, params, query)` + +Called when a route is about to render, giving you the opportunity to +abort or redirect the transition. You can return a promise and the whole +route hierarchy will wait for the promises to resolve before proceeding. + +See also: [transition](/docs/api/misc/transition.md) + +### `willTransitionFrom(transition, component)` + +Called when an active route is being transitioned out giving you an +opportunity to abort the transition. The `component` is the current +component, you'll probably need it to check its state to decide if you +want to allow the transition. + +See also: [transition](/docs/api/misc/transition.md) + +#### Example + +```js +var Settings = React.createClass({ + statics: { + willTransitionTo: function(transition, params) { + return auth.isLoggedIn().then(function(loggedIn) { + if (!loggedIn) + return; + transition.abort(); + return auth.logIn({transition: transition}); + // in auth module call `transition.retry()` after being logged in + }); + }, + + willTransitionFrom: function(transition, component) { + if (component.formHasUnsavedData())) { + if (!confirm('You have unsaved information, are you sure you want to leave this page?')) { + transition.abort(); + } + } + } + } + + //... +}); +``` + diff --git a/web/src/vendor/react-router/docs/api/components/Routes.md b/web/src/vendor/react-router/docs/api/components/Routes.md new file mode 100644 index 00000000..2d9396aa --- /dev/null +++ b/web/src/vendor/react-router/docs/api/components/Routes.md @@ -0,0 +1,69 @@ +API: `Routes` (component) +========================= + +Configuration component for your router, all `<Route/>`s must be +children of a `<Routes/>`. It is the component you provide to +`React.renderComponent(routes, el)`. + +Props +----- + +### `location` + +One of `"hash"`, `"history"` or a user defined location implementation, +defaults to `"hash"`. + +`"hash"` includes `#/` in the url and works without a server, if you use +`history` your server will need to support it. + +For browsers that don't support the HTML5 history API the router will +fall back to `window.location` if you choose `history`, in other words, +the router will simply cause a full page reload. This way all users get +the same urls and can share them. + +See also: [user supplied locations][Location]. + +### `preserveScrollPosition` + +If `true`, the router will not scroll the window up globally when any +route is transitioned to. Defaults to `false`. When `false`, the +`<Route/>` gets to decide whether or not to scroll on transition. + +### `onAbortedTransition` + +A function called when any transition is aborted. + +### `onActiveStateChange` + +A function called when the active routes change. + +#### signature + +`function(nextState)` + +### `onTransitionError` + +A function called when a transition has an error. + +#### signature + +`function(error)` + +Example +------- + +```jsx +function onError(error) { + handleError(error); +} + +var routes = ( + <Routes location="history" onTransitionError={onError}> + <Route handler={App}/> + </Routes> +); +React.renderComponent(routes, document.body); +``` + + [Location]:../misc/Location.md + |