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