From e195225125abc957736b75baf7fd1f11f5183824 Mon Sep 17 00:00:00 2001 From: Michael Jackson Date: Mon, 16 Feb 2015 14:21:12 -0800 Subject: [PATCH] Small docs tweaks --- docs/api/Location.md | 65 +++++++++++++++++++ docs/api/README.md | 19 +++--- docs/api/Router.md | 30 --------- .../api/{misc/transition.md => Transition.md} | 4 +- docs/api/components/DefaultRoute.md | 6 +- docs/api/components/Link.md | 18 ++--- docs/api/components/NotFoundRoute.md | 8 +-- docs/api/components/Redirect.md | 2 +- docs/api/components/Route.md | 6 +- docs/api/components/RouteHandler.md | 13 ++-- docs/api/misc/Location.md | 51 --------------- 11 files changed, 100 insertions(+), 122 deletions(-) create mode 100644 docs/api/Location.md delete mode 100644 docs/api/Router.md rename docs/api/{misc/transition.md => Transition.md} (80%) delete mode 100644 docs/api/misc/Location.md diff --git a/docs/api/Location.md b/docs/api/Location.md new file mode 100644 index 0000000000..3a50d59630 --- /dev/null +++ b/docs/api/Location.md @@ -0,0 +1,65 @@ +API: `Location` (object) +======================== + +The router uses "location" objects to determine the current state of +the application and update it when needed. In a browser environment, +the location represents the URL in the browser's location bar. On the +server, the location is the URL path that was used in the request. + +ReactRouter ships with several locations that make it convenient to +use in many different scenarios. They are listed below. + + | `HashLocation` | Stores the current URL in `window.location.hash`. Use this if you need to support browsers that do not support the HTML5 history API | + | `HistoryLocation` | Uses the HTML5 history API to store state in clean URLs | + | `RefreshLocation` | A fallback for having clean URLs in browsers that do not support the HTML5 history API by updating `window.location` whenever the route changes. The router automatically falls back to this when you try to use `HistoryLocation` in old browsers | + | `StaticLocation` | A location for stateless environments (like servers) where the URL is given once | + | `TestLocation` | A location that allows you to easily stub out URL history when writing tests | + +You can also supply the router with your own location implementation. The +following methods must be implemented: + +Methods +------- + +### `addChangeListener(listener)` + +Adds a function to the location that should be called when it changes. + +### `removeChangeListener(listener)` + +Stop calling the given function when the location changes. + +### `push` + +Called when the router is transitioning from one path to another. + +### `replace` + +Called when the router is replacing (not transitioning) one url with +another. + +### `pop` + +Called when the router attempts to go back one entry in the history. + +### `getCurrentPath` + +Should return the current URL path, complete with query string (if applicable). +This method should be ready to go immediately after setup. + +### `toString` + +Should return a useful string for logging and debugging. + +History +------- + +Additionally, location objects must: + +- Increment `ReactRouter.History.length` immediately **after** the URL changes +- Decrement `ReactRouter.History.length` immediately **before** going back to the + previous URL + +Please refer to the [built-in location objects][locations] to get an idea for how this is done. + +[locations]: /locations diff --git a/docs/api/README.md b/docs/api/README.md index ab04019181..8dabbedf4c 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,28 +1,25 @@ React Router API ================ -- [`Router`](/docs/api/Router.md) - - [`Router.run`](/docs/api/run.md) - - [`Router.create`](/docs/api/create.md) +- [`Location`](/docs/api/Location.md) +- [`Transition`](/docs/api/Transition.md) -- Components - - [`DefaultRoute`](/docs/api/components/DefaultRoute.md) +- Renderable Components + - [`RouteHandler`](/docs/api/components/RouteHandler.md) - [`Link`](/docs/api/components/Link.md) + +- Configuration Components + - [`Route`](/docs/api/components/Route.md) + - [`DefaultRoute`](/docs/api/components/DefaultRoute.md) - [`NotFoundRoute`](/docs/api/components/NotFoundRoute.md) - [`Redirect`](/docs/api/components/Redirect.md) - - [`Route`](/docs/api/components/Route.md) - - [`RouteHandler`](/docs/api/components/RouteHandler.md) - Mixins - [`State`](/docs/api/mixins/State.md) - [`Navigation`](/docs/api/mixins/Navigation.md) -- Misc - - [`Location`](/docs/api/misc/Location.md) - - [`transition`](/docs/api/misc/transition.md) - Public Modules -------------- diff --git a/docs/api/Router.md b/docs/api/Router.md deleted file mode 100644 index cdbdd0d267..0000000000 --- a/docs/api/Router.md +++ /dev/null @@ -1,30 +0,0 @@ -API: `Router` -============= - -The main export of this library. - -```js -// cjs modules -var Router = require('react-router') - -// or global build -var Router = window.ReactRouter - -// contains these exports - -// methods -Router.run -Router.create - -// components -Router.DefaultRoute -Router.Link -Router.NotFoundRoute -Router.Redirect -Router.Route - -// mixins -Router.State -Router.Navigation -``` - diff --git a/docs/api/misc/transition.md b/docs/api/Transition.md similarity index 80% rename from docs/api/misc/transition.md rename to docs/api/Transition.md index e8377af1f3..0377600ca2 100644 --- a/docs/api/misc/transition.md +++ b/docs/api/Transition.md @@ -1,7 +1,7 @@ -API: `transition` (object) +API: `Transition` (object) ========================== -This object is sent to the [transition hooks][transition-hooks] as the +A `Transition` object is sent to the [transition hooks][transition-hooks] as the first argument. Methods diff --git a/docs/api/components/DefaultRoute.md b/docs/api/components/DefaultRoute.md index 03f8ddc032..83eb419c03 100644 --- a/docs/api/components/DefaultRoute.md +++ b/docs/api/components/DefaultRoute.md @@ -1,15 +1,15 @@ API: `DefaultRoute` (component) =============================== -A `DefaultRoute` is active when the parent route's path matches exactly. +A `` is active when the parent route's path matches exactly. -Note, this is not a `NotFoundRoute`. It is only active when the parent's +Note, this is not a ``. It is only active when the parent's route path is matched exactly. Props ----- -See [Route::props][routeProps] +See [][routeProps] Example ------- diff --git a/docs/api/components/Link.md b/docs/api/components/Link.md index c5efeaf460..629a353e20 100644 --- a/docs/api/components/Link.md +++ b/docs/api/components/Link.md @@ -1,9 +1,11 @@ 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. +A `` renders an `` tag that links to a route in the application. If +you change the path of your route, you don't also have to change your links. + +A `` also knows when the route it links to is active and automatically +applies its `activeClassName` and/or `activeStyle` when it is. Props ----- @@ -14,7 +16,7 @@ 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. +An object of the names/values that correspond with dynamic segments in your route path. #### Example @@ -31,17 +33,15 @@ Object, the parameters to fill in the dynamic segments of your route. ### `query` -Object, Query parameters to add to the link. Access query parameters in -your route handler with `this.getQuery()`. +The query string parameters as a JavaScript object. ### `activeClassName` -The className a `Link` receives when its route is active. Defaults to -`active`. +The className a `Link` receives when its route is active. Defaults to `active`. ### `activeStyle` -Object, the styles to apply to the link element when its route is active. +The styles to apply to the link element when its route is active. ### `onClick` diff --git a/docs/api/components/NotFoundRoute.md b/docs/api/components/NotFoundRoute.md index b6c09486c9..553d932c6b 100644 --- a/docs/api/components/NotFoundRoute.md +++ b/docs/api/components/NotFoundRoute.md @@ -1,14 +1,14 @@ API: `NotFoundRoute` (component) =============================== -When a parent's URL partially matches, but none of the children do, a -`NotFoundRoute` will be matched and its handler activated at any level -of your route hierarchy. +A `` 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" page. Props ----- -See [Route::props][routeProps] +See [][routeProps] Example ------- diff --git a/docs/api/components/Redirect.md b/docs/api/components/Redirect.md index 80e3c104c8..5c9bb8cd4f 100644 --- a/docs/api/components/Redirect.md +++ b/docs/api/components/Redirect.md @@ -1,7 +1,7 @@ API: `Redirect` (component) =========================== -Configures a redirect for a path in your route declarations. +A `` sets up a redirect to another route in your application. Props ----- diff --git a/docs/api/components/Route.md b/docs/api/components/Route.md index 5c629549ca..c799db3398 100644 --- a/docs/api/components/Route.md +++ b/docs/api/components/Route.md @@ -1,16 +1,14 @@ API: `Route` (component) ========================= -Configuration component to declare your application's routes and entry -view hierarchy. +A `` is used to declare your application's routes and entry view hierarchy. Props ----- ### `name` -The name of the route, used in the `Link` component and the router's -transition methods. +The name of the route, used in the `Link` component and the router's transition methods. ### `path` diff --git a/docs/api/components/RouteHandler.md b/docs/api/components/RouteHandler.md index b837a6bb3b..6f3d858ff8 100644 --- a/docs/api/components/RouteHandler.md +++ b/docs/api/components/RouteHandler.md @@ -1,15 +1,14 @@ API: `RouteHandler` (component) =============================== -The component supplied to a route is called a "Route Handler". They can -be rendered by the parent handler with ``. There are -some special static methods available to these components. +A `` renders the handler of the route at the level of the +route hierarchy in which it is used. Static Lifecycle Methods ------------------------ -You can define static methods on your route handlers that will be called -during route transitions. +You can define some static methods on your route handlers that will be +called during route transitions. ### `willTransitionTo(transition, params, query, callback)` @@ -18,7 +17,7 @@ abort or redirect the transition. You can pause the transition while you do some asynchonous work and call `callback(error)` when you're done, or omit the callback in your argument list and it will be called for you. -See also: [transition](/docs/api/misc/transition.md) +See also: [Transition](/docs/api/Transition.md) ### `willTransitionFrom(transition, component, callback)` @@ -27,7 +26,7 @@ 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 (like form fields). -See also: [transition](/docs/api/misc/transition.md) +See also: [Transition](/docs/api/Transition.md) #### Example diff --git a/docs/api/misc/Location.md b/docs/api/misc/Location.md deleted file mode 100644 index b831db0572..0000000000 --- a/docs/api/misc/Location.md +++ /dev/null @@ -1,51 +0,0 @@ -API: `Location` (object) -========================== - -You can supply the router with your own location implementation. The -following methods must be implemented: - -Methods -------- - -### `addChangeListener(listener)` - -Adds a function to the location that should be called when it changes. - -### `removeChangeListener(listener)` - -Stop calling the given function when the location changes. - -### `push` - -Called when the router is transitioning from one path to another. - -### `replace` - -Called when the router is replacing (not transitioning) one url with -another. - -### `pop` - -Called when the router attempts to go back one entry in the history. - -### `getCurrentPath` - -Should return the current URL path, complete with query string (if applicable). -This method should be ready to go immediately after setup. - -### `toString` - -Should return a useful string for logging and debugging. - -History -------- - -Additionally, location objects must: - -- Increment `ReactRouter.History.length` immediately **after** the URL changes -- Decrement `ReactRouter.History.length` immediately **before** going back to the - previous URL - -Please refer to the [built-in location objects][locations] to get an idea for how this is done. - -[locations]: /locations