Mobrix-engine-plugin-router NPM

MoBrix-engine-plugin-router

A routing system to control navigation with MoBrix-engine

Summary

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

@everything-registry/sub-chunk-2185 @zalastax/nolb-mobr

1.0.0

2 years ago