Demo
Репозиторий


tl;dr


Плагин включает синхронизацию свойств объекта и куска урла.


Matreshka.initRouter(object, '/a/b/c/');
object.a = 'foo';
object.b = 'bar';
object.c = 'baz'

// location.hash теперь #!/foo/bar/baz/

Для использования History API вместо location.hash, нужно передать строку "history" вторым аргументом.


Matreshka.initRouter(object, '/a/b/c/', 'history');

Импорт CJS модуля:


const initRouter = require('matreshka-router');
initRouter(object, '/a/b/c/', 'history');


Как работает “традиционный” роутинг? Разработчик указывает правило (роут) и описывает то, как будет себя вести приложение при соответствии урла с указанным правилом.


route('books/:id', id => {
    // делать что-то
});

Matreshka Router работает по-другому. Библиотека синхронизирует часть пути со свойством объекта.


Дисклеймер: такой способ роутинга может не покрывать все те задачи, которые обычно ставятся перед обычным роутером. Воспользуйтесь альтернативным решением, если в этом есть необходимость.


Принцип работы плагина в следующем: вы указываете какая часть урла (поддерживается и hash, и HTML5 History) синхронизируется со свойством.


Скажем, вы хотите синхронизировать свойство "x" с первой частью location.hash, свойство "y" — со второй.


Matreshka.initRouter(object, "/x/y/");

Теперь когда вы пишете..


object.x = 'foo';
object.y = 'bar';

… Хеш автоматически изменится на #!/foo/bar/


И наоборот, если вы вручную, программно или с помощью стрелок “вперед” и “назад“ меняете адрес, свойства изменятся автоматически.


location.hash = '#!/baz/qux/';

// ... через несколько миллисекунд
console.log(object.x, object.y); // ‘bar’, ‘qux’

Как и всегда, свойства можно прослушивать с помощью метода on.


Matreshka.on(object, 'change:x', handler);
// или так, если объект - экземпляр Matreshka: this.on('change:x', handler);

В функцию initRouter можно передать строку со “звездочками”, для игнорирования части урла.


Matreshka.initRouter(object, '/x/*/y');

Если хеш выглядит, как #!/foo/bar/baz/, то object.x становится равным "foo", object.y — "baz".


Такая возможность полезна тогда, когда один класс контролирует одну часть адреса, другой — другую.


class1.js


Matreshka.initRouter(this, '/x/*/');

class2.js


Matreshka.initRouter(this, '/*/y/');

Важно помнить две вещи:


1. Если при инициализации роутера свойство имеет правдивое значение, адрес изменится сразу после вызова initRouter. Иначе — наоборот, свойство получит значение части пути.


object.x = 'foo';

Matreshka.initRouter(object, '/x/y/');

2. Если свойство, указанное в роуте получит лживое значение, все последующие свойства, указанные в роуте, получат значение null.


Matreshka.initRouter(object, '/x/y/z/u/');

object.y = null; // установит object.z и object.u тоже в null

Идея в том, чтоб поддерживать состояния урла и свойств актуалными. Было бы странно иметь свойство "z" со значением "foo" при условии отсутствующей части адреса, связанной с этим свойством.


HTML5 History API


Кроме хеш роутинга, плагин поддерживает возможность работы с HTML5 History. Для инициализации нужно передать в метод initRoute дополнительный параметр type равный "history" (по умолчанию, type = "hash").


Matreshka.initRouter(object, '/x/y/z/', 'history');

Дополнительная информация


Ядро роутера реализовано в виде класса Matreshka.Router. Его конструктор принимает один аргумент: тип роутера ("hash", "history" или произвольную строку).


При подключении роутера создаётся два экземпляра класса Matreshka.Router с типами hash и history, которые хранятся, соответственно, в Matreshka.Router.hash и Matreshka.Router.history (используется ленивая инициализация, поэтому подключение без использования ничего не делает). Для этих двух экземпляров реализуется паттерн синглтон, т. е, при создании роутера с типом hash возвращается Matreshka.Router.hash вместо создания нового экземпляра. Такая логика централизует обработку урла, положительно влияя на производительность и не вызывает коллизии. Объекты, в свою очередь, просто подписываются на изменения и не занимаются парсингом.


"Кастомные" экземпляры Matreshka.Router могут быть созданы вручную, на случай, если нужно сгенерировать ссылку для дальнейшего произвольного использования. В этом случае, изменение свойств не повлияет на hash и не вызовет pushState.


Экземпляры класса Router имеют три свойства.


path — свойство, которое содержит актуальный урл, например, /foo/bar/baz/.


hashPath — свойство, которое сожеджит path, с дописанным к ней hashbang, например #!/foo/bar/baz/


parts — свойство, представленное в виде массива, содержащее актуальные кусочки пути, например, [‘foo’, ‘bar’, ‘baz’].


Все три свойства объявлены с помощью метода calc, так что при изменении одного свойства, меняются и другие:


Matreshka.Router.hash.path = '/yo/man/';

… И два метода


subscribe(object, route) — подписывает объект на изменения в свойствах.


init() — используется для ленивой инициализации при вызове subscribe (вызывать вручную нет нужды).


const customRouter = new Matreshka.Router('myType');
const object = {
    a: 'foo',
    b: 'bar'
};

customRouter.subscribe(object, '/a/b/');

console.log(customRouter.path); // /foo/bar/

Импорт модуля CommonJS


Всё описанное выше касается немодульного окружения. Если приложение находится в окружении CommonJS (NodeJS, Webpack, Rollup...) подключение модуля matreshka-router не добавляет новых статичных свойств классу Matreshka. Вместо этого, initRouter импортируется традиционным способом.


const initRouter = require('matreshka-router');
initRouter(object, '/x/y/');

Импортировать класс Router можно так:


const Router = require('matreshka-router/router');
const customRouter = new Router('myType');

Всем добра.