A router for Matreshka.js
npm install --save matreshka-router
A bundle (downloadable version) lives at gh-pages branch
The library turns on two-way data binding between properties and parts of URL.
// location.hash is used thereMatreshka;objecta = 'foo';objectb = 'bar';objectc = 'baz';// makes location.hash to be #!/foo/bar/baz/
If you need to use History API instead of hash, pass
"history" as the second argument.
CJS module import:
const initRouter = ;;
How does "traditional" routing works? A developer defines a rule (route) and defines a function which will be called when current path fits given rule.
Let's say you need to synchronize
"x" with the first part of
"y" with the second.
Now when you type...
objectx = 'foo';objecty = 'bar';
location.hash is automatically changed to
And vice versa. When the URL is changed manually or via back and forward buttons, the properties will be changed automatically.
locationhash = '#!/baz/qux/';// ... after a momentconsole; // ‘baz’, ‘qux’
As usually you can listen property changes with Matreshka#on method.
Matreshka;// for Matreshka instances: this.on('change:x', handler);
An asterisk syntax
You can pass a string which contain asterisks to
initRouter if you don't need to synchronize some part of the path with a property.
If the hash looks like
this.x = "foo" and
this.y = "baz".
This feature is useful in cases when classes control different parts of the path.
Two things to remember
1. If a property has truthy value then URL will be changed immediately after
objectx = 'foo';Matreshka;
2. If a property gets falsy value then all next listed properties will get
null as new value.
Matreshka;Matreshkay = null; // makes this.z and this.u to be null as well
The idea is to get actual state of URL. It could be weird to get
"z" with value
"foo" in case of non-existing bound part of URL.
HTML5 History API
The plugin supports HTML5 History as well. To initialize it you need to pass optional argument
"history" value to the
initRoute function (by default
If an application is located at CJS environment (NodeJS, Webpack, Rollup...) then requiring
matreshka-router doesn't add any static properties to
const initRouter = ;;
Router class import (read below):
const Router = ;const customRouter = 'myType';
An additional information
matreshka-router is powered by
Matreshka.Router class. It accepts only one argument - router type (
"history" or a custom string).
By default, the library creates two instances of
Matreshka.Router with types
history. They live at
Matreshka.Router.history. matreshka-router uses lazy initialization so when you just attach the script onto webpage, the library does nothing.
For these two types of instances the singleton pattern is used. That means when you're trying to create another instance of
hash routing via
new Matreshka.Router('hash'), the
Matreshka.Router.hash will be returned instead of new instance creation. This logic centralizes URL handling, gives positive effect to the performance and doesn't make potential collisions. Objects which are handled by
initRouter just subscribe to the changes of needed type of the router.
Custom instances (non-hash and non-history) of
Matreshka.Router can be created manually in case if you generate URL for further use. At this case changes of target properties don't affect on
hash and don't call
Matreshka.Router instances has 3 properties.
path- contains actual URL, eg
hashPath- contains actual URL and hashbang as a prefix, eg
parts- contains an array of all parts of the path, eg
[‘foo’, ‘bar’, ‘baz’].
All these properties are created using calc, which means when you change one property, the others are changed automatically.
MatreshkaRouterhashpath = '/yo/man/';
By changing these properties you can trigger needed procedures (update the path, change subscribed objects etc.)
subscribe(object, route)- subscribes object for route changes.
init()- used for lazy initialization in
subscribemethod (no need to call it manually).
const customRouter = 'myType';const object =a: 'foo'b: 'bar';customRouter;console; // /foo/bar/