Router

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" : { ... }
 },

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

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.

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/);