diff --git a/CHANGELOG.md b/CHANGELOG.md index 3591a3e..b9b767c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,9 +14,9 @@ All notable changes to this project will be documented in this file. import { resolve } from 'universal-router'; resolve(routes, { path, ...context }); // => Promise ``` - See #83 for more info and examples + See [#83](https://github.com/kriasoft/universal-router/pull/83) for more info and examples - `context.next()` now iterates only child routes by default (BREAKING CHANGE)
- use `context.next(true)` to iterate through all remaining routes + use `context.next(true)` to iterate through the all remaining routes - Add support for URL Generation ```js import generateUrls from 'universal-router/generate-urls'; diff --git a/docs/README.md b/docs/README.md index 4599e0b..fcd35a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,8 @@ server-side applications (e.g. Node.js/Express, Koa). with only single [path-to-regexp](https://github.com/pillarjs/path-to-regexp) dependency * It can be used with any JavaScript framework such as React, Vue.js etc * It uses the same middleware approach used in Express and Koa, making it easy to learn +* Routes are plain javascript objects with which you can interact as you like +* Support both imperative and declarative routing style ## How does it look like? @@ -58,8 +60,8 @@ import Router from 'universal-router/legacy'; ## Learn more -* [Getting Started](./getting-started.md) -* [Universal Router API](./api.md) +* [Getting Started](https://github.com/kriasoft/universal-router/blob/master/docs/getting-started.md) +* [Universal Router API](https://github.com/kriasoft/universal-router/blob/master/docs/api.md) ## Backers diff --git a/docs/api.md b/docs/api.md index 7d1dffe..5bc9669 100644 --- a/docs/api.md +++ b/docs/api.md @@ -8,33 +8,31 @@ title: API ∙ Universal Router ## `const router = new Router(routes, options)` Creates an universal router instance which have a single -[`router.resolve()`](##routerresolve-path-context---promiseany) method. -`Router` constructor expects a plain javascript object for the first argument -with any amount of params where only `path` is required or array of such objects. -Second argument is optional or you can pass following: +[`router.resolve()`](#routerresolve-path-context---promiseany) method. +`Router` constructor expects a plain javascript object for the first `routes` argument +with any amount of params where only `path` is required, or array of such objects. +Second `options` argument is optional where you can pass the following: -- `context` - The object with any data which you want to pass through to `resolveRoute` function.
+- `context` - The object with any data which you want to pass to `resolveRoute` function.
See [Context](#context) section below for details. -- `baseUrl` - The base URL of the app. Empty string `''` by default.
+- `baseUrl` - The base URL of the app. By default is empty string `''`.
If all the URLs in your app are relative to some other "base" URL, use this option. - `resolveRoute` - The function for any custom route handling logic.
For example you can define this option to work with routes in declarative manner.
- By default the router calls `action` methods of matched route if any. - -Example: + By default the router calls the `action` function of matched route. ```js import Router from 'universal-router'; const routes = { - path: '/', // string, required
 - name: 'home', // unique string, optional - parent: null, // route object or null, optional (filled by router) - children: [], // array of route objects or null, optional
 - action(context, params) { // function, optional - - // method should return anything except `null` or `undefined` to be resolved by router - // otherwise router will throw an error if all matched routes returned nothing + path: '/', // string, required
 + name: 'home', // unique string, optional + parent: null, // route object or null, automatically filled by the router + children: [], // array of route objects or null, optional
 + action(context, params) { // function, optional + + // action method should return anything except `null` or `undefined` to be resolved by router + // otherwise router will throw `Page not found` error if all matched routes returned nothing return '

Home Page

'; }, // ... @@ -58,7 +56,7 @@ const router = new Router(routes, options); ## `router.resolve({ path, ...context })` ⇒ `Promise` Traverses the list of routes in the order they are defined until it finds the first route that -matches provided URL path string and whose action method returns anything other than `null` or `undefined`. +matches provided URL path string and whose `action` function returns anything other than `null` or `undefined`. ```js const router = new Router([ @@ -150,8 +148,8 @@ Also check out online [router tester](http://forbeslindesay.github.io/express-ro ## Context -In addition to a URL path string, any arbitrary data can be passed to the router's `resolve()` method, -that becomes available inside action methods. +In addition to a URL path string, any arbitrary data can be passed to the `router.resolve()` method, +that becomes available inside `action` functions. ```js const router = new Router({ @@ -166,29 +164,17 @@ router.resolve({ path: '/hello', user: 'admin' }) // => Welcome, admin! ``` -Router supports `context` option in the constructor +Router supports `context` option in the `Router` constructor to support for specify of custom context properties only once. ```js -import { createStore } from 'redux'; - -const route = { - path: '/hello', - action(context) { - const state = context.store.getState(); - return `Welcome, ${state.user}!`; - }, -}; - const context = { - store: createStore({ user: 'admin' }), + store: {}, + user: 'admin', + // ... }; const router = new Router(route, { context }); - -router.resolve({ path: '/hello' }) - .then(result => console.log(result)); - // => Welcome, admin! ``` Router always adds following parameters to the `context` object @@ -199,7 +185,7 @@ before passing it to the `resolveRoute` function: - `next` - Middleware style function which can continue resolving, see [Middlewares](#middlewares) section below for details. - `url` - URL which was transmitted to `router.resolve()`. -- `baseUrl` - Base URL path relative to the current route. +- `baseUrl` - Base URL path relative to the path of the current route. - `path` - Matched path. - `params` - Matched path params, see [URL Parameters](#url-parameters) section above for details. @@ -274,7 +260,7 @@ router.resolve({ path: '/hello' }); ``` Remember that `context.next()` iterates only child routes, -use `context.next(true)` to iterate through all remaining routes. +use `context.next(true)` to iterate through the all remaining routes. ## URL Generation @@ -289,7 +275,7 @@ In most web applications it's much simpler to just use a string for hyperlinks. // etc. ``` -However for some types of web applications it may be useful to generate URLs dynamically based on route names. +However for some types of web applications it may be useful to generate URLs dynamically based on route name. That's why this feature is available as an extension `url(routeName, params) ⇒ String`. ```js @@ -314,7 +300,7 @@ url('home'); // => '/base' url('hello', { username: 'john' }); // => '/base/hello/john' ``` -This approach also works fine for dynamically added routes at runtime: +This approach also works fine for dynamically added routes at runtime. ```js routes.children.push({ path: '/world', name: 'world' }); diff --git a/docs/getting-started.md b/docs/getting-started.md index 6c27fef..22e0899 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -15,10 +15,10 @@ by running: $ npm install universal-router --save ``` -This module contains a `router.resolve` method that responsible for traversing the list of routes, until it -finds the first route matching the provided URL path string and whose action method returns anything -other than `null` or `undefined`. Each route is just a plain JavaScript object having `path`, `action`, and -`children` (optional) properties. +This module contains a `Router` class with a single `router.resolve` method that responsible for traversing +the list of routes, until it finds the first route matching the provided URL path string and whose action method +returns anything other than `null` or `undefined`. Each route is just a plain JavaScript object having `path`, +`action`, and `children` (optional) properties. ```js import Router from 'universal-router'; @@ -40,15 +40,15 @@ router.resolve({ path: '/one' }).then(result => { ## Use with React -```js +```jsx import React from 'react'; import ReactDOM from 'react-dom'; import Router from 'universal-router'; const routes = [ - { path: '/one', action: () => '

Page One

' }, - { path: '/two', action: () => '

Page Two

' }, - { path: '*', action: () => '

Not Found

' } + { path: '/one', action: () =>

Page One

}, + { path: '/two', action: () =>

Page Two

}, + { path: '*', action: () =>

Not Found

} ]; const router = new Router(routes); @@ -58,3 +58,7 @@ router.resolve({ path: '/one' }).then(component => { // renders:

Page One

}); ``` + +## Learn more + +* [Universal Router API](https://github.com/kriasoft/universal-router/blob/master/docs/api.md)