webappengine

<!doctype html><html lang="en"><head><meta charset="utf-8"><title>React Router Documentation</title><link rel="stylesheet" href="./styles.css"><link rel="stylesheet" href="./syntax.css"></head><body><main class="Main"><div class="Main__Content"><center><img src="./img/vertical.png" width="367" style="margin-bottom:40px;"></center>React Router is a complete routing solution designed specifically for <a href="https://facebook.github.io/react">React.js</a>. It painlessly synchronizes the components of your application with the URL, with first-class support for nesting, transitions, and server side rendering.<a href="https://github.com/rackt/react-router">Contribute on Github.</a><section><article class="Doc"><h1 class="Heading" id="Router Overview"><a class="HeadingLink" href="#Router Overview">Router Overview</a>Guides</h1><div>To illustrate the problems React Router is going to solve for you, let’s build a small application without it. <h2 id="without-react-router">Without React Router</h2> <pre><code class="lang-js"><div class="highlight"><pre>var About = React.createClass({ render: function () { return <h2>About</h2>; } }); var Inbox = React.createClass({ render: function () { return <h2>Inbox</h2>; } }); var Home = React.createClass({ render: function () { return <h2>Home</h2>; } }); var App = React.createClass({ render () { var Child; switch (this.props.route) { case 'about': Child = About; break; case 'inbox': Child = Inbox; break; default: Child = Home; } return ( <div> <h1>App</h1> <Child/> </div> ) } }); function render () { var route = window.location.hash.substr(1); React.render(<App route={route} />, document.body); } window.addEventListener('hashchange', render); render(); // render initially </pre></div> </code></pre> As the hash portion of the URL changes, <code>App</code> will render a different <code><Child/></code> by branching on <code>this.props.route</code>. Pretty straightforward stuff. But it gets complicated fast. Imagine now that <code>Inbox</code> has some nested UI at a path like <code>inbox/messages/:id</code> and <code>inbox/unread</code>, etc. We'll need to make our url parsing much more intelligent to be able to pass the right information to <code>App</code>, and then to <code>Inbox</code> in order for it to know which URL-mapped child component it should render. We'd then have a branch of components that should be rendered at any given URL. Add a few more of these branches and we'll end up with a lot of code to keep the URL and our application's component hierarchy in sync. <h2 id="with-react-router">With React Router</h2> Nested URLs and nested component hierarchy are at the heart of React Router. Lets make our routing for our little app declarative. We use JSX for route configuration because we want to define a view hierarchy with properties, so its a pefect fit. <pre><code class="lang-js"><div class="highlight"><pre>var Router = require('react-router'); var Route = Router.Route; // declare our routes and their hierarchy var routes = ( <Route handler={App}> <Route path="about" handler={About}/> <Route path="inbox" handler={Inbox}/> </Route> ); </pre></div> </code></pre> Next we need to delete some code from <code>App</code>. We'll replace <code><Child/></code> with <code><RouteHandler/></code> that functions as the old <code>switch</code> block from before. <pre><code class="lang-js"><div class="highlight"><pre>var RouteHandler = Router.RouteHandler; var App = React.createClass({ render () { return ( <div> <h1>App</h1> <RouteHandler/> </div> ) } }); </pre></div> </code></pre> Finally we need to listen to the url and render the application. <pre><code class="lang-js"><div class="highlight"><pre>Router.run(routes, Router.HashLocation, (Root) => { React.render(<Root/>, document.body); }); </pre></div> </code></pre> <code>Root</code> is a component that bakes in the matched component hierarchy making <code>RouteHandler</code> know what to render. Note that <code><Route/></code> components are not ever rendered, they are just configuration objects that the router uses to create an internal tree of routes. <h2 id="adding-more-ui">Adding more UI</h2> Alright, now we're ready to nest the inbox messages inside the inbox UI. First we'll make a new <code>Message</code> component and then we'll add the route under <code>inbox</code> so that the UI will nest. <pre><code class="lang-js"><div class="highlight"><pre>var Message = React.createClass({ render () { return <h3>Message</h3>; } }); var routes = ( <Route handler={App}> <Route path="about" handler={About}/> <Route path="inbox" handler={Inbox}> <Route path="messages/:id" handler={Message}/> </Route> </Route> ); </pre></div> </code></pre> Now visits to urls like <code>inbox/messages/Jkei3c32</code> will match the new route and nest the UI branch of <code>App -> Inbox -> Message</code>. <h2 id="getting-the-url-parameters">Getting the url parameters</h2> We're going to need to know something about the message in order to fetch it from the server. We call the component you hand to a <code><Route/></code> a <code>RouteHandler</code>. <code>RouteHandler</code> instances get some useful properties injected into them when you render, particularly the parameters from the dynamic segment of your path. In our case, <code>:id</code>. <pre><code class="lang-js"><div class="highlight"><pre>var Message = React.createClass({ componentDidMount: function () { // from the path `/inbox/messages/:id` var id = this.props.params.id; fetchMessage(id, function (err, message) { this.setState({ message: message }); }) }, // ... }); </pre></div> </code></pre> <h2 id="nested-ui-and-nested-urls-need-not-be-coupled">Nested UI and Nested URLs need not be coupled</h2> With React Router, you don't need to nest your UI in order to get a nested URL. Inversely, to get nested UI, you don't need to have nested URLs either. Lets make a new url at <code>/about/company</code>, but without nesting the UI inside of the <code>About</code> component. <pre><code class="lang-js"><div class="highlight"><pre>var routes = ( <Route handler={App}> <Route path="about" handler={About}/> <Route path="about/company" handler={Company}/> </Route> ); </pre></div> </code></pre> Though our url is nested, the UI of <code>About</code> and <code>Company</code> are siblings. Now lets go the other way and add the url <code>/archive/messages/:id</code> and have it nested under our inbox UI even though the URL is not nested. We have to do three things for this to work: <ol> <li>Start the path with <code>/</code> to signal that its an absolute path. This won’t “inherit” the parent path the way <code>inbox/messages/:id</code> gets inherited.</li> <li>Nest the <code><Route/></code> under the <code>inbox</code> route to cause the UI to nest.</li> <li>Ensure you have all the necessary dynamic segments, we only have <code>:id</code> so its pretty easy.</li> </ol> <pre><code class="lang-js"><div class="highlight"><pre>var routes = ( <Route handler={App}> <Route path="inbox" handler={Inbox}> <Route path="messages/:id" handler={Message}/> <Route path="/archive/messages/:id" handler={Message}/> </Route> </Route> ); </pre></div> </code></pre> 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. </div></article></section><section><article class="Doc"><h1 class="Heading" id="DefaultRoute"><a class="HeadingLink" href="#DefaultRoute">DefaultRoute</a>Route Configuration</h1><div>A <code>DefaultRoute</code> will be the matched child route when the parent's path matches exactly. You'd want to use this to ensures a child <code>RouteHandler</code> is always rendered when there is no child match. Think of it like <code>index.html</code> in a directory of a static html server. <h2 id="props">Props</h2> <h3 id="-handler-"><code>handler</code></h3> The <code>RouteHandler</code> component you want to be rendered when the route is matched. <h3 id="-name-optional-"><code>name</code> (optional)</h3> The name of the route used when linking or transitioning to the route. <h2 id="example">Example</h2> <pre><code class="lang-xml"><div class="highlight"><pre><Route path="/" handler={App}>  <DefaultRoute handler={Home}/> <Route name="about" handler={About}/> <Route name="users" handler={Users}> <Route name="user" handler={User} path="/user/:id"/>  <DefaultRoute name="users-index" handler={UsersIndex}/> </Route> </Route> </pre></div> </code></pre> </div></article><article class="Doc"><h1 class="Heading" id="NotFoundRoute"><a class="HeadingLink" href="#NotFoundRoute">NotFoundRoute</a>Route Configuration</h1><div>A <code>NotFoundRoute</code> is active when the beginning of its parent's path matches the URL but none of its siblings do. It can be found at any level of your hierarchy, allowing you to have a context-aware "not found" screens. You'd want to use this to handle bad links and users typing invalid urls into the address bar. Note: This is not intended to be used for when a resource is not found. There is a difference between the router not finding a matched path and a valid URL that results in a resource not being found. The url <code>courses/123</code> is a valid url and results in a matched route, therefore it was "found" as far as routing is concerned. Then, if we fetch some data and discover that the course <code>123</code> does not exist, we do not want to transition to a new route. Just like on the server, you go ahead and serve the url but render different UI (and use a different status code). You shouldn't ever try to transition to a <code>NotFoundRoute</code>. <h2 id="props">Props</h2> <h3 id="-handler-"><code>handler</code></h3> The <code>RouteHandler</code> component you want to be rendered when the route is matched. <h2 id="example">Example</h2> <pre><code class="lang-xml"><div class="highlight"><pre><Route path="/" handler={App}> <Route name="course" path="course/:courseId" handler={Course}> <Route name="course-dashboard" path="dashboard" handler={Dashboard}/>  <NotFoundRoute handler={CourseRouteNotFound} /> </Route>  <NotFoundRoute handler={NotFound} /> </Route> </pre></div> </code></pre> The last <code>NotFoundRoute</code> will render inside the <code>App</code>, the first will rendering inside of <code>Course</code>. </div></article><article class="Doc"><h1 class="Heading" id="Redirect"><a class="HeadingLink" href="#Redirect">Redirect</a>Route Configuration</h1><div>A <code>Redirect</code> sets up a redirect to another route in your application to maintain old URLs. <h2 id="props">Props</h2> <h3 id="-from-"><code>from</code></h3> The path you want to redirect from, including dynamic segments. Defaults to <code>*</code> so you can redirect anything not found to somewhere else. <h3 id="-to-"><code>to</code></h3> The <code>name</code> of the route you want to redirect to. <h3 id="-params-"><code>params</code></h3> By default, the parameters will just pass through to the new route, but you can specify them if you need to (usually you shouldn't). <h3 id="-query-"><code>query</code></h3> By default, the query parameters will just pass through to the new route, but you can specify them if you need to (usually you shouldn't). <h2 id="example">Example</h2> <pre><code class="lang-xml"><div class="highlight"><pre> <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}/> </Route>  <Redirect from="get-in-touch" to="contact" />  <Redirect from="profile/:userId" to="about-user" />  <Redirect from="profile/me" to="about-user" params={{userId: SESSION.USER_ID}} /> </Route> </pre></div> </code></pre> Note that the <code><Redirect/></code> can be placed anywhere in the route hierarchy, if you'd prefer the redirects to be next to their respective routes, the <code>from</code> path will match the same as a regular route <code>path</code>. <pre><code class="lang-xml"><div class="highlight"><pre><Route handler={App}> <Route name="course" path="course/:courseId"> <Route name="course-dashboard" path="dashboard" handler={Dashboard}/>  <Redirect from="home" to="course-dashboard" /> </Route> </Route> </pre></div> </code></pre> </div></article><article class="Doc"><h1 class="Heading" id="Route"><a class="HeadingLink" href="#Route">Route</a>Route Configuration</h1><div>A <code>Route</code> is used to declaratively map routes to your application's screen hiearchy. <h2 id="props">Props</h2> <h3 id="-name-optional-"><code>name</code> (optional)</h3> The unique name of the route, used in the <code>Link</code> component and the router's transition methods. <h3 id="-path-optional-"><code>path</code> (optional)</h3> The path used in the URL. If left undefined, the path will be defined by the <code>name</code>, and if there is no name, will default to <code>/</code>. Please refer to the <a href="#TODO">Path Matching Guide</a> to learn more about supported path matching syntax. <h3 id="-handler-"><code>handler</code></h3> The <code>RouteHandler</code> component to be rendered when the route is active. <h3 id="-children-"><code>children</code></h3> Routes can be nested. When a child route path matches, the parent route is also activated. Please refer to the <a href="#TODO">overview</a> since this is a very critical part of the router's design. <h3 id="-ignorescrollbehavior-"><code>ignoreScrollBehavior</code></h3> When a route or its <code>params</code> change, the router adjusts window scroll position according to the [<code>scrollBehavior</code>][scrollbehavior]. This is generally desirable but you might want to opt-out of scrolling adjustment for a specific route or a group of routes. If you specify <code>ignoreScrollBehavior</code>, changes in <code>params</code> or any transitions within its <code>children</code> will not adjust scroll position. This can be useful on a search page or in a tabbed interface. Note that changes in <code>query</code> never adjust scroll position, regardless of the value of this attribute. <h2 id="example">Example</h2> <pre><code class="lang-xml"><div class="highlight"><pre> <Route handler={App}>  <Route name="about" handler={About}/> <Route name="users" handler={Users}>  <Route name="user" handler={User} path="/user/:id"/> </Route> </Route> </pre></div> </code></pre> </div></article></section><section><article class="Doc"><h1 class="Heading" id="Router.create"><a class="HeadingLink" href="#Router.create">Router.create</a>Top-Level</h1><div>Creates a new router. Useful to pass around your app to be able to call <code>transitionTo</code> and friends w/o being inside of a component. <h2 id="signature">Signature</h2> <code>Router.create(options)</code> <h2 id="options">Options</h2> <h3 id="-routes-"><code>routes</code></h3> <h3 id="-location-"><code>location</code></h3> <h3 id="-scrollbehavior-"><code>scrollBehavior</code></h3> <h3 id="-onabort-"><code>onAbort</code></h3> Used server-side to know when a route was redirected. <h2 id="methods">Methods</h2> <h3 id="-run-callback-"><code>run(callback)</code></h3> Runs the router, the same as <code>Router.run</code>. <h2 id="example">Example</h2> <pre><code class="lang-js"><div class="highlight"><pre>// the more common API is Router.run(routes, Router.HistoryLocation, callback); // which is just a shortcut for var router = Router.create({ routes: routes, location: Router.HistoryLocation }); router.run(callback); </pre></div> </code></pre> </div></article><article class="Doc"><h1 class="Heading" id="Router.run"><a class="HeadingLink" href="#Router.run">Router.run</a>Top-Level</h1><div>The main API into react router. It runs your routes, matching them against a location, and then calls back with the next state for you to render. <h2 id="signature">Signature</h2> <code>Router.run(routes, [location,] callback)</code> <h2 id="arguments">Arguments</h2> <h3 id="-routes-"><code>routes</code></h3> Your route config. See <a href="#TODO">Route</a> <h3 id="-location-optional"><code>location</code> optional</h3> Defaults to <code>Router.HashLocation</code>. If given a <code>Location</code> object, it will setup and listen for changes on it, if given a string path, the router will immediately match that path and callback. <h4 id="examples">Examples</h4> <pre><code class="lang-js"><div class="highlight"><pre>// Defaults to `Router.HashLocation` // callback is called whenever the hash changes Router.run(routes, callback); // HTML5 History // callback is called when history events happen Router.run(routes, Router.HistoryLocation, callback); // Server rendering // callback is called once, immediately. Router.run(routes, '/some/path', callback); </pre></div> </code></pre> <h3 id="-callback-root-state-"><code>callback(Root, state)</code></h3> The callback receives two arguments: <ol> <li><code>Root</code></li> <li><code>state</code></li> </ol> <h4 id="-root-"><code>Root</code></h4> A ReactComponent class with the current match all wrapped up inside it, ready for you to render. <h4 id="-state-"><code>state</code></h4> An object containing the matched state. <h4 id="-state-path-"><code>state.path</code></h4> The current URL path with query string. <h4 id="-state-action-"><code>state.action</code></h4> The action that lead to the route change. <h4 id="-state-pathname-"><code>state.pathname</code></h4> The current URL path without the query string. <h4 id="-state-params-"><code>state.params</code></h4> The active params in the location match. <h4 id="-state-query-"><code>state.query</code></h4> The active query in the location match. <h4 id="-state-routes-"><code>state.routes</code></h4> An array of the matched <a href="#TODO">routes</a>. Very useful for fetching data before rendering. See also: <a href="#TODO">Route</a>. <h2 id="examples">Examples</h2> Basic Usage: <pre><code class="lang-js"><div class="highlight"><pre>Router.run(routes, function (Root) { // whenever the url changes, this callback is called again React.render(<Root/>, document.body); }); </pre></div> </code></pre> Sample data fetching using <code>state.routes</code>. Check out the <a href="#TODO">async-data</a> example. <pre><code class="lang-js"><div class="highlight"><pre>var resolveHash = require('when/keys').all; var SampleHandler = React.createClass({ statics: { // this is going to be called in the `run` callback fetchData: function (params) { return fetchStuff(params); } }, // ... }); Router.run(routes, Router.HistoryLocation, function (Root, state) { // create the promises hash var promises = state.routes.filter(function (route) { // gather up the handlers that have a static `fetchData` method return route.handler.fetchData; }).reduce(function (promises, route) { // reduce to a hash of `key:promise` promises[route.name] = route.handler.fetchData(state.params); return promises; }, {}); resolveHash(promises).then(function (data) { // wait until we have data to render, the old screen stays up until // we render React.render(<Root data={data}/>, document.body); }); }); </pre></div> </code></pre> Server Rendering <pre><code class="lang-js"><div class="highlight"><pre>something.serve(function (req, res) { Router.run(routes, req.path, function (Root, state) { // could fetch data like in the previous example fetchData(state.matches).then(function (data) { var html = React.renderToString(<Root data={data} />); res.send(html); }); }); }); </pre></div> </code></pre> </div></article></section><section><article class="Doc"><h1 class="Heading" id="Link"><a class="HeadingLink" href="#Link">Link</a>Components</h1><div>The primary way to allow users to navigate around your application. <code>Link</code> will render a fully accesible anchor tag with the proper href. A <code>Link</code> also knows when the route it links to is active and automatically applies its <code>activeClassName</code> and/or <code>activeStyle</code> when it is. <h2 id="props">Props</h2> <h3 id="-to-"><code>to</code></h3> The name of the route to link to, or a full URL. <h3 id="-params-"><code>params</code></h3> An object of the names/values that correspond with dynamic segments in your route path. <h3 id="-query-"><code>query</code></h3> An object of the names/values that will become the query parameters in the path. <h4 id="example">Example</h4> <pre><code class="lang-js"><div class="highlight"><pre>// given a route config like this <Route name="user" path="/users/: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}/> </pre></div> </code></pre> <h3 id="-query-"><code>query</code></h3> The query string parameters as a JavaScript object. <h3 id="-activeclassname-"><code>activeClassName</code></h3> The className a <code>Link</code> receives when its route is active. Defaults to <code>active</code>. <h3 id="-activestyle-"><code>activeStyle</code></h3> The styles to apply to the link element when its route is active. <h3 id="-onclick-"><code>onClick</code></h3> A custom handler for the click event. Works just like a handler on an <code><a></code> tag - calling <code>e.preventDefault()</code> or returning <code>false</code> will prevent the transition from firing, while <code>e.stopPropagation()</code> will prevent the event from bubbling. <h3 id="-others-">others</h3> You can also pass props you'd like to be on the <code><a></code> such as a title, id, className, etc. <h2 id="example">Example</h2> Given a route like <code><Route name="user" path="/users/:userId"/></code>: <pre><code class="lang-xml"><div class="highlight"><pre><Link to="user" params={{userId: use