widget-router v0.4.6

Description

This is another TypeScript Router (also Javascript), but this one works better if used in widgets inside HTML.

Widget Router does not change the browser history or modifies the address bar. The main reason to use this router is if you need to iterate through divs, setting visible the active one and invisible the rest of them.

The router receives a configuration object descripted bellow, and returns to a controller (configured inside that configuration object) a RouteResult object, containing among other things an instance of the router itself and a memory scope created specifically for that controller.

Widget Router does not compile or render any templates (it only injects the template content set on route configuration inside the container div), if you need to do this, pass a renderer object to the router constructor and the router will send it to the controller you set in configuration. In this way, you could compile and render yourself any kind of template you want (react, jsrender, angular, pug, and whatever you want…) but from inside your controller.

How to Install and Configure

npm install widget-router

var RouterBuilder = require('widget-router');
var containerId = '#myDivContainer'; // (Mandatory) Id to the Div Container of all widget pages.
var routerConfiguration = {
	afterRouteInitController: true, // (Optional) If you dont want the router init a controller after "go" execution set this to false. Default: false.
	pageIdPrefix: 'widget_router_', // (Optional) If you want that the router set a prefix on the id of all pages inside the Div Container.
	usingTemplates: false; // (Optional) If set to true, then widget router will not inject the templates content inside widget page container (So you will need to render the template) and will be created a templatesCollection object inside the controllerHelper Object that will contain the template you set in router configuration. The template will be included inside an attribute named exactly like the route name you configure.
    routes: [
		{
			name: "main", // (Mandatory) Name of the Route
			template: '<h1>Main Page</h1><input type="button" value="go to secondary" onclick="WidgetRouter.go(&quot;secondary&quot;);"/><p>Main page description</p>', // (Optional) Template String that will be injected inside the widget page.
			controller: function(routeResult) {} // (Optional) Controller Function that will be executed after "go" method execution. The routeResult object will be described bellow.
		},
		{
			name: "secondary",
			templateFile: "tmpSecondary.html", // (Optional) If you set a template file. Widget Router will download it using XHR and will return a Promise with the RouteResult object. You may need to enable Cors calls on your sever if needed.
			controller: function(routeResult){
				//do Stuff with routeResult, perhaps compile and render the templateFile included inside 'widget_router_secondary'.
			}
		}
    ]
}
var appScope = {}; // (Optional) Memory Scope that will be passed to your controller. So it can be used to render the data inside this.
var controllerHelper = { // (Optional) This object will be also passed to your controller, and can be used to share data between widget pages, and also for passing a renderer objet to the controller.
	sharedData : {},
	renderer: {}, // can be a React or Pug Renderer for example.
	templatesCollection: {}
}
var WidgetRouter = new RouterBuilder.WidgetRouter(containerId, routerConfiguration, appScope, controllerHelper);
WidgetRouter.go('main').then(()=> {
 /// do some work after 'go' completed...
});

##RouteResult Object Description

RouteResult {
  routeName: string; // Name of the route that is calling the controller.
  routeParams: any; // Params passed to the route that will need to handle the controller.
  routeScope: any; // Scope created by the router specifically for this controller.
  router: any; // router object. With it, you can re-route to another page within the controller. Use: router.go('another_page');
  controllerHelper: any; // Object Helper that can contain a shared scope between controllers, can also contain a renderer object that could be used to compile and render the template inside the page.
}

##Events "beforego" and "aftergo"

If you want to inject some functions executions before or after the method go is executed. Then you can do it this way:

  
  WidgetRouter.on('beforego', (event, sender) => {
    return new Promise(function(resolve, reject) {
      setTimeout(() => {
        console.log('event ' + event + ' will be executed after this async method');
        resolve();
      }, 100);  
    });
  });

  WidgetRouter.on('beforego', (event, sender) => {
    console.log('do something before go event gets executed');
  });

  WidgetRouter.on('aftergo', (event, sender) => {
    console.log('do something after go event have finished');
  });

##Notes

If you are going to use this library with webpack, please add this alias inside your webpack.config.js:

alias: {
    "widget-router": "widget-router/dist/widget-router"
}

If you are using a Template Renderer, please set to true in routerConfiguration the usingTemplates variable, this will prevent that the template (uncompile and unrendered) will be showed to the client, but remember that you will need to compile and render the template yourself. The template content will be inside the controllerHelper objetc as a public property named "templatesCollection", and every attribute inside that object correspond to a route name.