@metamatic.net/metamatic-router
v2.5.7
Published
Metamatic™ Router is an extension to Metamatic core framework providing support for routing.
Downloads
12
Readme
The Metamatic™ Router
A router extension to Metamatic™ state management framework.
Contents
Introduction
The Metamatic™ Router is a simple router component installed on top of the core Metamatic™ State Manager framework.
When you use Metamatic™ State Manager framework you can use any router library available around the Internet. But some of those solutions require you to wrap your app's root component with some clumpy "Router" tags before you can implement routing. Or if you want to programmatically soft-redirect your app to a certain sub-url then you may need to wrap your redirecting component inside some obscure wrapper again, possibly breaking your code's otherwise sleek and clean syntax.
For this reason, Metamatic Systems Ltd provides a simple out-of-the-box routing library. It may be a viable alternative to some external routing libraries. This depends of course on your use case.
Usage
Connecting to Router
To use Metamatic™ Router in your app, subscribe your main component to listen for URL changes with connectToRouter function:
componentDidMount = () => connectToRouter(
this,
(url) => this.setState({...this.state, url: url})
);
The code snippet above causes the connected component to retrieve the updated URL from Metamatic when the URL changes. Then the listener component is re-endered causing the main component show a different set of components based on that URL.
The code snippet above causes the main component to re-render itself every time the URL changes.
Disconnecting from Router
Any component that has a de-facto life cycle, meaning it will removed, deactivated or unmounted during the application's run-time, should be disconnected from the router upon unmount event. To disconnect a React component from Metamatic™ Router can be done with disconnectFromRouter function:
componentWillUnmount = () => disconnectFromRouter(this);
Note that in the root component of a React app, such as App.js or Main.js, however, it is not necessary to disconnect from the router upon unmount event since the root component only "dies" when the application tab or window is closed anyway.
Mapping Components to Routes
Inside your main component, make render function optionally render different components based on the current URL pattern using matchRoute function. As first parameter, give matchRoute any regular expression to define which URL patterns will match the current URL, thus causing the related component to be rendered that defined in the second parameter:
render = () => (
<div className='main'>
{matchRoute('/', <Header/>)}
{matchRoute('/language', <LanguageView/>)}
{matchRoute('/vocabulary', <VocabularyView/>)}
..
</div>
)
Alternative Ways of Connecting to Routes
Since matchRoute function does not need the current URL as parameter, you don't necessarily need to retrieve the URL parameter from Router at all in your main component where you define the actual routes. Therefore you can cause re-render by setting state without any modification to it:
componentDidMount = () => connectToRouter(
this,
(url) => this.setState(this.state)
);
Or use React's forceUpdate function, event though some puritanists may consider it ugly. But beauty is in the eye of the beholder. What works, just works:
componentDidMount = () => connectToRouter(
this,
(url) => this.forceUpdate()
);
Configuring Base Route
When you deploy your app to some sub-folder of your domain instead of domain's root, you must define the sub-path invoking configureBaseRoute function
at some early point of your app.
For example, I want to place my router demo app in sub folder 'router' of demo domain https://metamatic-demo.herokuapp.com/router/:
configureBaseRoute('/router');
Programmatically Redirecting to Routes
Whenever you want your app to programmatically redirect to some view defined in routes, use redirectTo function:
onClick = () => redirectTo(someUrlPath);
To see a complete example of using routing feature in action, please check out The Router Demo on GitHub.
Miscellaneous
Licence
Apache 2.0