react-module-hook

A react module hook for real configurable app with stateful persistent module tree and peer-to-peer messaging mechanism

Usage no npm install needed!

<script type="module">
  import reactModuleHook from 'https://cdn.skypack.dev/react-module-hook';
</script>

README

react-module-hook

A react module hook for real configurable app with stateful persistent module tree and peer-to-peer messaging mechanism

1. Usage

1.1. Install

npm install react-module-hook

1.2. Import

import { useModule } from "react-module-hook";

1.3. Call it in a render function

...
const ReactComponent = props => {
  const { module, auth, router, request } = useModule(props, {
    // the default state for this module
    state:{},
    // the default props for this module
    props:{},
    // actions for this module
    actions:{"actionName":()=>()},
    // for extra data
    tagVar:{},
    // enable router
    router: true,
    // enable auth
    auth: true,
    // the request configure
    req_url : `${useModule.resolveURL( "data/demo.json" ) }`,
    req_data : { key : "value" },
    req_method : "post",
    req_baseURL : null,
    req_AUTH_TOKEN : null,
    req_header : null,
    req_config : null,
    req_execute : true
  }); 

  // ...
  // return JSX;
};

1.4. Use the component

...
const ReactComSub1 = props => {
  const { module } = useModule(props, { }); 
  return (
    <div>
      ReactComSub1
    </div>
  );
};
const ReactComSub2 = props => {
  const { module } = useModule(props, { }); 
  return (
    <div>
      ReactComSub2 - {props.name}
    </div>
  );
};
const ReactCom = props => {
  const { module } = useModule(props, {
    state:{
      items:[{"name":"v1"},{"name":"v2"}]
    }
  }); 
  const XReactComSub2 = module.enhanceCom(ReactComSub2);
  return (
    <div>
      <ReactComSub1 usemodule_alias="alias1" usemodule_uid="uid1" usemodule_parent={module}/>
      <ReactComSub2 usemodule_alias="alias2" usemodule_uid="uid2" usemodule_parent={module}/>
      <XReactComSub2 usemodule_alias="alias3" usemodule_uid="uid3" x_id="x_id1" x_iterator="items"/>
    </div>
  );
};

[root]
  │  
  └─<ReactCom >
         │  
         ├<ReactComSub1 usemodule_alias="alias1">
         │  
         ├<ReactComSub2 usemodule_alias="alias2">
         │  
         └<XReactComSub2 usemodule_uid="alias3" x_id="x_id1">

2. API

2.1. useModule static functions

useModule.getRootModule

useModule.getRootModule( )
  Gets the root useModule element.
[return]
  Object, The root useModule element.

  // to get the root useModule element
  const rootModule = useModule.getRootModule();

useModule.getModule

useModule.getModule ( idOrAlias )
  Gets the useModule element by uid (usemodule_uid) or alias (usemodule_alias). Getting from alias is only for the child elements in the root useModule element )
[return]
  Object, The result useModule element
[parameters]

  • idOrAlias [required] : String, The target useModule element's uid or alias
  // to get an useModule element with usemodule_uid="global_uid1"
  const module1 = useModule.getModule("global_uid1");
  // to get an useModule element (It's a child element in the root useModule element) with usemodule_alias="alias1"
  const module2 = useModule.getModule("alias1");
  // to get an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  const module3 = useModule.getModule("alias_in_root.alias_in_level1.alias_in_level2");

useModule.sendMessageTo

useModule.sendMessageTo ( receiver, message )
  Sends a message to the target useModule element, which can be received in it's onMessage event
[return]
  Object, The return value of target useModule element's onMessage event
[parameters]

  • receiver [required] : String or Object, The target useModule element, which can be an useModule object, useModule uid or alias (if it's a child element in the root useModule element ).
  • message [required] : Object / Any, The message, can be any value
  // to sent a message to module1
  const result1 = useModule.sendMessageTo(module1, "message");
  // to sent a message to an useModule element with usemodule_uid="global_uid1"
  const resul2 = useModule.sendMessageTo("global_uid1", "message");
  // to sent a message to an useModule element ( a child element in the root useModule element) with usemodule_alias="alias1"
  const resul3 = useModule.sendMessageTo("alias1", "message");
  // to sent a message to an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  const resul4 = useModule.sendMessageTo("alias_in_root.alias_in_level1.alias_in_level2", "message");

useModule.dispatchActionTo

useModule.dispatchActionTo ( receiver, actionName, params, from)
  Dispatches an action of the target useModule element
[return]
  Object, The target action's return value
[parameters]

  • receiver [required] : String or Object, The target useModule, which can be an useModule object, useModule uid or alias (only for those child elements in the root useModule element ).
  • actionName [required] : String, The action name to be dispatched
  • params [optional] : Array, The parameters for the given action
  • from [optional] : Object/Any, The from info that indicates who dispatch the action or can be other info
  // to dispatch an action of module1
  const result1 = useModule.dispatchActionTo(module1, "actionName", [/*parameters*/]);
  // to dispatch an action of an useModule element with usemodule_uid="global_uid1"
  const resul2 = useModule.dispatchActionTo("global_uid1", "actionName", [/*parameters*/]);
  // to dispatch an action of an useModule element (a child element in the root useModule element) with usemodule_alias="alias1"
  const resul3 = useModule.dispatchActionTo("alias1", "actionName", [/*parameters*/]);
  // to dispatch an action of an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  const resul4 = useModule.dispatchActionTo("alias_in_root.alias_in_level1.alias_in_level2", "actionName", [/*parameters*/]);

useModule.dispatchAsyncActionTo

useModule.dispatchAsyncActionTo ( receiver, actionName, params, from)
  Dispatches an asynchronous action of the target useModule element
[return]
  Object, The target action's return value
[parameters]

  • receiver [required] : String or Object, The target useModule, which can be an useModule object, useModule uid or alias (only for the child elements in the root useModule element ).
  • actionName [required] : String, The asynchronous action name to be dispatched
  • params [optional] : Array, The parameters for the given action
  • from [optional] : Object/Any, The from info that indicates who dispatch the action or can be other info
  // to dispatch an action of module1, 
  const result1 = useModule.dispatchAsyncActionTo(module1, "asyncActionName", [/*parameters*/]);
  // to dispatch an action of an useModule element with usemodule_uid="global_uid1"
  const resul2 = useModule.dispatchAsyncActionTo("global_uid1", "asyncActionName", [/*parameters*/]);
  // to dispatch an action of an useModule element (a child elemnt in the root useModule element) with usemodule_alias="alias1"
  const resul3 = useModule.dispatchAsyncActionTo("alias1", "asyncActionName", [/*parameters*/]);
  // to dispatch an action of an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  const resul4 = useModule.dispatchAsyncActionTo("alias_in_root.alias_in_level1.alias_in_level2", "asyncActionName", [/*parameters*/]);

useModule.updateStateFor

useModule.updateStateFor ( target, path, state, force )
  Updates the module state for the target useModule element
[parameters]

  • target [required] : String or Object, The target useModule element, which can be an useModule element object, useModule uid or alias (only for those chlid elements in the root useModule element ).
  • path [required] : Object / Array< String > / String, If it's an Array< String >: to specify the path for updating the state; If it's a String: the string can be convert into an Array< String > after splitting by '.'; If it's an Object: to specify the whole object to update the state, the 2nd parameter - 'state' will be ignored in this case.
  • state [optional] : Object, The object to update the state in the given path
  • force [optional] : Boolean, Indicates whether force to update the state. Default is false.
  // to update state for module1
  useModule.updateStateFor(module1, { key:"value" });
  // to update state for an useModule element with usemodule_uid="global_uid1"
  useModule.updateStateFor("global_uid1", "key", "value");
  // to update state for an useModule element (a child element in the root useModule element) with usemodule_alias="alias1"
  useModule.updateStateFor("alias1", "keylevel1.keylevel2.keylevel3", "value");
  // to update state for an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  useModule.updateStateFor("alias_in_root.alias_in_level1.alias_in_level2", "key", "value");

useModule.fireEventTo

useModule.fireEventTo ( target, eventName, params, from)
  Fires an event of the target useModule element
[return]
  Object, The return value of the target event
[parameters]

  • target [required] : String or Object, The target useModule element, which can be an useModule element object, useModule uid or alias ( only for those child elements in the root useModule element ).
  • eventName [required] : String, The event name
  • params [optional] : Array, The parameters for the given event
  • from [optional] : Object/Any, The from info that indicates who fire the event or can be other info
  // to fire an event for module1
  const result1 = useModule.fireEventFor(module1, "eventName", [/*parameters*/]);
  // to fire an event for an useModule element with usemodule_uid="global_uid1"
  const resul2 = useModule.fireEventFor("global_uid1", "eventName", [/*parameters*/]);
  // to fire an event for an useModule element (a child element in the root useModule element) with usemodule_alias="alias1"
  const resul3 = useModule.fireEventFor("alias1", "eventName", [/*parameters*/]);
  // to fire an evnt for an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  const resul4 = useModule.fireEventFor("alias_in_root.alias_in_level1.alias_in_level2", "eventName", [/*parameters*/]);

useModule.broadcast

useModule.broadcast ( channelName, message)
  Broadcasts message to all useModule elements via a specified channel, which can be received in all useModule elements' onChannelMessage event
[parameters]

  • channelName [required] : String, The channel name
  • message [required] : Object / Any, The message object, can be any value
  // to broadcast an message to all useModule elements
  useModule.broadcast("channelName","message");

useModule.printModulesTree

useModule.printModulesTree ( )
  Prints the useModule element tree to the console window

  // to print the whole useModule element tree onto the console
  useModule.printModulesTree( );

useModule.resolveURL

useModule.resolveURL ( relPath )
  Resolves an url from a relative path. If you want to use a relative resource path in the CrossUI Designer, it's a must
[return]
  String, The resolved url
[parameters]

  • relPath [required] : String, The relative path for an url
  // to resolve a relative path for the resource url
  useModule.resolveURL("./img/pic.png");

useModule.getDataFromStore

useModule.getDataFromStore ( path )
  Gets data from the global store by the path
[return]
  Object, The result data
[parameters]

  • path [required] : Array< String > / String, If it's an Array< String >: to specify the path for the data; If it's a String: the string can be convert into an Array< String > after splitting by '.'

useModule.setDataToStore

useModule.setDataToStore ( path, value, clonePath )
  Sets data to the global store by the path
[parameters]

  • path [required] : Array< String > / String, If it's an Array< String >: to specify the path for the data; If it's a String: the string can be convert into an Array< String > after splitting by '.'
  • value [required] : Object / Any, The object to set
  • clonePath [optional] : Boolean, Determines whether to clone the path or not. Default is false.
  // to get data from the global store
  useModule.setDataToStore("path_level1.path_level2", {data:"value"}, false);
  // reusult: "value"
  useModule.getDataFromStore("path_level1.path_level2.data");

2.2. useModule utils functions

useModule.utils.getRand

useModule.utils.getRand ( preTag )
  Gets a random string. The result like 'ca1gis'.
[return]
  String, The random string.
[parameters]

  • preTag [optional] : String, The previous tag for the random string. Default is empty string.
  // The result like 'ca1gis
  useModule.getRand();
  // The result like 'id_ca1gis'
  useModule.getRand("id_");

useModule.utils.getNo

useModule.utils.getNo ( preTag )
  Gets a No. string. The result like 'a'.
[return]
  String, The No. string.
[parameters]

  • preTag [optional] : String, The previous tag for the No. string. Default is empty string.
  // The result like 'a'
  useModule.utils.getNo();
  // The result like 'id_a'
  useModule.utils.getNo("id_");

useModule.utils.deepGet

useModule.utils.deepGet ( object, path )
  Gets data from the given object by the path.
[return]
  Object/Any, The result data.
[parameters]

  • object [required] : Object, The target object.
  • path [required] : Array< String > / String, The path. If it's an Array< String >: to specify the path for the data; If it's a String: the string can be convert into an Array< String > after splitting by '.'
  // return 1
  useModule.utils.deepGet({a:{b:{c:1}}},'a.b.c');
  // return 1
  useModule.utils.deepGet({a:{b:{c:1}}},["a","b","c"]);

useModule.utils.deepSet

useModule.utils.deepSet ( object, path )
  Sets data to the given object by the path.
[return]
  Object/Any, The target object.
[parameters]

  • object [required] : Object, The target object.
  • path [required] : Array< String > / String, The path. If it's an Array< String >: to specify the path for the data; If it's a String: the string can be convert into an Array< String > after splitting by '.'
  • value [required] : Object/Any, The value to set.
  • clonePath [optional] : Boolean, Determines whether to clone the path or not. Default is false.
  // result : {a:{b:{c:2}}}
  useModule.utils.deepSet({a:{b:{c:1}}},'a.b.c', 2);
  // result : {a:{b:{c:[1,2,3]}}}
  useModule.utils.deepSet({a:{b:{c:1}}},["a","b","c"], [1,2,3]);

useModule.utils.deepClone

useModule.utils.deepClone ( object )
  Clones the given object deeply.
[return]
  Object/Any, The cloned object.
[parameters]

  • object [required] : Object, The target object to be cloned.
  const source = {a:{b:{c:1}}};
  // cloned : {a:{b:{c:1}}}
  // cloned.a === source.a      > false
  // cloned.a.b === source.a.b  > false
  const cloned = useModule.utils.deepClone(source);

useModule.utils.toUTF8

useModule.utils.toUTF8 ( source )
  Converts a string to UTF-8 string.
[return]
  String, The result UTF-8 string .
[parameters]

  • utf8string [required] : String, The target string to be converted.

useModule.utils.fromUTF8

useModule.utils.fromUTF8 ( utf8string )
  Converts an UTF-8 string back.
[return]
  String, The result string .
[parameters]

  • utf8string [required] : String, The target UTF-8 string to be converted.
  const source = '漢字';
  // "\u6f22\u5b57"
  const utf8 = useModule.utils.toUTF8(source);
  // source === back
  const back = useModule.utils.fromUTF8(utf8 );
  console.log(utf8, back);

useModule.utils.makeURLQueryString

useModule.utils.makeURLQueryString ( hash )
  Converts an object into an url query string.
[return]
  String, The result query string.
[parameters]

  • hash [required] : Object, The target object to be converted.

useModule.utils.getURLParams

useModule.utils.getURLParams ( querystring )
  Converts an object into an url query string.
[return]
  String, The result query string.
[parameters]

  • querystring [required] : Object, The target querystring.
  • parameter [optional] : String, The parameter key string. If don't specify this, it will return an object that presents all parameters.
  const hash = {k1:"v1",k2:"v2"};
  // return "k1=v1&k2=v2"
  const qs= useModule.utils.makeURLQueryString(hash);
  // return {k1:"v1",k2:"v2"}
  const back = useModule.utils.getURLParams(utf8 );
  // return "v2"
  const value = useModule.utils.getURLParams(utf8, "k2" );
  console.log(qs, back, value );

useModule.utils.getCookie

useModule.utils.getCookie ( name )
  Gets a specified cookie with the given name.
[return]
  String/Object/Array, The result cookie for the given name. If it's a stringified object or array, it will return the original object or array.
[parameters]

  • name [required] : String, The cookie name.

useModule.utils.setCookie

useModule.utils.setCookie ( name, value, options )
  Creates a cookie with the given name, value, and options.
[parameters]

  • name [required] : String, The cookie name.
  • value [required] : String/Object/Array, The value of cookie. If it's an Object or Array, a stringified string will be saved into Cookie.
  • options [options] : Object, The cookie options. { expires: Number for seconds, path: String, domain: String, maxAge: String, sameSite: Boolean, secure: Boolean, httpOnly: Boolean }.

useModule.utils.removeCookie

useModule.utils.removeCookie ( name )
  Removes a specified cookie by the given name.
[parameters]

  • name [required] : String, The cookie name.

useModule.utils.clearCookie

useModule.utils.clearCookie ( )
  Clears all cookies.

  useModule.utils.setCookie("c1", "v1");
  useModule.utils.setCookie("c2", {k1:"v1",k2:"v2"});
  // return "v1"
  const cookie1 = useModule.utils.getCookie( "c1" );
  // return {k1:"v1",k2:"v2"}
  const cookie2 = useModule.utils.getCookie( "c2" );
  console.log( cookie1, cookie2 );
  useModule.utils.removeCookie( "c1" );
  useModule.utils.clearCookie( );

useModule.utils.getLocalStorage

useModule.utils.getLocalStorage ( name )
  Gets a specified local storage by the given name.
[return]
  String/Object/Array, The result local storage for the given name. If it's a stringified object or array, it will return the original object or array.
[parameters]

  • name [required] : String, The local storage name.

useModule.utils.setLocalStorage

useModule.utils.setLocalStorage ( name, value )
  Creates a local storage data with the given name and value.
[parameters]

  • name [required] : String, The local storage name.
  • value [required] : String/Object/Array, The value of local storage. If it's an Object or Array, a stringified string will be saved into local storage.

useModule.utils.removeLocalStorage

useModule.utils.removeLocalStorage ( name )
  Removes a specified local storage by the given name.
[parameters]

  • name [required] : String, The local storage name.

useModule.utils.clearLocalStorage

useModule.utils.clearLocalStorage ( )
  Clears all local storage.

  useModule.utils.setLocalStorage ("c1", "v1");
  useModule.utils.setLocalStorage ("c2", {k1:"v1",k2:"v2"});
  // return "v1"
  const sto1 = useModule.utils.getLocalStorage( "c1" );
  // return {k1:"v1",k2:"v2"}
  const sto2 = useModule.utils.getLocalStorage( "c2" );
  console.log( sto1, sto2 );
  useModule.utils.removeLocalStorage( "c1" );
  useModule.utils.clearLocalStorage( );

useModule.utils.postH5ChannelMessage

useModule.utils.postH5ChannelMessage ( channelName, message)
  Posts HTML5 message ( ref: window.BroadcastChannel ) to all browser windows via a specified channel, which can be received in all useModule components' onH5ChannelMessage event
[parameters]

  • channelName [required] : String, The channel name
  • message [required] : Object / Any, The message object, can be any value
  // to pose HTML5 message to all browser windows via "channel1"
  useModule.utils.postH5ChannelMessage ("channel1","message");

useModule.utils.selectLocalFiles

useModule.utils.selectLocalFiles ( contentType, multiple )
  To show an browser's file dialog for selecting files. You must use 'await' to call it, and it must be in an async function.
[return]
  Array < File >, The result files.
[parameters]

  • contentType [optional] : String, The content type. e.g. 'image/png', 'image/*'
  • multiple [optional] : Boolean, Allows multiple files or not. Default is false
  import { useModule } from "react-module-hook";
  //...
  const App = props => {
      const { module } = useModule(props, { }); 
      return (
        <div>
          <button onClick={async () => {
            const files = await useModule.utils.selectLocalFiles("image/*", true);
            console.log(files);
          }}>module.request</button>
        </div>
      );
  };

2.3. useModule instance - module functions

getRootModule

getRootModule ( )
  Gets the root useModule element
[return]
  Object, The root useModule element

  // to get the root useModule element
  const rootModule = module.getRootModule();

getModule

getModule ( idOrAlias )
  Gets the useModule element by uid (usemodule_uid) or alias (usemodule_alias). Getting from alias is only for the child elements in the root useModule element )
[return]
  Object, The result module element
[parameters]

  • idOrAlias [required] : String, The target useModule element's uid or alias
  // to get an useModule element with usemodule_uid="global_uid1"
  const module1 = module.getModule("global_uid1");
  // to get an useModule element( a child element in the current module) with usemodule_alias="alias1"
  const module2 = module.getModule("alias1");
  // to get an useModule element with alias path: ["alias_in_root", "alias_in_level1", "alias_in_level2"]
  const module3 = module.getModule("alias_in_root.alias_in_level1.alias_in_level2");

getModuleByAlias

getModuleByAlias ( alias )
  Gets a useModule element by the given alias in the current module, which must be a child element in the current module and has an alias (usemodule_alias property)
[return]
  Object, The result module element
[parameters]

  • alias [required] : String, The alias of the element
  // to get a child module in the current module with usemodule_alias="alias1"
  const childModule = module.getModuleByAlias("alias1");

sendMessage

sendMessage ( message )
  Sends a message to the current useModule, which can be received in it's onMessage event
[return]
  Object, The return value of the module's onMessage event
[parameters]

  • message [required] : Object / Any, The message object, can be any value
  // to sent a message
  const result1 = module.sendMessage("message");

dispatchAction

dispatchAction ( actionName, params, from )
  Dispatches an action for the current useModule element
[return]
  Object, The target action's return value
[parameters]

  • actionName [required] : String, The action name to be dispatched
  • params [optional] : Array, The parameters for the given action
  • from [optional] : Object/Any, The from info that indicates who dispatch the action or can be other info
  // to dispatch an action
  const result1 = module.dispatchAction("actionName", [/*parameters*/]);

dispatchAsyncAction

dispatchAsyncAction ( actionName, params, from)
  Dispatches an asynchronous action for the current useModule element
[return]
  Object, The target action's return value
[parameters]

  • actionName [required] : String, The asynchronous action name to be dispatched
  • params [optional] : Array, The parameters for the given action
  • from [optional] : Object/Any, The from info that indicates who dispatch the action or can be other info
  // to dispatch an async action
  const result1 = module.dispatchAsyncAction("asyncActionName", [/*parameters*/]);

updateState

updateState ( path, state, force )
  Updates the module state for the current useModule
[parameters]

  • path [required] : *Object / Array< String > / String, *If it's an Array< String >: ** to specify the path for updating the state; If it's a String: the string can be convert into an Array< String > after splitting by '.'; If it's an Object: to specify the whole object to update the state, the 2nd parameter - 'state' will be ignored in this case.
  • state [optional] : Object/Any, The object to update the state in the given path
  • force [optional] : Boolean, Indicates whether force to update the state. Default is false.
  // If the old state is {key:'ovalue',key1:{key2:'ovalue'}}
  // the new state will be {key:'nvalue',key1:{key2:'ovalue'}}
  module.updateState({ "key":"nvalue" });
  // the new state will be {key:'nvalue',key1:{key2:'nvalue'}}
  module.updateState("key1,key2", "nvalue");

fireEvent

fireEvent ( eventName, params, from )
  Fires a specified event for the current useModule
[return]
  Object, The return value of the target event
[parameters]

  • eventName [required] : String, The event name
  • params [optional] : Array, The parameters for the given event
  • from [optional] : Object/Any, The from info that indicate who fire the event or can be other info
  // to fire an event 
  const result1 = module.fireEvent("eventName", [/*parameters*/]);

broadcast

broadcast ( channelName, message )
  Broadcasts message to all useModule elements via a specified channel, which can be received in all useModule components' onChannelMessage event.
[parameters]

  • channelName [required] : String, The channel name
  • message [required] : Object / Any, The message object, can be any value
  // to broadcast an message to all useModule elements
  useModule.broadcast("channelName","message");

useRef

useRef ( refName, value )
  Triggers a React.useRef to create a ref, which initialial value is 'value'. It can be retrieved by module.getRef('refName') .
[return]
  Object, The ref
[parameters]

  • refName [required] : String, The ref name
  • value [optional] : Object/Any, The given initialial value

getRef

getRef ( refName )
  Gets a specified ref by the given name, this ref was created by module.useRef('refName', 'value').
[return]
  Object, The ref
[parameters]

  • refName [required] : String, The ref name
  // to use(create) a ref
  const ref = module.useRef("refName", "init vaule");
  // to get the ref
  const ref1 = module.getRef("refName");  
  // or
  const ref2 = module.refs["refName"];

renderComAs

renderComAs ( x_id, replace, beforeNodes, afterNodes )
  Renders an enhanced component (with a specified 'x_id') as a different component or a set of components, which can be used as element replacement, or inserting additional elements before or after the element.
[parameters]

  • x_id [required] : String, The target element's x_id. The target element must be an enhanced component which powered by module.enhanceCom()
  • replace [optional] : Object/Array/false, A React element or React elements array, which will replace the current element in the UI. If specified [false], this parameter will be ignored. If specified [null], the original element will be restored. Default is null.
  • beforeNodes [optional] : Object/Array/false, A React element or React elements array, which will be inserted before the current element. If specified [false], this parameter will be ignored. If specified [null], all beforeNodes will be removed. Default is null.
  • afterNodes [optional] : Object/Array/false, A React element or React elements array, which will be inserted after the current element. If specified [false], this parameter will be ignored. If specified [null], all afterNodes will be removed. Default is null.
  const Com1= props => {
      const { module } = useModule(props, { });
      const XElem = module.enchanceCom("div");
      return (
      <div>
          <XElem x_id="x_id1">original</XElem>
          <button onClick={() =>{
              module.renderComAs("x_id", <input />, false, false);
          }}>replace</button>
          <button onClick={() =>{
              module.renderComAs("x_id", false, <div>before</div>, false);		  
          }}>insert before</button>
          <button onClick={() =>{
              module.renderComAs("x_id", false, false, <div>after</div>);		  
          }}>insert after</button>		  
          <button onClick={() =>{
              module.renderComAs("x_id", null, null, null);
          }}>restore</button>
      </div>);
  };

2.4. useModule instance - material-UI plugin functions

showSnackbar

showSnackbar ( message )
  To show a material-UI snackbar. It's an advanced function in material-UI plugin ( react-module-hook/plugin_mui )
[parameters]

  • message [required] : String/Object, The message (String), or the props (Object) of the Snackbar
  import { useModule } from "react-module-hook";
  // must import material-UI plugin
  import "react-module-hook/plugin_mui";
  //...
  // to show a snack bar
  module.showSnackbar("snack message");

alert

alert ( title, description, okCaption )
  To show an material-UI alert window. It's an advanced function in material-UI plugin ( react-module-hook/plugin_mui ). You must use 'await' to call it, and it must be in an async function.
[parameters]

  • title [required] : String, The title text
  • description [required] : String, The description text
  • okCaption [optional] : String, The caption text for OK button. Default is "OK".
  import { useModule } from "react-module-hook";
  // must import material-UI plugin
  import "react-module-hook/plugin_mui";
  //...
  (async()=>{
      // to show an alert dialog
      await module.alert("title", "desc", "O K");
  })();

confirm

confirm ( title, description, okCaption, cancelCaption )
  To show an material-UI confirm window. It's an advanced function in material-UI plugin ( react-module-hook/plugin_mui ). You must use 'await' to call it, and it must be in an async function.
[return]
  Boolean, the confirm result.
[parameters]

  • title [required] : String, The title text
  • description [required] : String, The description text
  • okCaption [optional] : String, The caption text for OK button. Default is "OK".
  • cancelCaption [optional] : String, The caption text for cancel button. Default is "Cancel".
  import { useModule } from "react-module-hook";
  // must import material-UI plugin
  import "react-module-hook/plugin_mui";
  //...
  (async()=>{
      // to show an confirm dialog
      const result = await module.cofirm("title", "desc");
  })();

prompt

prompt ( title, description, defaultValue, okCaption, cancelCaption )
  To show an material-UI prompt window. It's an advanced function in material-UI plugin ( react-module-hook/plugin_mui ). You must use 'await' to call it, and it must be in an async function.
[return]
  String, the input text.
[parameters]

  • title [required] : String, The title text
  • description [required] : String, The description text
  • defaultValue [optional] : String, The default value text. Default is empty string.
  • okCaption [optional] : String, The caption text for OK button. Default is "OK".
  • cancelCaption [optional] : String, The caption text for cancel button). Default is "Cancel".
  import { useModule } from "react-module-hook";
  // must import material-UI plugin
  import "react-module-hook/plugin_mui";
  //...
  (async()=>{
      // to show an confirm dialog
      const result = await module.prompt("title", "desc");
  })();

showBackdrop

showBackdrop ( id, clickAway, style, transitionDuration, children)
  To show a backdrop for a given id. It's an advanced function in material-UI plugin ( react-module-hook/plugin_mui ).
[parameters]

  • id [optional] : String, The backdrop id, default is 'default'
  • clickAway [optional] : Boolean, To determine whether 'click' to hide the backdrop or not, default is true.
  • style [optional] : Object, To determine the backdrop's style, default is {}.
  • transitionDuration [optional] : Number, The transition duration in ms. Default is 300.
  • children [optional] : Array/Boolean, The children elements in the backdrop. Default is true > there'll be an CircularProgress in the backdrop.
  import { useModule } from "react-module-hook";
  // must import material-UI plugin
  import "react-module-hook/plugin_mui";
  //...
  module.showBackdrop( );

hideBackdrop

hideBackdrop ( id )
  To hide a backdrop for a given id. It's an advanced function in material-UI plugin ( react-module-hook/plugin_mui ).
[parameters]

  • id [optional] : String, The backdrop id, default is 'default'.
  import { useModule } from "react-module-hook";
  // must import material-UI plugin
  import "react-module-hook/plugin_mui";
  //...
  module.hideBackdrop( );

2.5. useModule instance - request plugin functions

request

request ( url, data, method, baseURL, AUTH_TOKEN, header, config )
  To request data from a remote service endpoint, by axios. It's an advanced function in request plugin ( react-module-hook/plugin_request ). You must use 'await' to call it, and it must be in an async function.
[return]
  Object, the request result.
[parameters]

  • url [required] : String, The url option for an axios reqeust
  • data [optional] : Object/String, The data (ArrayBuffer, ArrayBufferView, URLSearchParams, FormData, File, Blob, or queryString) option for an axios reqeust Default is null.
  • method [optional] : String, The method (get/post/put/delete/patch/head/options) option for an axios reqeust. Default is 'get'.
  • baseURL [optional] : String, The base URL option for an axios reqeust. Default is empty string.
  • AUTH_TOKEN [optional] : String, The AUTH_TOKEN option for an axios reqeust. Default is null.
  • header [optional] : Object, The header option for an axios reqeust. Default is {}.
  • config [optional] : Object, The config option for an axios reqeust.Default is {}.
  import { useModule } from "react-module-hook";
  // must import request plugin for 
  import "react-module-hook/plugin_request";
  //...
  const App = props => {
      const { module } = useModule(props, { }); 
      return (
        <div>
          <button onClick={async () => {
            const result = await  module.request(useModule.resolveURL("./service/endpoint"));
            console.log( result );
          }}>module.request</button>
        </div>
      );
  };

request.fetch

request.fetch( )
  To fetch data for the useModule's default request, only for the props with req_execute=false. You must use 'await' to call it, and it must be in an async function.
[return]
  Object, the request result.

  import { useModule } from "react-module-hook";
  import { If } from "react-module-hook";
  // must import request plugin
  import "react-module-hook/plugin_request";
  //...
  const App = props => {
      // If no 'req_url', the request will be undefined 
      const { module, request } = useModule(props, {
        props:{
          req_url: useModule.resolveUrl("./service/endpoint"),
          req_execute: false
        }
      }); 
      return (
        <div>
          <div>Status: [{request.status}]</div>
          <If condition={request.error} >
            error: {request.error && JSON.stringify(request.error)}
          </If>
          <If condition={request.response} >
            data: {request.response && JSON.stringify(request.response)}
          </If>
          <button onClick={async () => {
            const result = await request.fetch();
            console.log( result );
          }}>fetch</button>
        </div>
      );
  };

Normally, you don't need to set 'req_execute' to false for the default request in an useModule. The default request will be executed automatically.

  import { useModule } from "react-module-hook";
  import { If } from "react-module-hook";
  // must import request plugin
  import "react-module-hook/plugin_request";
  //...
  const App = props => {
      // If no 'req_url', the request will be undefined 
      const { module, request } = useModule(props, {
        props:{
          req_url: useModule.resolveUrl("./service/endpoint")
        }
      }); 
      return (
        <div>
          <div>Status: [{request.status}]</div>
          <If condition={request.error} >
            error: {request.error && JSON.stringify(request.error)}
          </If>
          <If condition={request.response} >
            data: {request.response && JSON.stringify(request.response)}
          </If>
        </div>
      );
  };

request.cancel

request.cancel( )
  To cancel the useModule's default request.

  import { useModule } from "react-module-hook";
  // must import request plugin
  import "react-module-hook/plugin_request";
  //...
  const App = props => {
    // If no 'req_url', the request will be undefined 
    const { module, request } = useModule(props, {
      props:{
        req_url: useModule.resolveUrl("./service/endpoint")
      }
    }); 
    // cancel the useModule's default request
    React.useEffect(() => request.cancel(), [request]);
      return (
        <div>
          <div>Status: [{request.status}]</div>
        </div>
      );
  };

2.6. useModule instance - router plugin functions

router.navigate

router.navigate ( route, state )
  *To navigate to target route (document). *
[parameters]

  • route [required] : String, The route path.
  • state [optional] : Object, The state. [router.navigate('/', {replace: true})] equals to [router.replace('/')] .

router.replace

router.replace( route )
  *To replace the document by target route. *
[parameters]

  • route [required] : String, The route path.

--->router.replace(route) equlas to router.navigate(route ,{replace: true}).

router.setSearchParams

router.setSearchParams( params )
  *[for useModule router plugin] To update the search parameters. *
[parameters]

  • params [required] : Object/String, The search params. Object or queryString.
  import { useModule } from "react-module-hook";
  // must import request plugin
  import { BrowserRouter as  Router, RelativeRouter } from  "react-module-hook/plugin_router";
  //...
  const App = props => {
      // If no 'router' in props, or 'props.router' is false, the router will be undefined 
      const { module, router } = useModule(props, {
        props:{
          router : true
        }
      }); 
      return (
        <Router>
            <RelativeRouter>
                <div path="/path1">path1</div>
                <div path="/path2">path2</div>
                <div path="/about">about</div>
                <div path="*">Not Support</div>
            </RelativeRouter>
            <div>
                <button onClick={() => {
                    router.navigate('/about');
                }}>Route to "/about"</button>
                <button onClick={() => {
                    router.setSearchParams('k1=v1&k2=v2');
                }}>setSearchParams</button>				
            </div>
        </Router>
      );
  };

2.7. useModule instance - auth plugin functions

auth.signIn

auth.signIn ( )
  To trigger the sign in action.

auth.signOut

auth.signOut ( )
  To trigger the sign out action.

auth.signUp

auth.signUp( )
  To trigger the sign up action.

File - auth_fake.js

  import {utils} from "react-module-hook";
  // singIn function
  const signIn = function(){
    const auth = this;
    const user = {email:"fake@email.com"};
    setTimeout(() => {
      auth.setUser(user);
      utils.setCookie("user", user);
    }, 500);
  };
  // signOut function
  const signOut = function(){
    this.setUser(null);
    utils.removeCookie("user");
  };
  // signUp function
  const signUp = function(){
    console.log("signUp function");
  };  
  const authInit = function(){
    const auth = this;
    const user = utils.getCookie("user");
    user && auth.setUser(user);
    return function(){
      // nothing
    };
  };
  export default {signIn, signOut, authInit};

File - index.js

  import React from "react";
  import ReactDOM from "react-dom";
  import { useModule } from "react-module-hook";
  import { ProvideAuth } from "react-module-hook/plugin_auth";
  import App from "./App";
  import configure from "./auth_fake.js";
  ReactDOM.render( (
    <React.StrictMode>
      <ProvideAuth {...configure} >
        <App path="/*" />
      </ProvideAuth>
    </React.StrictMode>
  ), document.getElementById("root"));

File - App.js

  import React from "react";
  import { useModule } from "react-module-hook";
  import { If } from "react-module-hook";
  const App = props => {
      // If no 'auth' in props, or 'props.auth' is false, the auth will be undefined 
      const { module, auth } = useModule(props, { auth: true });
      return (
      <React.Fragment>
        <If condition={auth && auth.user} >
          <div> Signed in successfully!</div>
          <div> User Email: {auth && auth.user && auth.user.email} </div>
          <div> <button onClick={() => auth.signOut()}>Sign Out</button> </div>
        </If>
        <If condition={!auth || !auth.user} >
          <div><button onClick={() => auth.signIn()}>Sign In</button></div>
        </If>
      </React.Fragment>
    );
  };

3. Quickstart

3.1. Basic Demo

import React from "react";
import { useModule } from "react-module-hook";

export default (props) => {  
  const { module } = useModule(props, {
    actions: {
      callback: (msg) => module.updateState({ msg })
    }
  });
  return (
    <div style={{ border: "1px dashed", padding: "1em" }}>
      <h2>useModule demo {">"} modules interaction</h2>
      <div><strong>{"<"}Module1{">"}</strong></div>{" "} <p />
      <button onClick={(e) => module.updateStateFor("alias_in_parent", { value: "Value updated by updateState" }) }>
        updateState for Module2
      </button>{" | "}
      <button onClick={(e) => module.sendMessageTo("alias_in_parent", "Value updated by sendMessage") }>
        sendMessage to Module2
      </button>{" | "}
      <button onClick={(e) => useModule.dispatchActionTo("global_uid", "updValue", [ "Value updated by dispatchAction" ]) }>
        dispatchAction to Module2
      </button><p />
      <div> Callback Message: "{module.state.msg || "No callback yet"}"</div><p />
      <Module2 usemodule_alias="alias_in_parent" usemodule_parent={module}/>
      <Module2 usemodule_uid="global_uid"/> 
    </div>
  );
};

export const Module2 = (props) => {
  const { module } = useModule(props, {
    props: {
      onMessage: (value) => {
        module.updateState({ value });
        module.parent.dispatchAction("callback", ["Message received"]);
      }
    },
    actions: {
      updValue: (value) => {
        module.updateState({ value });
      }
    }
  });
  return (
    <div style={{ border: "1px dashed", padding: "1em" }}>
      <div><strong>{"<"}Module2{">"}</strong> ( {props.usemodule_alias?("alias='" + props.usemodule_alias+"'"):""} {props.usemodule_uid?("uid='" + props.usemodule_uid+"'"):""} )</div>{" "}<p />
      value = "<strong>{module.state.value}</strong>"
    </div>
  );
};

Screenshot

Module Tree

[root]
  │  
  ├─<Module1>
  │     │  
  │     └<Module2 usemodule_alias="alias_in_parent">
  │      
  └<Module2 usemodule_uid="global_uid">

Open the demo in CodeSandbox

3.2. Meterial UI Demo

import React from "react";
import { useModule } from "react-module-hook";
import Button from "@material-ui/core/Button";
import { makeStyles } from "@material-ui/core/styles";
import Dialog from "@material-ui/core/Dialog";
import TextField from "@material-ui/core/TextField";
import DialogActions from "@material-ui/core/DialogActions";
import DialogContent from "@material-ui/core/DialogContent";
import DialogContentText from "@material-ui/core/DialogContentText";
import DialogTitle from "@material-ui/core/DialogTitle";

const useStyles4basic = makeStyles(theme => ({ item: { margin: theme.spacing(1) }, container: { padding: theme.spacing(1) } }));
const useStyles4Modal = makeStyles(theme => ({ root: { display: 'flex', alignItems: 'center', justifyContent: 'center' }, paper: { backgroundColor: theme.palette.background.paper, border: '2px solid #000', boxShadow: theme.shadows[5], padding: theme.spacing(2, 4, 3) } }));

const Module_Dialog = props => {
    const { module } = useModule(props, { });
    const styles_basic = useStyles4basic(props || {});

    return (
      <React.Fragment>
          <Button variant="contained" color="primary" className={ styles_basic.item } key="cyenksua" onClick={ ( e ) => {module.updateStateFor("Alert_1", { open: true });} }>Alert</Button>
          <Button variant="contained" color="secondary" className={ styles_basic.item } onClick={ e => {module.dispatchActionTo("Confirm_1", "open"); } }>Confirm</Button>
          <Button variant="contained" color="default" className={ styles_basic.item } onClick={ e => {module.sendMessageTo("Prompt_1", "open");} }>Prompt</Button>

          <Alert  open={ false } usemodule_alias="Alert_1" usemodule_parent="{module}" title="Alert" description="Description" onOK={ () => alert("OK") }></Alert>
          <Confirm  open={ false } usemodule_alias="Confirm_1" usemodule_parent="{module}" title="Confirm" description="Description" onOK={ () => alert("OK") } onCancel={ () => alert("onCancel") } ></Confirm>
          <Prompt  open={ false } usemodule_alias="Prompt_1" usemodule_parent="{module}" title="Prompt" description="Description" onOK={ txt => alert("Result: " + txt) }  onCancel={ () => { alert("onCancel"); } }></Prompt>
      </React.Fragment>
    );
};

export default Module_Dialog;

export const Alert = props => {
    const style_modal = useStyles4Modal();
    const { module } = useModule(props, {
        props: {
            open: true,
            title: "Title",
            description: "Description",
            onOK: () => {}
        },
        state: {
            open: false
        },
        "actions": {
            "open": function () {
                this.updateState({ open: true });
            },
            "close": function () {
                this.updateState({ open: false });
            }
        }
    });
    const [defaultState, setDefaultState] = React.useState({
        "open": false
    });

    return  <React.Fragment>
        <Dialog open={module.props.open || module.state.open} onClose={() => module.dispatchAction("close")} fullWidth aria-labelledby="alert_9za5tayt_title" aria-describedby="alert_9za5tayt_description" key="7e8gz5b3">
            <DialogTitle id="alert_9za5tayt_title"> {module.props.title} </DialogTitle>
            <DialogContent>
              <DialogContentText id="alert_9za5tayt_description">{module.props.description}</DialogContentText>
            </DialogContent>
            <DialogActions>
              <Button onClick={() => { module.props.onOK();module.dispatchAction("close");}}  color="primary"> OK </Button>
            </DialogActions>
          </Dialog>
        </React.Fragment>
    ;
};

export const Confirm = props => {
    const style_modal = useStyles4Modal();
    const { module } = useModule(props, {
        props: {
            open: true,
            title: "Title",
            description: "Description",
            onOK: () => {},
            onCancel: () => {}
        },
        state: {
            open: false
        },
        "actions": {
            "open": function () {
                this.updateState({ open: true });
            },
            "close": function () {
                this.updateState({ open: false });
            }
        }
    });
    const [defaultState, setDefaultState] = React.useState({
        "open": false
    });

    return <React.Fragment>
            <Dialog open={module.props.open || module.state.open} onClose={() => module.dispatchAction("close")} fullWidth aria-labelledby="confirm_jlh80pil_title" aria-describedby="confirm_jlh80pil_description" key="2h6e3jqi">
                <DialogTitle>{props.title}</DialogTitle>
                <DialogContent>
                    <DialogContentText>{props.description}</DialogContentText>
                </DialogContent>
                <DialogActions>
                    <Button onClick={() => {
                      module.props.onCancel();module.dispatchAction("close");
                    }} color="secondary">Cancel</Button>
                    <Button onClick={() => {module.props.onOK();module.dispatchAction("close");}} color="primary">OK</Button>
                </DialogActions>
            </Dialog>
        </React.Fragment>
    ;
};

export const Prompt = props => {
    const style_modal = useStyles4Modal();
    const { module } = useModule(props, {
        "props": {
            "open": true,
            "title": "Title",
            "description": "Description",
            "onOK": () => {},
            "onCancel": () => alert(9),
            "onMessage": msg => {
                if (msg == "open") {
                    module.updateState({
                        open: true
                    });
                }
            }
        },
        "state": {
            "open": false
        },
        "actions": {
            "open": function () {
                this.updateState({
                    open: true
                });
            },
            "close": function () {
                this.updateState({
                    open: false
                });
            }
        }
    });
    const [defaultState, setDefaultState] = React.useState({
        "open": false
    });

    return <React.Fragment>
            <Dialog open={module.props.open || module.state.open} onClose={() => module.dispatchAction("close")} fullWidth aria-labelledby="prompt_fn69vqpc_title" aria-describedby="prompt_fn69vqpc_description" key="blg87o2c">
                <DialogTitle>{props.title}</DialogTitle>
                <DialogContent>
                    <DialogContentText>{props.description}</DialogContentText>
                    <TextField autoFocus margin="dense" defaultValue="" fullWidth onChange={e => 
                      setDefaultState(Object.assign({}, defaultState, { text: e.target.value }))
                    }></TextField>
                </DialogContent>
                <DialogActions>
                    <Button color="secondary" onClick={() => props.onCancel()}>Cancel</Button>
                    <Button onClick={() => {
                      props.onOK(defaultState.text);module.dispatchAction("close");
                    }} color="primary">OK</Button>
                </DialogActions>
            </Dialog>
        </React.Fragment>
    ;
};

Screenshot

Module Tree

[root]
  │  
  └─<Module_Dialog >
         │  
         ├<Alert usemodule_alias="Alert_1">
         │  
         ├<Confirm usemodule_alias="Confirm_1">
         │  
         └<Prompt usemodule_uid="Prompt_uid">

Open the demo in CodeSandbox

npm

npm link