MoBrix-engine-plugin-router

---

A routing system to control navigation with MoBrix-engine

---

Summary

• Getting started
  • Installation
  • Usage
• API
  • Config
  • Actions
  • Selectors
• Integration with other plugins
• Included libraries
• Authors
• License

---

Getting started

Installation

If you want to use this plugin with MoBrix-engine, install it:

npm i mobrix-engine-plugin-router

Check MoBrix-engine guide to init the system

Usage

Include this plugin inside your MoBrix-engine config file, and optionally set the router field, with the plugin settings. For example, to add a custom query parameter:

// Inside your MoBrix-engine config file

import { routerPlugin } from "mobrix-engine-plugin-router";

const config = {
  appName: "custom-app",
  plugins: [routerPlugin],
  router: {
    routes: {
      Home: "/",
      Custom: "/custom",
    },
    homePage: "Home",
    basename: "/custom-basename",
  },
};

export default config;

So the plugin will store 2 routes:

{
  "Home": "/custom-basename/",
  "Custom": "/custom-basename/custom"
}

and the home page route will be:

/custom-basename/

Additionally, this plugin save the used history into the router config, inside the config returned after MoBrix-engine is initialized. you can find it into the history field:

import { initEngine } from "mobrix-engine";
import { routerPlugin } from "mobrix-engine-plugin-router";

const config = {
  plugins: [routerPlugin],
  appName: "custom-app",
  router: {
    routes: {
      Home: "/",
      Custom: "/custom",
    },
    homePage: "Home",
    basename: "/custom-basename",
  },
};

const engineOutput = initEngine(config);

//You can use this history object in any part of your app
const history = engineOutput.config.router.history;

You can see a live preview by visiting mobrix-engine-playground

API

Config

This plugin adds a custom field inside the MoBrix-engine config, router:

Selectors	Returns
routes	a dictionary with all custom routes (the key is the custom route name, and the value is the route associated)
homePage	home page route name (from routes field)
basename	custom basename, a shared common routes that will be put at the start of every route
onLocationChange	functions called everytime the location change

Check the usage section for a real example

Actions

Action creator	Arguments	Effect
goBack	/	Go back to previous route saved in history
goTo	- path: new route to set	Go to the given route, if it is one of the stored routes, and save it to the shared history

Import them from this lib:

import { goBack, goTo } from "mobrix-engine-plugin-router";

Then dispatch them from any part of your app:

import { goBack, goTo } from "mobrix-engine-plugin-router";

import { useDispatch } from "react-redux";

export const goToButton = () => {
  const dispatch = useDispatch();

  return (
    <button
      onClick={() => {
        dispatch(goTo('/custom-basename/custom'));
      }}
    >
      Go to '/custom-basename/custom' route
    </button>
  );

export const GoBackButton = () => {
  const dispatch = useDispatch();

  return (
    <button
      onClick={() => {
        dispatch(goBack());
      }}
    >
      Go back
    </button>
  );
};

Selectors

Selectors	Returns
getRouterView	router plugin state
getRouterPluginConfig	router plugin configuration
getHomePage	home page route
getRoutes	stored routes, with basename at the start of all routes
isHomePage	true if actual route is home page, otherwise false

Import them from this lib:

import {
  getHomePage,
  getRouterPluginConfig,
  getRouterView,
  getRoutes,
  isHomePage,
} from "mobrix-engine-plugin-router";

Then you can use them, with selectors hooks, inside your components::

import { useSelector } from "react-redux";
import { getRouterConfig } from "mobrix-engine-plugin-router";

export const RouterDebugComponent = () => {
  const routerConfig = useSelector(getRouterConfig);

  return (
    <div>
      <p>Router plugin configuration</p>
      {routerConfig}
    </div>
  );
};

Integration with other plugins

• This plugin expose some fields to work with any other plugin. If you want to interact with it, using your custom plugin, just check the add an interaction for mobrix-engine-router. With the given field and the actual engine config, you can add custom params to the plugin (look at the config section). For example, to add a custom function to be called when location change:

//Just a skeleton of a custom plugin that interacts with router plugin
const customPlugin = () => ({
  // Custom plugin stuffs

  interactions: [
    {
      plugin: "mobrix-engine-router",
      effect: (routerConfig) => {
        // Custom plugin stuffs

        //Add the custom callback
        routerConfig.onLocationChange.push(() => {
          alert("location changed");
        });
      },
    },
  ],
});

• Additionally, if you use MoBrix-engine-plugin-url-checker too, you can change the initial route directly from URL, with query parameters, by passing the to parameter with the route you want to set. Try it with MoBrix-engine playground - https://cianciarusocataldo.github.io/mobrix-engine?to=/test

---

Included libraries

• redux-first-history to drive location with actions
• MoBrix-engine-types - to use MoBrix-engine type definitions inside the plugin
• MoBrix-utils - to use shared util functions during init process
• This lib is written entirely with Typescript

---

Authors

• Cataldo Cianciaruso

---

License

This project is licensed under the MIT License - see the LICENSE file for details