Router - globules-io/OGX.JS GitHub Wiki

Navigation

Check out the Routes subsection to know how to navigate between sections

Request

To retrieve the request associated with the original GET, and the route found for this request, do

 const req = app.router.request();
 console.log(req);     

Note that window is always set to false when the request is the result of a goto within your app, and that origin is always set to null upon first load of the application.

First load of the app, window is the URL request upon a hard GET, for instance, if you app was bookmarked at a certain route/url, and the user loaded with app with /app#some_stage/some_route

 {route: {…}, url: 'default_stage/default_route', origin: null, window: 'some_stage/some_route'}

When you navigate with goto within the app

 {route: {…}, url: 'some_stage/some_route', origin: 'default_stage/default_route', window: false}

Options

You can set the router default behavior in the app.json at the routing node

 "routing":{
      "options":{
           "history": true,
           "bookmark": true,
           "jail": true,
           "cache" : false,
           "eval": some_global_function,
           "idle": false
       },
       "errors":{
            "404":"/errorstage/404",
            "403":"/errorstage/403"
       }
       ...
  }

History

If you want to use the history mode (back button) with your app, set it to true

  "history": true

Bookmark

If you want your app to be bookmark-able, set the bookmark property to true. Otherwise every user will be redirected to the home page at every session

  "bookmark": true

Jail

In jail mode, the user is prevented from opening an internal link in a new tab/window

 "jail": true

Links

Using standard a links

 <a href="/mystage/myroute" title="view my route">My Route</a>

is the equivalent to

 app.goto('mystage/myroute');

Note that all internal links must be written as /stage/route. In case jail is false, the URL will be rewritten and a new instance of the app will open in a new tab/window. Also, the router will trigger OGX.Router.GOTO upon navigation to the target of the link while passing back the url.

inline link options 1.23.0+

You can also set certain options from the element

<a href="/mystage/myroute" title="view my route" data-reload="true" data-history="false">My Route</a>

Cache 1.25.0+

When navigating from one route to the other, the default behavior is to destroy the top most Uxi in the stage's placeholder element. If you wish to re-use the render of a route (url), you can cache it and set an expiration length in seconds (in how long the cache will expire). The cache must be turned on in the router's option

 "options":{"cache":true, ...}

In the example bellow, 2 routes (or urls) are cached. First the one for 100s and the second one for 300s.

 "mystage/myrouteA" : {
      "cache" : 100,
      "oml" : { ... }
 },
 "mystage/myrouteB" : {
      "cache" : 300,
      "oml" : { ... }
 }

Note that if you set the expiration to 0, the cache never expires. To clear the cache for a given URL, do

 app.router.expire(URL);

You can also set to cache the route only once

 "mystage/myrouteA" : {
      "cache" : "once",
      "oml" : { ... }
 }

Live Controls

Starting at version 1.43.0, you can change the caching of the current route

 app.router.cacheOnce();
 app.router.cache(_VALUE_);

You can also disable the cache given a URL

 app.router.uncache(_URL_);

Eval 1.14.0+

If case you cannot rely on scope due to some additional permissions verification, you can set a function available globally to evaluate a route before it is travelled to. The function or method must return true or false

 "options":{
       "eval" : "MyFunction"
 }

 function MyFunction(__route_obj){
      //evaluate if the user can go there, return true or false
      return true;
 }

Gate 1.25.0+

Gate is a mechanism to prevent exiting the current route, based on the returned value of a function. If gate is set to true in the router's options, then at anytime you can call from your app

 "options":{
      "gate" : true
 }

 app.router.gate(myFunction);

Upon exiting the current route, the function myFunction will be called and if it returns true, the navigation will proceed as expected, otherwise it will be prevented.

 function myFunction(__url, __options){
      //do something and return true or false
      return true;
 }

The difference with eval is that eval is not passed any parameter and is not permanent. Once the gate has been passed, it is removed.

Idle

Idle is the maximum time in seconds spent in "tab blur" (when the browser's tab blurs), for a route. After which, the route will be automatically reloaded, ignoring and discarding the cached version. This basically ignores the cached version of a URL, if the browser's tab has lost focus for more than X seconds.

In router, in app.json

 "options":{
      "idle" : true
 }

In route, in app.json

 "mystage/myview":{
      "idle" : 30
 }

Reload 1.26.1+

Reload is a short to getting the request and then navigating to the same url again.

 app.router.reload();

Gather 1.27.0+

Gather returns an array of allowed urls given the current scope.

 const urls = app.router.gather();

You can also filter on top, by passing either a String or a RegExp.

 const urls = app.router.gather(/^public/);

isCached 1.39.0+

Find if the current route has been cached

const bool = app.router.isCached();

Popstate 1.42.0+

You can also manage the popstate event by adding a callback

 app.router.onpopstate = (__url) => {
       //if you want to deal with capture that event, return true
       if(__url.indexOf('...') !== -1){
            return true;
       }
       return false;
 };

Returning true would mean that you handle at this moment the user going back in the history with the back button, and not the router, besides settings up the previous URL. That also means that the rendering of that URL is handled by the onpopstate callback and the router does not render an actual route, if that callback returns true.

Route Availability 1.42.0+

By default, all routes are enabled. You can change that by specifying the "enabled" property in app.json per route, or you can disable/enable them later in your code

 app.router.disable('mystage/myroute');
 app.router.enable('mystage/myroute');

If a route is disabled, the end user will be from accessing the route.

Events

If no 404 or 403 error redirections are set in the router options, the router will fallback on triggering events

 OGX.Router.FORBIDDEN //404
 OGX.Router.NOT_FOUND //403
 OGX.Router.GOTO //when an internal link is encountered
 OGX.Router.BACK //when user hits the back button