\n );\n}\n```\nEither click to the buttons or make change in your browser address bar to navigate to page. For the url paths that does not match with those in `routes` will be redirected to `fallbackRoute`, i.e. `/error/404` in this example.\n\nAny Props passing to `Navigator` will be passed to `Page` element.\n\nIt is a simple usage. However, `Navigator` can do much more than that.\n\n## Concept\n\n`@realmjs/react-navi` is built around the `route` object and `navigator` component.\n\n### `Route` object\n\nA `route` object defines a `route` controlled by `Navigator`.\n\n```javascript\nroute {\n url: String, // path of url for this route, does NOT include hostname\n Page: React.Component, // A React component used to render your Page\n data: Object || Promise, // data you can access from your Page via props.route.data\n title: String, // Title the browser will display when entered into this route\n resolve: Function // Function will be called if the promise function of data is resolved\n reject: Function // Function will be called if the promise function of data is rejected\n redirect: String // Name of the route that this route will be redirected to\n}\n```\n\n`url`: is the path of `route` and case insensitive. If your app does not need url, you can ommit it and set prop `noUrl = {true}` in `Navigator`\n\n* Route parameter is supported. For example: `/document/:docid`. You can access these parameters in `route.params` .\n\n`data`: is the data you want to pass into the rendered Page element of this `route`. It can be an object or a function returning a promise.\n\n* A promise is useful if you want the `navigator` to prepare data before actually navigating to Page. The data function receives two arguments: `params` which is `route.params` and `props` which is the react props passing to the element. Page is loaded only if the function is resolved.\n\n ```javascript\n const route = {\n ...\n data: ({params, props} => fetch(`${props.endpoint}/${params.id}`)),\n ...\n };\n ```\n Resolved data is accessed from the Page via `props.route.data`\n\n`resolve`: the callback function which is called if the data promise function is resolved, accept the resolved data as the function argument.\n\n`reject`: the callback function which is called if the data promise function is rejected, accept the rejected error as the function argument.\n\n`Page`: is the React component you design for `route`. The `Navigator` will pass the following helper props to your `Page` element:\n\n* `route`: this route object represents the current route. It contains the actual url path, the resolved data, the params object extracted from the url path and an isActive flag indicating whether this route is active or not.\n\n ```javascript\n const route = { url: '/page/about/:id', Page: Page, data: ({params, props}) => fetch(`/person/${params.id}`) };\n\n function Page({ route }) {\n const { url, data, params, isActive } = route;\n console.log(url); // example output: /page/about/jon\n console.log(params); // example output: { id: 'jon' }\n console.log(data); // example output: { person: 'Jon Snow', email: 'jon@westeros.got }\n console.log(isActive); // example output: true or false\n return (\n
\n
Person: {data.person}
\n
{data.email}
\n
\n );\n }\n ```\n\n* `page`: the page helper providing some helper utilities for page. You can setup page event observer (load, enter, leave...), create page popup or get data passed to page via navigator routine.\n\n`redirect`: the name of route that this route should be redirected to. For example:\n\n```javascript\nconst routes = {\n home: {\n url: '/',\n Page: Home\n },\n landing: {\n url: '/landing',\n redirect: 'home'\n }\n};\n```\n\n* `title`: The document title the browser will display for that `route`. Using {:param} and {{data}} for dynamic title. For example:\n\n ```javascript\n {\n url: '/welcome/:team',\n data: () => fetch('api/name'),\n title: \"Welcome {{name}} from {:team} team\",\n }\n ```\n\n When accessing /welcome/dev with resolving data { name: 'awesome' }, the title will be \"Welcome awesome from dev team\"\n\n### `Navigator` Component\n\n`Navigator` component controls all routes registered to it. Each time user navigate to a route (by calling API or change url in address bar), it will render and display `Page` component of that `route`.\n\nFor each rendered `Page`, `Navigator` will inject `route` object and `page` object into `props`.\n\nNote that there is only one `Navigator` for entire application.\n\n#### `Navigator` Component Properties:\n\n`routes` (Object): Routes object to be registered into `Navigator`\n\n`initialRoute` (String): Name of the `route` that will be active at initial if `noUrl` is `true`\n\n`fallbackRoute` (String): Name of the `route` that `Navigator` will redirect to if the `url` does not match any `route` in registered `routes`. It is ignored if `noUrl` is `false`. Note that navigate to an unregistered route by `navigate API` will not redirect to `fallbackRoute`, but `reject` with an error.\n\n`onChangeRoute` (Function): Function that is called when active route is changed. It receives the `route` object of active route as the arguments.\n\n`onEnterPage` (Function): Function that is called when navigate is enter a Page but before the page is rendered. It receives the `route` object of active route as the arguments.\n\n`onPageRendered` (Function): Function that is called after Page is rendered, It receives the `route` object of active route as the arguments.\n\n`noUrl` (Boolean): Default is `false`, define whether your application should use `url` or not. If set to `true`, `route` object will require `url`, navigate to a `route` will update `url` in address bar and you can also navigate by typing `url` from there.\n\n`routeHandler` (Function): The function will be called when creating `navigator`, with `routeHandler` in the argument. `routeHanler` can be used to call `navigate` API. [Deprecated]\n\n```javascript\n// example of using routeHandler\n...\nrender() {\n return (\n console.log('Active route is' + route.url) }\n onPageRendered = { route => console.log('Rendered page for route ' + route.url) }\n onEnterPage = { route => console.log('Enter page for route ' + route.url) }\n {...this.props}\n />\n )\n}\n```\n\n#### Route Stack\n\nThe `Navigator` will create route stack in session storage automatically. Each time user navigate to a `route`, it will add to the route stack.\n\n### Global `nav` Object\n\n`@realmjs/react-navi` expose the global `nav` object. It can be used to navigate route, create `global popup` or create `toast` from anywhere in your application\n\n**`navigate (name, options)`**\n\n`name` (String): name of route navigate to\n\n`options` (Object): optional\n\n* `data` (Object): Data passing to `Page` and can be accessed via `props.page.data`.\n\n* `noUpdateUrl` (Boolean): defalt is `false`, set to `true` will not update url [Deprecated]\n\n* `reload` (Boolean): default is `false`, set to `true` will cause a `web page reload` when navigating.\n\nThis function return a `promise`\n\n**`popup(PopupComponent, options, callback)`**\n\n* `PopupComponent` (React Component): A React Component design the popup\n\n* `options` (Object): optional\n * `data` (Object): Data passed to `Popup` via `self` object\n * `overlay` (Boolean): Default is `false`, set to `true` will create `popup` in an overlay layer\n * `onClickOverlay` (Function): The function is called whenever user click to overlay. Accept `self` as the function argument.\n\n* `callback` - `Function`: optional, a callback provide `self` object to `resolve` or `reject` popup.\n\nThis function return a `promise` that `resolve` or `reject` by the `popup` via `self` object\n\n**Popup `self` object**\n\nThe `Popup` component receive `self` object via its `props`.\n\n```javascript\nself {\n data: Object,\n onClickOverlay: Function,\n resolve: Function,\n reject: Function\n}\n```\nNote that the popup created by `nav` is global.\n\n##### Create `toast`\n\n`Toast` can only be created by `nav` object. The API is veri similar to `popup APi` except that it does not return anything\n\n**`toast(ToastComponent, options, callback)`**\n\n* `PopupComponent` - `React Component`: A React Component design the popup\n\n* `options` - `Object`: optional\n * `data` - `Object`: `data` passed to `Toast` via `self` object\n * `bottom` - `Boolean`: default `false`, if set to `true` toast will float up from bottom\n\n* `callback` - `Function`: optional, a callback provide `self` object to `close` toast.\n\n**Toast `self` object**\n\nThe `Toast` component receive `self` object via its `props`.\n\n```javascript\nself {\n data: Object,\n close: Function\n}\n```\n\n#### Example using `nav` object\n\n```javascript\n\nimport { nav } from 'react-navi'\n\nimport Popup_Loading from './popup/Popup_Loading'\nimport Toast_System from './toast/Toast_System'\n\nnav.navigate('welcome', { data: {\n user: 'Awesome Dev'\n}});\n\nnav.popup(Popup_Loading, self => {\n setTimeout(() => {\n self.resolve('Loading Timeout 3 seconds');\n }, 3000);\n});\n\nnav.toast(Toast_System, { data: 'System message' }, self => {\n setTimeout(() => {\n self.close();\n }, 2000);\n});\n\n```\n\n#### Injected `page` object\n\nFor each rendered `Page`, `Navigator` will inject a `page` object into `Page props`. This `page` object allow `Page` to setup event listeners and create page's `Popups`.\n\n##### Page events\n\nFollowing page event are supporting:\n\n`load`\n\nThis event is fired when a `route` is active for the first time. When a `route` is active, it will be pushed into a `routeStack` manage internally by `Navigator`. When it is inactive, `Navigator` will `hide` its `page`. When it is active again, `Navigator` simply `unhide` its `page` and `load` event is not fired.\n\n`beforeEnter`\n\nThis event is fired every time a `route` is going to active by a `navigate` API call.\n\n`enter`\n\nThis event is fired every time a `route` is active and its `page` is shown up.\n\n`leave`\n\nThis event is fired every time a `route` is going to `inactive` by a `navigate` API call.\n\nThese `event` can be registered via `page` object. Example below:\n\n```javascript\nclass Page_Home extends Component {\n constructor(props) {\n super(props);\n props.page.onLoad(e => console.log('# Load Page'));\n props.page.onBeforeEnter(e => console.log('# Before Enter Page'));\n props.page.onEnter(e => console.log('# Enter Page'));\n props.page.onLeave(e => console.log('# Leave Page'));\n }\n render() {\n // render code...\n }\n}\n```\n\n##### Create Popup\n\nIt is very useful to create a `popup` using `page` object, simple by calling `popup` API. The API is identical with `nav.popup`.\n\nNote that `popup` created from a `page` will only exist in that `page`. `popup` created by `nav` object will exist in global.\n\n\n**TODO:**\n1. Animation for popup & page\n1. Add Unit tests\n1. Validate href not duplicated\n1. Fix error: enter invalid route without fallbackRoute defined.\n1. HOw redirect route use to redirect to route with param?","readmeFilename":"README.md"}