From 0bfb31fd5da99d5f66253d883e618df225767a0b Mon Sep 17 00:00:00 2001 From: Sabra Pratt Date: Fri, 18 Sep 2015 15:16:41 -0700 Subject: [PATCH] Single-page API docs refactor. --- README.md | 3 +- UPGRADE_GUIDE.md | 3 +- docs/API.md | 668 ++++++++++++++++++ docs/Glossary.md | 22 + docs/Introduction.md | 4 +- docs/README.md | 32 +- docs/api/History.md | 158 ----- docs/api/IndexLink.md | 1 - docs/api/IndexRoute.md | 14 - docs/api/Lifecycle.md | 21 - docs/api/Link.md | 58 -- docs/api/PlainRoute.md | 59 -- docs/api/PropTypes.md | 1 - docs/api/README.md | 26 - docs/api/Redirect.md | 42 -- docs/api/Route.md | 144 ---- docs/api/RouteComponent.md | 101 --- docs/api/RouteContext.md | 6 - docs/api/Router.md | 72 -- docs/api/RoutingContext.md | 4 - docs/api/createRoutes.md | 8 - docs/api/useRoutes.md | 9 - .../advanced/ComponentLifecycle.md | 0 .../advanced/ConfirmingNavigation.md | 6 +- docs/{ => guides}/advanced/DynamicRouting.md | 4 +- .../advanced/NavigatingOutsideOfComponents.md | 1 - docs/{ => guides}/advanced/README.md | 2 +- docs/{ => guides}/advanced/ServerRendering.md | 4 +- docs/{ => guides}/basics/Histories.md | 8 - docs/{ => guides}/basics/IndexRoutes.md | 3 +- docs/{ => guides}/basics/README.md | 0 .../{ => guides}/basics/RouteConfiguration.md | 10 +- docs/{ => guides}/basics/RouteMatching.md | 5 +- 33 files changed, 712 insertions(+), 787 deletions(-) create mode 100644 docs/API.md delete mode 100644 docs/api/History.md delete mode 100644 docs/api/IndexLink.md delete mode 100644 docs/api/IndexRoute.md delete mode 100644 docs/api/Lifecycle.md delete mode 100644 docs/api/Link.md delete mode 100644 docs/api/PlainRoute.md delete mode 100644 docs/api/PropTypes.md delete mode 100644 docs/api/README.md delete mode 100644 docs/api/Redirect.md delete mode 100644 docs/api/Route.md delete mode 100644 docs/api/RouteComponent.md delete mode 100644 docs/api/RouteContext.md delete mode 100644 docs/api/Router.md delete mode 100644 docs/api/RoutingContext.md delete mode 100644 docs/api/createRoutes.md delete mode 100644 docs/api/useRoutes.md rename docs/{ => guides}/advanced/ComponentLifecycle.md (100%) rename docs/{ => guides}/advanced/ConfirmingNavigation.md (77%) rename docs/{ => guides}/advanced/DynamicRouting.md (72%) rename docs/{ => guides}/advanced/NavigatingOutsideOfComponents.md (99%) rename docs/{ => guides}/advanced/README.md (93%) rename docs/{ => guides}/advanced/ServerRendering.md (97%) rename docs/{ => guides}/basics/Histories.md (99%) rename docs/{ => guides}/basics/IndexRoutes.md (97%) rename docs/{ => guides}/basics/README.md (100%) rename docs/{ => guides}/basics/RouteConfiguration.md (93%) rename docs/{ => guides}/basics/RouteMatching.md (98%) diff --git a/README.md b/README.md index dcd1ebad7a..9ae041d02b 100644 --- a/README.md +++ b/README.md @@ -124,8 +124,7 @@ React.render(( ), document.body) ``` -See more in the [Introduction](/docs/Introduction.md) and [Advanced -Usage](/docs/advanced/README.md). +See more in the [Introduction](/docs/Introduction.md) and [Advanced Usage](/docs/guides/advanced/README.md). ### Thanks diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index b586fbfc3f..51d435bc58 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -293,7 +293,7 @@ var Home = React.createClass({ ``` To cancel a "transition from", please refer to the -[Confirming Navigation](docs/advanced/ConfirmingNavigation.md) guide. +[Confirming Navigation](docs/guides/advanced/ConfirmingNavigation.md) guide. ### We'll keep updating this @@ -1104,4 +1104,3 @@ router.renderComponent(element); // 0.2.x React.renderComponent(routes, element); ``` - diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000000..46d37494ad --- /dev/null +++ b/docs/API.md @@ -0,0 +1,668 @@ +# API Reference + +* [Components](#components) + - [Router](#router) + - [Link](#link) + - [IndexLink](#indexlink) + - [RoutingContext](#routingcontext) + +* [Configuration Components](#configuration-components) + - [Route](#route) + - [PlainRoute](#plainroute) + - [Redirect](#redirect) + - [IndexRoute](#indexroute) + +* [Handler Components](#handler-components) + +* [Mixins](#mixins) + - [Lifecycle](#lifecycle-mixin) + - [History](#history-mixin) + - [RouteContext](#routecontext-mixin) + +* [Utilities](#utilities) + * [useRoutes](#useroutescreatehistory) + * [createRoutes](#createroutesroutes) + * [PropTypes](#proptypes) + + +## Components + +### Router +Primary component of React Router. It keeps your UI and the URL in sync. + +#### Props +##### `children` (required) +One or many [`Routes`](#route) or [`PlainRoutes`](#plainroute). When the +history changes, `Router` will match a branch of its [`Routes`](#route), +and render their configured [components](#routecomponent), with child +route components nested inside the parents. + +##### `routes` +Alias for `children`. + +##### `history` +The history the router should listen to from the `history` package. + +##### `createElement(Component, props)` +When the router is ready to render a branch of route components, it will +use this function to create the elements. You may want to take control +of creating the elements when you're using some sort of data abstraction, like setting up subscriptions to stores, or passing in some sort of application module to each component via props. + +```js + + +// default behavior +function createElement(Component, props) { + // make sure you pass all the props in! + return +} + +// maybe you're using something like Relay +function createElement(Component, props) { + // make sure you pass all the props in! + return +} +``` + +##### `stringifyQuery(queryObject)` +A function used to convert an object from [`Link`](#link)s or calls to +[`transitionTo`](#transitiontopathname-query-state) to a URL query string. + +##### `parseQueryString(queryString)` +A function used to convert a query string into an object that gets passed to route component props. + +##### `onError(error)` +While the router is matching, errors may bubble up, here is your opportunity to catch and deal with them. Typically these will come from async features like [`route.getComponents`](#getcomponentscallback) and [`route.getChildRoutes`](#getchildrouteslocation-callback). + +##### `onUpdate()` +Called whenever the router updates its state in response to URL changes. + +#### Examples +Please see the [`examples/`](/examples) directory of the repository for extensive examples of using `Router`. + + + +### Link +The primary way to allow users to navigate around your application. +`Link` will render a fully accessible anchor tag with the proper href. + +A `Link` also knows when the route it links to is active and automatically +applies its `activeClassName` and/or `activeStyle` when it is. + +#### Props +##### `to` +The path to link to, e.g., `/users/123`. + +##### `query` +An object of key:value pairs to be stringified. + +##### `state` +State to persist to the `location`. + +##### `activeClassName` +The className a `Link` receives when its route is active. No active class by default. + +##### `activeStyle` +The styles to apply to the link element when its route is active. + +##### `onClick` +A custom handler for the click event. Works just like a handler on an `` +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 `` such as a title, id, className, etc. + +#### Example +Given a route like ``: + +```js +{user.name} +// becomes one of these depending on your History and if the route is +// active +Michael +Michael + +// change the activeClassName +{user.name} + +// change style when link is active +Users +``` + +### IndexLink +Docs coming so soon! + +### RoutingContext +A `RoutingContext` renders the component tree for a given router state and sets the history object and the current location in context. + + + +## Configuration Components + +## Route +A `Route` is used to declaratively map routes to your application's +component hierarchy. + +#### Props +##### `path` +The path used in the URL. + +It will concat with the parent route's path unless it starts with `/`, +making it an absolute path. + +**Note**: Absolute paths may not be used in route config that is [dynamically loaded](/docs/guides/advanced/DynamicRouting.md). + +If left undefined, the router will try to match the child routes. + +##### `component` +A single component to be rendered when the route matches the url. It can +be rendered by the parent route component with `this.props.children`. + +```js +const routes = ( + + + + +) + +const App = React.createClass({ + render () { + return ( +
+ {/* this will be either or */} + {this.props.children} +
+ ) + } +}) +``` + +##### `components` +Routes can define multiple components as an object of `name:component` +pairs to be rendered when the path matches the url. They can be rendered +by the parent route component with `this.props.children[name]`. + +```js +// think of it outside the context of the router, if you had pluggable +// portions of your `render`, you might do it like this +, sidebar: }}/> + +// So with the router it looks like this: +const routes = ( + + + + + + +) + +const App = React.createClass({ + render () { + const { main, sidebar } = this.props.children + return ( +
+
+ {main} +
+
+ {sidebar} +
+
+ ) + } +}) + +const Users = React.createClass({ + render () { + return ( +
+ {/* if at "/users/123" `children` will be */} + {/* UsersSidebar will also get as this.props.children, + so its a little weird, but you can decide which one wants + to continue with the nesting */} + {this.props.children} +
+ ) + } +}) +``` +##### `getComponent(location, callback)` +Same as `component` but asynchronous, useful for +code-splitting. + +###### `callback` signature +`cb(err, component)` + +```js + { + // do asynchronous stuff to find the components + cb(null, Course) +}}/> +``` + +##### `getComponents(location, callback)` +Same as `components` but asynchronous, useful for +code-splitting. + +###### `callback` signature +`cb(err, components)` + +```js + { + // do asynchronous stuff to find the components + cb(null, {sidebar: CourseSidebar, content: Course}) +}}/> +``` + +##### `children` +Routes can be nested, `this.props.children` will contain the element created from the child route component. Please refer to the [Route Configuration](/docs/guides/basics/RouteConfiguration.md) since this is a very critical part of the router's design. + +##### `onEnter(nextState, replaceState)` +Called when a route is about to be entered. It provides the next router state and a function to redirect to another path. + +##### `onLeave()` +Called when a route is about to be exited. + + + +## PlainRoute +A plain JavaScript object route definition. `Router` turns JSX +``s into these objects, but you can use them directly if you +prefer. All of the props are the same as `` props, except +those listed here. + +#### Props +##### `childRoutes` +An array of child routes, same as `children` in JSX route configs. + +##### `getChildRoutes(location, callback)` +Same as `childRoutes` but asynchronous and receives the `location`. +Useful for code-splitting and dynamic route matching (given some state +or session data to return a different set of child routes). + +###### `callback` signature +`cb(err, routesArray)` + +```js +let myRoute = { + path: 'course/:courseId', + childRoutes: [ + announcementsRoute, + gradesRoute, + assignmentsRoute + ] +} + +// async child routes +let myRoute = { + path: 'course/:courseId', + getChildRoutes (location, cb) { + // do asynchronous stuff to find the child routes + cb(null, [announcementsRoute, gradesRoute, assignmentsRoute]) + } +} + +// navigation dependent child routes +// can link with some state + + +let myRoute = { + path: 'picture/:id', + getChildRoutes (location, cb) { + let { state } = location + if (state && state.fromDashboard) + cb(null, [dashboardPictureRoute]) + else + cb(null, [pictureRoute]) + } +} +``` + + + +## Redirect +A `Redirect` sets up a redirect to another route in your application to +maintain old URLs. + +#### Props +##### `from` +The path you want to redirect from, including dynamic segments. + +##### `to` +The path you want to redirect to. + +##### `query` +By default, the query parameters will just pass through but you can +specify them if you need to. + +```js +// lets say we want to change from `/profile/123` to `/about/123` +// and redirect `/get-in-touch` to `/contact` + + + + {/* `/profile/123` -> `/about/123` */} + + +``` + +Note that the `` can be placed anywhere in the route hierarchy, though [normal precedence](/docs/guides/basics/RouteMatching.md#precedence) rules apply. If you'd prefer the redirects to be next to their respective routes, the `from` path will match the same as a regular route `path`. Currently, the `to` property of `` needs to be an absolute path. Pull requests welcome to make them handle relative paths too! + +```js + + + {/* /course/123/home -> /course/123/dashboard */} + + +``` + + +## IndexRoute +Index Routes allow you to provide a default "child" to a parent +route when visitor is at the url of the parent, they provide convention +for `` to work. + +Please see the [Index Routes guide](/docs/guides/basics/IndexRoutes.md) + +#### Props +All the same props as [Route](#route) except for `path`. + + + +## Handler Components +A route's handler component is rendered when that route matches the URL. The router will inject the following properties into your component when it's rendered: + +#### `isTransitioning` +A boolean value that is `true` when the router is transitioning, `false` otherwise. + +#### `location` +The current [location](https://github.com/rackt/history/blob/master/docs/Location.md). + +#### `params` +The dynamic segments of the URL. + +#### `route` +The route that rendered this component. + +#### `routeParams` +A subset of `this.props.params` that were directly specified in this component's route. For example, if the route's path is `users/:userId` and the URL is `/users/123/portfolios/345` then `this.props.routeParams` will be `{userId: '123'}`, and `this.props.params` will be `{userId: '123', portfolioId: 345}`. + +#### `children` +The matched child route elements to be rendered. + +##### Example +```js +React.render(( + + + + + + +), node) + +const App = React.createClass({ + render() { + return ( +
+ {/* this will be either or */} + {this.props.children} +
+ ) + } +}) +``` + +### Named Components +When a route has multiple components, the child elements are available by name on `this.props.children`. All route components can participate in the nesting. + +#### Example +```js +React.render(( + + + + + + + + +), node) + +const App = React.createClass({ + render() { + // the matched child route components become props in the parent + return ( +
+
+ {/* this will either be or */} + {this.props.children.main} +
+
+ {/* this will either be or */} + {this.props.children.sidebar} +
+
+ ) + } +}) + +const Users = React.createClass({ + render() { + return ( +
+ {/* if at "/users/123" this will be */} + {/* UsersSidebar will also get as this.props.children, + you pick where it renders */} + {this.props.children} +
+ ) + } +}) +``` + + + +## Mixins + +## Lifecycle Mixin +Adds a hook to your component instance that is called when the router is +about to navigate away from the route the component is configured on, +with the opportunity to cancel the transition. Mostly useful for forms +that are partially filled out. + +On standard transitions, `routerWillLeave` receives a single argument: the `location` we're transitioning to. To cancel the transition, return false. + +To prompt the user for confirmation, return a prompt message (string). `routerWillLeave` does not receive a location object during the beforeunload event in web browsers (assuming you're using the `useBeforeUnload` history enhancer). In this case, it is not possible for us to know the location we're transitioning to so `routerWillLeave` must return a prompt message to prevent the user from closing the tab. + +#### Lifecycle Methods +##### `routerWillLeave(nextLocation)` +Called when the router is attempting to transition away from the route +that rendered this component. + +##### arguments +- `nextLocation` - the next location + + + +## History Mixin +Adds the router's `history` object to your component instance. + +**Note**: You do not need this mixin for route components, its already +available as `this.props.history`. This is for components deeper in the +render tree that need access to the router's history object. + +#### Methods +##### `pushState(state, pathname, query)` +Transitions to a new URL. + +###### arguments +- `state` - the location state. +- `pathname` - the full url with or without the query. +- `query` - an object that will be stringified by the router. + +##### `replaceState(state, pathname, query)` +Replaces the current URL with a new one, without affecting the length of +the history (like a redirect). + +###### arguments +- `state` - the location state. +- `pathname` - the full url with or without the query. +- `query` - an object that will be stringified by the router. + +##### `go(n)` +Go forward or backward in the history by `n` or `-n`. + +##### `goBack()` +Go back one entry in the history. + +##### `goForward()` +Go forward one entry in the history. + +##### `createPath(pathname, query)` +Stringifies the query into the pathname, using the router's config. + +##### `createHref(pathname, query)` +Creates a URL, using the router's config. For example, it will add `#/` in +front of the `pathname` for hash history. + +##### `isActive(pathname, query)` +Returns `true` or `false` depending on if the current path is active. +Will be true for every route in the route branch matched by the +`pathname` (child route is active, therefore parent is too). + +###### arguments +- `pathname` - the full url with or without the query. +- `query` - an object that will be stringified by the router. + +#### Examples +```js +import { History } from 'react-router' + +React.createClass({ + + mixins: [ History ], + + render() { + return ( +
+
this.history.pushState(null, '/foo')}>Go to foo
+
this.history.replaceState(null, 'bar')}>Go to bar without creating a new history entry
+
this.history.goBack()}>Go back
+
+ ) + } +}) +``` + +Let's say you are using bootstrap and want to get `active` on those `li` +tags for the Tabs: + +```js +import { Link, History } from 'react-router' + +let Tab = React.createClass({ + + mixins: [ History ], + + render() { + let isActive = this.history.isActive(this.props.to, this.props.query) + let className = isActive ? 'active' : '' + return
    • + } + +}) + +// use it just like , and you'll get an anchor wrapped in an `li` +// with an automatic `active` class on both. +Foo +``` + +#### But I’m using Classes +> Notice how we never told you to use ES6 classes? :) + +https://twitter.com/soprano/status/610867662797807617 + +If you aren't happy using `createClass` for a handful of components in +your app for the sake of the `History` mixin, have a couple of options: + +- Pass `this.props.history` from your route components down to the + components that need it. + +- Use context + +```js +import PropTypes from 'react-router' +class MyComponent extends React.Component { + doStuff () { + this.context.history.pushState(null, '/some/path') + } +} +MyComponent.contextTypes = { history: PropTypes.history } +``` + +- [Make your history a module](/docs/guides/advanced/NavigatingOutsideOfComponents.md) + +- Create a higher order component, we might end up shipping with this + and deprecating history, just haven't had the time to think it through + all the way. + +```js +function connectHistory (Component) { + return React.createClass({ + mixins: [ History ], + render () { + return + } + }) +} + +// other file +import connectHistory from './connectHistory' + +class MyComponent extends React.Component { + doStuff () { + this.props.history.pushState(null, '/some/where') + } +} + +export default connectHistory(MyComponent) +``` + + + +## RouteContext Mixin +The RouteContext mixin provides a convenient way for route components to set the route in context. This is needed for routes that render elements that want to use the [Lifecycle mixin](#lifecycle) to prevent transitions. + +It simply adds `this.context.route` to your component. + + + +## Utilities + +## `useRoutes(createHistory)` +Returns a new createHistory function that may be used to create history objects that know about routing. + +- isActive(pathname, query) +- registerRouteHook(route, (location) => {}) +- unregisterRouteHook(route, (location) => {}) +- match(location, (error, nextState, nextLocation) => {}) +- listen((error, nextState) => {}) + + + +## `createRoutes(routes)` + +Creates and returns an array of routes from the given object which may be a JSX route, a plain object route, or an array of either. + +#### params +##### `routes` +One or many [`Routes`](#route) or [`PlainRoutes`](#plainRoute). + + +## PropTypes +Coming so soon! diff --git a/docs/Glossary.md b/docs/Glossary.md index 58276e7a92..b6db0bf629 100644 --- a/docs/Glossary.md +++ b/docs/Glossary.md @@ -2,6 +2,28 @@ This is a glossary of common terms used in the React Router codebase and documentation listed in alphabetical order, along with their [type signatures](http://flowtype.org/docs/quick-reference.html). +* [Action](#action) +* [Component](#component) +* [EnterHook](#enterhook) +* [LeaveHook](#leavehook) +* [Location](#location) +* [LocationKey](#locationkey) +* [LocationState](#locationstate) +* [Path](#path) +* [Pathname](#pathname) +* [Params](#params) +* [Query](#query) +* [QueryString](#querystring) +* [RedirectFunction](#redirectfunction) +* [Route](#route) +* [RouteComponent](#routecomponent) +* [RouteConfig](#routeconfig) +* [RouteHook](#routehook) +* [RoutePattern](#routepattern) +* [Router](#router) +* [RouterListener](#routerlistener) +* [RouterState](#routerstate) + ## Action ```js diff --git a/docs/Introduction.md b/docs/Introduction.md index 2e501d99c7..84a0ea693c 100644 --- a/docs/Introduction.md +++ b/docs/Introduction.md @@ -216,8 +216,8 @@ const Message = React.createClass({ }) ``` -You can also access parameters from the query string. If you for instance visit `/foo?bar=baz`, you can access `this.props.location.query.bar` to get the value `"baz"` from your Route component. +You can also access parameters from the query string. If you for instance visit `/foo?bar=baz`, you can access `this.props.location.query.bar` to get the value `"baz"` from your Route component. That's the gist of React Router. Application UIs are boxes inside of boxes inside of boxes; now you can keep those boxes in sync with the URL and link to them easily. -The docs about [route configuration](/docs/basics/RouteConfiguration.md) describe more of the router's features in depth. +The docs about [route configuration](/docs/guides/basics/RouteConfiguration.md) describe more of the router's features in depth. diff --git a/docs/README.md b/docs/README.md index bd8cef46fb..ec62f70fbb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,35 +1,9 @@ ## Table of Contents -* [Read Me](/README.md) * [Introduction](/docs/Introduction.md) -* [Basics](/docs/basics/README.md) - * [Route Configuration](/docs/basics/RouteConfiguration.md) - * [Route Matching](/docs/basics/RouteMatching.md) - * [Histories](/docs/basics/Histories.md) -* [Advanced](/docs/advanced/README.md) - * [Dynamic Routing](/docs/advanced/DynamicRouting.md) - * [Confirming Navigation](/docs/advanced/ConfirmingNavigation.md) - * [Server Rendering](/docs/advanced/ServerRendering.md) - * [Component Lifecycle](/docs/advanced/ComponentLifecycle.md) - * [Navigating Outside of Components](/docs/advanced/NavigatingOutsideOfComponents.md) +* [Basics](/docs/guides/basics/README.md) +* [Advanced Usage](/docs/guides/advanced/README.md) * [Upgrade Guide](/UPGRADE_GUIDE.md) * [Troubleshooting](/docs/Troubleshooting.md) +* [API](/docs/API.md) * [Glossary](/docs/Glossary.md) -* [API Reference](/docs/api/README.md) - * [Components](/docs/api/README.md#components) - * [Router](/docs/api/Router.md) - * [Link](/docs/api/Link.md) - * [IndexLink](/docs/api/IndexLink.md) - * [RoutingContext](/docs/api/RoutingContext.md) - * [Configuration components](/docs/api/README.md#configuration-components) - * [Route](/docs/api/Route.md) - * [Redirect](/docs/api/Redirect.md) - * [IndexRoute](/docs/api/IndexRoute.md) - * [Mixins](/docs/api/README.md#mixins) - * [Lifecycle](/docs/api/Lifecycle.md) - * [History](/docs/api/History.md) - * [RouteContext](/docs/api/RouteContext.md) - * [Utilities](/docs/api/README.md#utilities) - * [useRoutes](/docs/api/useRoutes.md) - * [createRoutes](/docs/api/createRoutes.md) - * [PropTypes](/docs/api/PropTypes.md) diff --git a/docs/api/History.md b/docs/api/History.md deleted file mode 100644 index 780f4cdcdb..0000000000 --- a/docs/api/History.md +++ /dev/null @@ -1,158 +0,0 @@ -# History Mixin - -Adds the router's `history` object to your component instance. - -**Note**: You do not need this mixin for route components, its already -available as `this.props.history`. This is for components deeper in the -render tree that need access to the router's history object. - -### Methods - -#### `pushState(state, pathname, query)` - -Transitions to a new URL. - -##### arguments - -- `state` - the location state. -- `pathname` - the full url with or without the query. -- `query` - an object that will be stringified by the router. - -#### `replaceState(state, pathname, query)` - -Replaces the current URL with a new one, without affecting the length of -the history (like a redirect). - -##### arguments - -- `state` - the location state. -- `pathname` - the full url with or without the query. -- `query` - an object that will be stringified by the router. - -#### `go(n)` - -Go forward or backward in the history by `n` or `-n`. - -#### `goBack()` - -Go back one entry in the history. - -#### `goForward()` - -Go forward one entry in the history. - -#### `createPath(pathname, query)` - -Stringifies the query into the pathname, using the router's config. - -#### `createHref(pathname, query)` - -Creates a URL, using the router's config. For example, it will add `#/` in -front of the `pathname` for hash history. - -#### `isActive(pathname, query)` - -Returns `true` or `false` depending on if the current path is active. -Will be true for every route in the route branch matched by the -`pathname` (child route is active, therefore parent is too). - -##### arguments - -- `pathname` - the full url with or without the query. -- `query` - an object that will be stringified by the router. - -### Examples - -```js -import { History } from 'react-router' - -React.createClass({ - - mixins: [ History ], - - render() { - return ( -
    -
    this.history.pushState(null, '/foo')}>Go to foo
    -
    this.history.replaceState(null, 'bar')}>Go to bar without creating a new history entry
    -
    this.history.goBack()}>Go back
    -
    - ) - } -}) -``` - -Let's say you are using bootstrap and want to get `active` on those `li` -tags for the Tabs: - -```js -import { Link, History } from 'react-router' - -let Tab = React.createClass({ - - mixins: [ History ], - - render() { - let isActive = this.history.isActive(this.props.to, this.props.query) - let className = isActive ? 'active' : '' - return
    • - } - -}) - -// use it just like , and you'll get an anchor wrapped in an `li` -// with an automatic `active` class on both. -Foo -``` - -### But I’m using Classes - -> Notice how we never told you to use ES6 classes? :) - -https://twitter.com/soprano/status/610867662797807617 - -If you aren't happy using `createClass` for a handful of components in -your app for the sake of the `History` mixin, have a couple of options: - -- Pass `this.props.history` from your route components down to the - components that need it. - -- Use context - -```js -import PropTypes from 'react-router' -class MyComponent extends React.Component { - doStuff () { - this.context.history.pushState(null, '/some/path') - } -} -MyComponent.contextTypes = { history: PropTypes.history } -``` - -- [Make your history a module](/docs/advanced/NavigatingOutsideOfComponents.md) - -- Create a higher order component, we might end up shipping with this - and deprecating history, just haven't had the time to think it through - all the way. - -```js -function connectHistory (Component) { - return React.createClass({ - mixins: [ History ], - render () { - return - } - }) -} - -// other file -import connectHistory from './connectHistory' - -class MyComponent extends React.Component { - doStuff () { - this.props.history.pushState(null, '/some/where') - } -} - -export default connectHistory(MyComponent) -``` diff --git a/docs/api/IndexLink.md b/docs/api/IndexLink.md deleted file mode 100644 index f85eae5710..0000000000 --- a/docs/api/IndexLink.md +++ /dev/null @@ -1 +0,0 @@ -# IndexLink \ No newline at end of file diff --git a/docs/api/IndexRoute.md b/docs/api/IndexRoute.md deleted file mode 100644 index 75d2abf238..0000000000 --- a/docs/api/IndexRoute.md +++ /dev/null @@ -1,14 +0,0 @@ -# IndexRoute - -Index Routes allow you to provide a default "child" to a parent -route when visitor is at the url of the parent, they provide convention -for `` to work. - -Please see the [Index Routes guide](../basics/IndexRoutes.md) - -### Props - -All the same props as [Route](./Route.md) except for `path`. - - - diff --git a/docs/api/Lifecycle.md b/docs/api/Lifecycle.md deleted file mode 100644 index 58f370b0b5..0000000000 --- a/docs/api/Lifecycle.md +++ /dev/null @@ -1,21 +0,0 @@ -# Lifecycle Mixin - -Adds a hook to your component instance that is called when the router is -about to navigate away from the route the component is configured on, -with the opportunity to cancel the transition. Mostly useful for forms -that are partially filled out. - -On standard transitions, `routerWillLeave` receives a single argument: the `location` we're transitioning to. To cancel the transition, return false. - -To prompt the user for confirmation, return a prompt message (string). `routerWillLeave` does not receive a location object during the beforeunload event in web browsers (assuming you're using the `useBeforeUnload` history enhancer). In this case, it is not possible for us to know the location we're transitioning to so `routerWillLeave` must return a prompt message to prevent the user from closing the tab. - -### Lifecycle Methods - -#### `routerWillLeave(nextLocation)` - -Called when the router is attempting to transition away from the route -that rendered this component. - -#### arguments - -- `nextLocation` - the next location \ No newline at end of file diff --git a/docs/api/Link.md b/docs/api/Link.md deleted file mode 100644 index 7b0890fe0c..0000000000 --- a/docs/api/Link.md +++ /dev/null @@ -1,58 +0,0 @@ -# Link - -The primary way to allow users to navigate around your application. -`Link` will render a fully accessible anchor tag with the proper href. - -A `Link` also knows when the route it links to is active and automatically -applies its `activeClassName` and/or `activeStyle` when it is. - -### Props - -#### `to` - -The path to link to, e.g., `/users/123`. - -#### `query` - -An object of key:value pairs to be stringified. - -#### `state` - -State to persist to the `location`. - -#### `activeClassName` - -The className a `Link` receives when its route is active. No active class by default. - -#### `activeStyle` - -The styles to apply to the link element when its route is active. - -#### `onClick` - -A custom handler for the click event. Works just like a handler on an `` -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 `` such as a title, id, className, etc. - -### Example - -Given a route like ``: - -```js -{user.name} -// becomes one of these depending on your History and if the route is -// active -Michael -Michael - -// change the activeClassName -{user.name} - -// change style when link is active -Users -``` diff --git a/docs/api/PlainRoute.md b/docs/api/PlainRoute.md deleted file mode 100644 index 748994ef82..0000000000 --- a/docs/api/PlainRoute.md +++ /dev/null @@ -1,59 +0,0 @@ -# Plain Route - -A plain JavaScript object route definition. `Router` turns JSX -``s into these objects, but you can use them directly if you -prefer. All of the props are the same as `` props, except -those listed here. - -### Props - -#### `childRoutes` - -An array of child routes, same as `children` in JSX route configs. - -#### `getChildRoutes(location, callback)` - -Same as `childRoutes` but asynchronous and receives the `location`. -Useful for code-splitting and dynamic route matching (given some state -or session data to return a different set of child routes). - -##### `callback` signature - -`cb(err, routesArray)` - -### Examples - -```js -let myRoute = { - path: 'course/:courseId', - childRoutes: [ - announcementsRoute, - gradesRoute, - assignmentsRoute - ] -} - -// async child routes -let myRoute = { - path: 'course/:courseId', - getChildRoutes (location, cb) { - // do asynchronous stuff to find the child routes - cb(null, [announcementsRoute, gradesRoute, assignmentsRoute]) - } -} - -// navigation dependent child routes -// can link with some state - - -let myRoute = { - path: 'picture/:id', - getChildRoutes (location, cb) { - let { state } = location - if (state && state.fromDashboard) - cb(null, [dashboardPictureRoute]) - else - cb(null, [pictureRoute]) - } -} -``` diff --git a/docs/api/PropTypes.md b/docs/api/PropTypes.md deleted file mode 100644 index a4e056ca24..0000000000 --- a/docs/api/PropTypes.md +++ /dev/null @@ -1 +0,0 @@ -# PropTypes \ No newline at end of file diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index dcb0180443..0000000000 --- a/docs/api/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# API Reference - -#### Components - -* [Router](Router.md) -* [Link](Link.md) -* [IndexLink](IndexLink.md) -* [RoutingContext](RoutingContext.md) - -#### Configuration components - -* [Route](Route.md) -* [Redirect](Redirect.md) -* [IndexRoute](IndexRoute.md) - -#### Mixins - -* [Lifecycle](Lifecycle.md) -* [History](History.md) -* [RouteContext](RouteContext.md) - -#### Utilities - -* [useRoutes](useRoutes.md) -* [createRoutes](createRoutes.md) -* [PropTypes](PropTypes.md) diff --git a/docs/api/Redirect.md b/docs/api/Redirect.md deleted file mode 100644 index 09d735b1ed..0000000000 --- a/docs/api/Redirect.md +++ /dev/null @@ -1,42 +0,0 @@ -# Redirect - -A `Redirect` sets up a redirect to another route in your application to -maintain old URLs. - -### Props - -#### `from` - -The path you want to redirect from, including dynamic segments. - -#### `to` - -The path you want to redirect to. - -#### `query` - -By default, the query parameters will just pass through but you can -specify them if you need to. - -### Example - -```js -// lets say we want to change from `/profile/123` to `/about/123` -// and redirect `/get-in-touch` to `/contact` - - - - {/* `/profile/123` -> `/about/123` */} - - -``` - -Note that the `` can be placed anywhere in the route hierarchy, though [normal precedence](../basics/RouteMatching.md#precedence) rules apply. If you'd prefer the redirects to be next to their respective routes, the `from` path will match the same as a regular route `path`. Currently, the `to` property of `` needs to be an absolute path. Pull requests welcome to make them handle relative paths too! - -```js - - - {/* /course/123/home -> /course/123/dashboard */} - - -``` diff --git a/docs/api/Route.md b/docs/api/Route.md deleted file mode 100644 index c58ba458c2..0000000000 --- a/docs/api/Route.md +++ /dev/null @@ -1,144 +0,0 @@ -# Route - -A `Route` is used to declaratively map routes to your application's -component hierarchy. - -### Props - -#### `path` - -The path used in the URL. - -It will concat with the parent route's path unless it starts with `/`, -making it an absolute path. - -**Note**: Absolute paths may not be used in route config that is [dynamically loaded](/docs/advanced/DynamicRouting.md). - -If left undefined, the router will try to match the child routes. - -#### `component` - -A single component to be rendered when the route matches the url. It can -be rendered by the parent route component with `this.props.children`. - -```js -const routes = ( - - - - -) - -const App = React.createClass({ - render () { - return ( -
    - {/* this will be either or */} - {this.props.children} -
    - ) - } -}) -``` - -#### `components` - -Routes can define multiple components as an object of `name:component` -pairs to be rendered when the path matches the url. They can be rendered -by the parent route component with `this.props.children[name]`. - -##### Example - -```js -// think of it outside the context of the router, if you had pluggable -// portions of your `render`, you might do it like this -, sidebar: }}/> - -// So with the router it looks like this: -const routes = ( - - - - - - -) - -const App = React.createClass({ - render () { - const { main, sidebar } = this.props.children - return ( -
    -
    - {main} -
    -
    - {sidebar} -
    -
    - ) - } -}) - -const Users = React.createClass({ - render () { - return ( -
    - {/* if at "/users/123" `children` will be */} - {/* UsersSidebar will also get as this.props.children, - so its a little weird, but you can decide which one wants - to continue with the nesting */} - {this.props.children} -
    - ) - } -}) -``` - -#### `getComponent(location, callback)` - -Same as `component` but asynchronous, useful for -code-splitting. - -##### `callback` signature - -`cb(err, component)` - -##### Example - -```js - { - // do asynchronous stuff to find the components - cb(null, Course) -}}/> -``` - -#### `getComponents(location, callback)` - -Same as `components` but asynchronous, useful for -code-splitting. - -##### `callback` signature - -`cb(err, components)` - -##### Example - -```js - { - // do asynchronous stuff to find the components - cb(null, {sidebar: CourseSidebar, content: Course}) -}}/> -``` - -#### `children` - -Routes can be nested, `this.props.children` will contain the element created from the child route component. Please refer to the [Route Configuration](/docs/basics/RouteConfiguration.md) since this is a very critical part of the router's design. - -#### `onEnter(nextState, replaceState)` - -Called when a route is about to be entered. It provides the next router state and a function to redirect to another path. - -#### `onLeave()` - -Called when a route is about to be exited. diff --git a/docs/api/RouteComponent.md b/docs/api/RouteComponent.md deleted file mode 100644 index e586c3609c..0000000000 --- a/docs/api/RouteComponent.md +++ /dev/null @@ -1,101 +0,0 @@ -# Route Component - -A route's component is rendered when that route matches the URL. The router will inject the following properties into your component when it's rendered: - -### `isTransitioning` - -A boolean value that is `true` when the router is transitioning, `false` otherwise. - -### `location` - -The current [location](https://github.com/rackt/history/blob/master/docs/Location.md). - -### `params` - -The dynamic segments of the URL. - -### `route` - -The route that rendered this component. - -### `routeParams` - -A subset of `this.props.params` that were directly specified in this component's route. For example, if the route's path is `users/:userId` and the URL is `/users/123/portfolios/345` then `this.props.routeParams` will be `{userId: '123'}`, and `this.props.params` will be `{userId: '123', portfolioId: 345}`. - -### `children` - -The matched child route elements to be rendered. - -#### Example - -```js -React.render(( - - - - - - -), node) - -const App = React.createClass({ - render() { - return ( -
    - {/* this will be either or */} - {this.props.children} -
    - ) - } -}) -``` - -## Named Components - -When a route has multiple components, the child elements are available by name on `this.props.children`. All route components can participate in the nesting. - -### Example - -```js -React.render(( - - - - - - - - -), node) - -const App = React.createClass({ - render() { - // the matched child route components become props in the parent - return ( -
    -
    - {/* this will either be or */} - {this.props.children.main} -
    -
    - {/* this will either be or */} - {this.props.children.sidebar} -
    -
    - ) - } -}) - -const Users = React.createClass({ - render() { - return ( -
    - {/* if at "/users/123" this will be */} - {/* UsersSidebar will also get as this.props.children, - you pick where it renders */} - {this.props.children} -
    - ) - } -}) -``` diff --git a/docs/api/RouteContext.md b/docs/api/RouteContext.md deleted file mode 100644 index 73247af202..0000000000 --- a/docs/api/RouteContext.md +++ /dev/null @@ -1,6 +0,0 @@ -# RouteContext - -The RouteContext mixin provides a convenient way for route components to set the route in context. This is needed for routes that render elements that want to use the [Lifecycle mixin](/docs/api/Lifecycle.md) to prevent transitions. - -It simply adds `this.context.route` to your component. - diff --git a/docs/api/Router.md b/docs/api/Router.md deleted file mode 100644 index 6a62714670..0000000000 --- a/docs/api/Router.md +++ /dev/null @@ -1,72 +0,0 @@ -# Router - -Primary component of React Router. It keeps your UI and the URL in sync. - -### Props - -#### `children` (required) - -One or many [`Routes`](Route.md) or [Plain Routes](PlainRoute.md). When the -history changes, `Router` will match a branch of its [`Routes`](Route.md), -and render their configured [components](RouteComponent.md), with child -route components nested inside the parents. - -#### `routes` - -Alias for `children`. - -#### `history` - -The history the router should listen to from the `history` package. - -#### `createElement(Component, props)` - -When the router is ready to render a branch of route components, it will -use this function to create the elements. You may want to take control -of creating the elements when you're using some sort of data -abstraction, like setting up subscriptions to stores, or passing in some -sort of application module to each component via props. - -##### Examples - -```js - - -// default behavior -function createElement(Component, props) { - // make sure you pass all the props in! - return -} - -// maybe you're using something like Relay -function createElement(Component, props) { - // make sure you pass all the props in! - return -} -``` - -#### `stringifyQuery(queryObject)` - -A function used to convert an object from [`Link`](Link.md)s or calls to -[`transitionTo`](Navigation.md#transitiontopathname-query-state) to a URL query string. - -#### `parseQueryString(queryString)` - -A function used to convert a query string into an object that gets -passed to route component props. - -#### `onError(error)` - -While the router is matching, errors may bubble up, here -is your opportunity to catch and deal with them. Typically these will -come from async features like [`route.getComponents`](Route.md#getcomponentscallback) and -[`route.getChildRoutes`](PlainRoute.md#getchildrouteslocation-callback). - -#### `onUpdate()` - -Called whenever the router updates its state in response to URL changes. - -### Examples - -Please see the [`examples/`](/examples) directory of the repository for extensive -examples of using `Router`. diff --git a/docs/api/RoutingContext.md b/docs/api/RoutingContext.md deleted file mode 100644 index 8a72d89541..0000000000 --- a/docs/api/RoutingContext.md +++ /dev/null @@ -1,4 +0,0 @@ -# RoutingContext - -A `RoutingContext` renders the component tree for a given router state and sets the history object and the current location in context. - diff --git a/docs/api/createRoutes.md b/docs/api/createRoutes.md deleted file mode 100644 index 1ba71c11d6..0000000000 --- a/docs/api/createRoutes.md +++ /dev/null @@ -1,8 +0,0 @@ -# `createRoutes(routes)` - -Creates and returns an array of routes from the given object which may be a JSX route, a plain object route, or an array of either. - -### params - -#### `routes` -One or many [`Routes`](Route.md) or [Plain Routes](PlainRoute.md). \ No newline at end of file diff --git a/docs/api/useRoutes.md b/docs/api/useRoutes.md deleted file mode 100644 index 68bb4a6213..0000000000 --- a/docs/api/useRoutes.md +++ /dev/null @@ -1,9 +0,0 @@ -# `useRoutes(createHistory)` - -Returns a new createHistory function that may be used to create history objects that know about routing. - -- isActive(pathname, query) -- registerRouteHook(route, (location) => {}) -- unregisterRouteHook(route, (location) => {}) -- match(location, (error, nextState, nextLocation) => {}) -- listen((error, nextState) => {}) \ No newline at end of file diff --git a/docs/advanced/ComponentLifecycle.md b/docs/guides/advanced/ComponentLifecycle.md similarity index 100% rename from docs/advanced/ComponentLifecycle.md rename to docs/guides/advanced/ComponentLifecycle.md diff --git a/docs/advanced/ConfirmingNavigation.md b/docs/guides/advanced/ConfirmingNavigation.md similarity index 77% rename from docs/advanced/ConfirmingNavigation.md rename to docs/guides/advanced/ConfirmingNavigation.md index 6392a52006..757338aca4 100644 --- a/docs/advanced/ConfirmingNavigation.md +++ b/docs/guides/advanced/ConfirmingNavigation.md @@ -1,8 +1,8 @@ # Confirming Navigation -React Router provides a [`routerWillLeave` lifecycle hook](/docs/Glossary.md#routehook) that React [component](/docs/Glossary.md#component)s may use to prevent a transition from happening or to prompt the user before leaving a [route](/docs/Glossary.md#route). [`routerWillLeave`](/docs/api/Lifecycle.md#routerwillleavenextlocation) may either: +React Router provides a [`routerWillLeave` lifecycle hook](/docs/Glossary.md#routehook) that React [component](/docs/Glossary.md#component)s may use to prevent a transition from happening or to prompt the user before leaving a [route](/docs/Glossary.md#route). [`routerWillLeave`](/docs/API.md#routerwillleavenextlocation) may either: -1. `return false` to cancel the transition or +1. `return false` to cancel the transition or 2. `return` a prompt message that will prompt the user for confirmation before leaving the route. To install this hook, use the `Lifecycle` mixin in one of your [route component](/docs/Glossary.md#routecomponent)s. @@ -26,7 +26,7 @@ const Home = React.createClass({ }) ``` -If you need a [`routerWillLeave`](/docs/api/Lifecycle.md#routerwillleavenextlocation) hook in a deeply nested component, simply use the [`RouteContext`](/docs/api/RouteContext.md) mixin in your [route component](/docs/Glossary.md#routecomponent) to put the `route` in context. +If you need a [`routerWillLeave`](/docs/API.md#routerwillleavenextlocation) hook in a deeply nested component, simply use the [`RouteContext`](/docs/API.md#routecontext-mixin) mixin in your [route component](/docs/Glossary.md#routecomponent) to put the `route` in context. ```js import { Lifecycle, RouteContext } from 'react-router' diff --git a/docs/advanced/DynamicRouting.md b/docs/guides/advanced/DynamicRouting.md similarity index 72% rename from docs/advanced/DynamicRouting.md rename to docs/guides/advanced/DynamicRouting.md index 903983431f..53bd311ecb 100644 --- a/docs/advanced/DynamicRouting.md +++ b/docs/guides/advanced/DynamicRouting.md @@ -8,9 +8,9 @@ It's important that changes deep down in the application don't require changes a A router is the perfect place to handle code splitting: it's responsible for setting up your views. -React Router does all of its [path matching](/docs/basics/RouteMatching.md) and component fetching asynchronously, which allows you to not only load up the components lazily, *but also lazily load the route configuration*. You really only need one route definition in your initial bundle, the router can resolve the rest on demand. +React Router does all of its [path matching](/docs/guides/basics/RouteMatching.md) and component fetching asynchronously, which allows you to not only load up the components lazily, *but also lazily load the route configuration*. You really only need one route definition in your initial bundle, the router can resolve the rest on demand. -Routes may define [`getChildRoutes`](/docs/api/PlainRoute.md#getchildrouteslocation-callback) and [`getComponents`](/docs/api/Route.md#getcomponentscallback) methods. These are asynchronous and only called when needed. We call it "gradual matching". React Router will gradually match the URL and fetch only the amount of route configuration and components it needs to match the URL and render. +Routes may define [`getChildRoutes`](/docs/API.md#getchildrouteslocation-callback) and [`getComponents`](/docs/API.md#getcomponentslocation-callback) methods. These are asynchronous and only called when needed. We call it "gradual matching". React Router will gradually match the URL and fetch only the amount of route configuration and components it needs to match the URL and render. Coupled with a smart code splitting tool like [webpack](http://webpack.github.io/), a once tireless architecture is now simple and declarative. diff --git a/docs/advanced/NavigatingOutsideOfComponents.md b/docs/guides/advanced/NavigatingOutsideOfComponents.md similarity index 99% rename from docs/advanced/NavigatingOutsideOfComponents.md rename to docs/guides/advanced/NavigatingOutsideOfComponents.md index 04738d04f8..a439338f01 100644 --- a/docs/advanced/NavigatingOutsideOfComponents.md +++ b/docs/guides/advanced/NavigatingOutsideOfComponents.md @@ -31,4 +31,3 @@ flux actions file import history from './history' history.replaceState(null, '/some/path') ``` - diff --git a/docs/advanced/README.md b/docs/guides/advanced/README.md similarity index 93% rename from docs/advanced/README.md rename to docs/guides/advanced/README.md index ed4a048d58..16c11c8c62 100644 --- a/docs/advanced/README.md +++ b/docs/guides/advanced/README.md @@ -1,4 +1,4 @@ -# Advanced +# Advanced Usage * [Dynamic Routing](DynamicRouting.md) * [Confirming Navigation](ConfirmingNavigation.md) diff --git a/docs/advanced/ServerRendering.md b/docs/guides/advanced/ServerRendering.md similarity index 97% rename from docs/advanced/ServerRendering.md rename to docs/guides/advanced/ServerRendering.md index 23379beef5..8c9850f831 100644 --- a/docs/advanced/ServerRendering.md +++ b/docs/guides/advanced/ServerRendering.md @@ -7,7 +7,7 @@ to: - Send `30x` responses for redirects - Fetch data before rendering (and use the router to help you do it) -To facilitate these needs, you drop one level lower than the [``](/docs/api/Router.md) +To facilitate these needs, you drop one level lower than the [``](/docs/API.md#Router) API with: - `createLocation` from the history package @@ -41,4 +41,4 @@ serve((req, res) => { For data loading, you can use the `renderProps` argument to build whatever convention you want--like adding static `load` methods to your route components, or putting data loading functions on the routes, it's up to -you. \ No newline at end of file +you. diff --git a/docs/basics/Histories.md b/docs/guides/basics/Histories.md similarity index 99% rename from docs/basics/Histories.md rename to docs/guides/basics/Histories.md index b2d05bfa4b..c053cec523 100644 --- a/docs/basics/Histories.md +++ b/docs/guides/basics/Histories.md @@ -23,21 +23,18 @@ const createBrowserHistory = require('history/lib/createBrowserHistory') ``` ### `createHashHistory` - This is the default history you'll get if you don't specify a history at all (i.e. `{/* your routes */}`). It uses the hash (`#`) portion of the url creating routes that look like `example.com/#/some/path`. #### Should I use `createHashHistory`? - Hash history is the default because it works without any setup on your server, and works in all evergreen browsers and IE8+. But, we don't recommend using it in production, every web app should aspire to use `createBrowserHistory`. #### What is that `?_k=ckuvup` junk in the URL? - When a history transitions around your app with `pushState` or `replaceState`, it can store "location state" on the new location that doesn't show up in the URL, think of it a little bit like post data in @@ -51,14 +48,12 @@ in session storage. When the visitor clicks "back" and "forward" we now have a mechanism to restore the location state. ### `createBrowserHistory` - Browser history is the recommended history for browser application with React Router. It uses the [History](https://developer.mozilla.org/en-US/docs/Web/API/History) API built into the browser to manipulate the url, creating real urls that look like `example.com/some/path`. #### Configuring Your Server - Your server must be ready to handle real urls. When the app first loads at `/` it will probably work, but as the user navigates around and then hits refresh at `/accounts/23` your web server will get a request to @@ -87,7 +82,6 @@ console.log("server started on port " + port) ``` #### IE8, IE9 Support - We feature detect to see if we can use the browser's native `History` API, if not, any call to transition around the app will result in _a full page reload_, which allows you to build your app and have a better @@ -100,13 +94,11 @@ we end up with a terrible cartesian product of infinite potential urls. ### `createMemoryHistory` - Memory history doesn't manipulate or read from the address bar. This is how we implement server rendering, its also useful for testing and other rendering environments (like React Native). ## Example implementation - ```js import React from 'react'; import createBrowserHistory from 'history/lib/createBrowserHistory'; diff --git a/docs/basics/IndexRoutes.md b/docs/guides/basics/IndexRoutes.md similarity index 97% rename from docs/basics/IndexRoutes.md rename to docs/guides/basics/IndexRoutes.md index a043f02735..e8a67e30ac 100644 --- a/docs/basics/IndexRoutes.md +++ b/docs/guides/basics/IndexRoutes.md @@ -1,4 +1,4 @@ -# Index Route and Index Links +# Index Routes and Index Links ## Index Routes @@ -45,4 +45,3 @@ we'd like to link to `Home` but only be active if `Home` is rendered. To have a link to `/` that is only active when the `Home` route is rendered, use `Home`. - diff --git a/docs/basics/README.md b/docs/guides/basics/README.md similarity index 100% rename from docs/basics/README.md rename to docs/guides/basics/README.md diff --git a/docs/basics/RouteConfiguration.md b/docs/guides/basics/RouteConfiguration.md similarity index 93% rename from docs/basics/RouteConfiguration.md rename to docs/guides/basics/RouteConfiguration.md index 95505a7a29..7825880e02 100644 --- a/docs/basics/RouteConfiguration.md +++ b/docs/guides/basics/RouteConfiguration.md @@ -1,6 +1,6 @@ # Route Configuration -A [route configuration](/docs/Glossary.md#routeconfig) is basically a set of instructions that tell a router how to try to [match the URL](RouteMatching.md) and what code to run when it does. To illustrate some of the features available in your route config, let's expand on the simple app from [the introduction](/docs/introduction/README.md#adding-more-ui). +A [route configuration](/docs/Glossary.md#routeconfig) is basically a set of instructions that tell a router how to try to [match the URL](RouteMatching.md) and what code to run when it does. To illustrate some of the features available in your route config, let's expand on the simple app from [the introduction](/docs/Introduction.md#adding-more-ui). ```js import React from 'react' @@ -67,7 +67,7 @@ URL | Components ### Adding an Index -Imagine we'd like to render another component inside of `App` when the URL is `/`. Currently, `this.props.children` inside of `App`'s `render` method is `undefined` in this case. We can use an [``](/docs/api/IndexRoute.md) to specify a "default" page. +Imagine we'd like to render another component inside of `App` when the URL is `/`. Currently, `this.props.children` inside of `App`'s `render` method is `undefined` in this case. We can use an [``](/docs/API.md#indexroute) to specify a "default" page. ```js import { IndexRoute } from 'react-router' @@ -133,13 +133,13 @@ URL | Components `/inbox` | `App -> Inbox` `/messages/:id` | `App -> Inbox -> Message` -**Note**: Absolute paths may not be used in route config that is [dynamically loaded](/docs/advanced/DynamicRouting.md). +**Note**: Absolute paths may not be used in route config that is [dynamically loaded](/docs/guides/advanced/DynamicRouting.md). ### Preserving URLs Wait a minute ... we just changed a URL! [That's not cool](http://www.w3.org/Provider/Style/URI.html). Now everyone who had a link to `/inbox/messages/5` has a **broken link**. :( -Not to worry. We can use a [``](/docs/api/Redirect.md) to make sure that URL still works! +Not to worry. We can use a [``](/docs/API.md#redirect) to make sure that URL still works! ```js import { Redirect } from 'react-router' @@ -164,7 +164,7 @@ Now when someone clicks on that link to `/inbox/messages/5` they'll automaticall ### Enter and Leave Hooks -[Route](/docs/Glossary.md#route)s may also define [`onEnter`](/docs/Glossary.md#enterhook) and [`onLeave`](/docs/Glossary.md#leavehook) hooks that are invoked once a transition has been [confirmed](/docs/advanced/ConfirmingNavigation.md). These hooks are useful for various things like [requiring auth](https://github.com/rackt/react-router/tree/master/examples/auth-flow) when a route is entered and saving stuff to persistent storage before a route unmounts. +[Route](/docs/Glossary.md#route)s may also define [`onEnter`](/docs/Glossary.md#enterhook) and [`onLeave`](/docs/Glossary.md#leavehook) hooks that are invoked once a transition has been [confirmed](/docs/guides/advanced/ConfirmingNavigation.md). These hooks are useful for various things like [requiring auth](https://github.com/rackt/react-router/tree/master/examples/auth-flow) when a route is entered and saving stuff to persistent storage before a route unmounts. During a transition, [`onLeave` hooks](/docs/Glossary.md#leavehook) run first on all routes we are leaving, starting with the leaf route on up to the first common ancestor route. Next, [`onEnter` hooks](/docs/Glossary.md#enterhook) run starting with the first parent route we're entering down to the leaf route. diff --git a/docs/basics/RouteMatching.md b/docs/guides/basics/RouteMatching.md similarity index 98% rename from docs/basics/RouteMatching.md rename to docs/guides/basics/RouteMatching.md index ce8519c023..2390635539 100644 --- a/docs/basics/RouteMatching.md +++ b/docs/guides/basics/RouteMatching.md @@ -2,16 +2,14 @@ A [route](/docs/Glossary.md#route) has three attributes that determine whether or not it "matches" the URL: -1. [nesting](#nesting) and +1. [nesting](#nesting) and 2. its [`path`](#path-syntax) 3. its [precedence](#precedence) ### Nesting - React Router uses the concept of nested routes to let you declare nested sets of views that should be rendered when a given URL is invoked. Nested routes are arranged in a tree-like structure. To find a match, React Router traverses the [route config](/docs/Glossary.md#routeconfig) depth-first searching for a route that matches the URL. ### Path Syntax - A route path is [a string pattern](/docs/Glossary.md#routepattern) that is used to match a URL (or a portion of one). Route paths are interpreted literally, except for the following special symbols: - `:paramName` – matches a URL segment up to the next `/`, `?`, or `#`. The matched string is called a [param](/docs/Glossary.md#params) @@ -27,7 +25,6 @@ A route path is [a string pattern](/docs/Glossary.md#routepattern) that is used If a route uses a relative `path`, it builds upon the accumulated `path` of its ancestors. Nested routes may opt-out of this behavior by [using an absolute `path`](RouteConfiguration.md#decoupling-the-ui-from-the-url). ### Precedence - Finally, the routing algorithm attempts to match routes in the order they are defined, top to bottom. So, when you have two sibling routes you should be sure the first doesn't match all possible `path`s that can be matched by the later sibling. For example, **don't** do this: ```js