Routes

OGX.JS provides a routing system that is also linked to the browser history. In OGX.JS, a route defines a set of OML nodes to be instanced into a stage.

Routes have similarities with back-end routes using Mod Rewrite, that you might be familiar with if you use Apache or IIS. They use regular expression to direct the request to the proper node.

Format

The format for a route is the following

 {"mystage/myroute":{
    "cache": false, 
    "idle": false,
    "origin": null,
    "oml":[OML Node]
 }}

Static Route

Let's write a very simple route without worrying about the OML part for now

 {"stage1/home":{"oml":[OML Node]}}

This route will redirect the end user to the home node of the application. You can of course have depth in your url, such as

 {"stage1/home/promo":{"oml":[OML Node]}}

Dynamic Route

You can also generate data from a route, using a dynamic route and and OML node. If the following example, the possible elements of node receive "id":[capture id]

 {"stage1/users/(id:[0-9]+)/profile":{
       "oml": {
            ...,
            "data:OSE":"{{%id}}"
        }
  }}

For instance, to load a json document based on the id based on the crumb

  "data:OSE":"{{json %id}}"

Important thing to remember here. If you choose the name your property data for the captured data, then any templating done over the view will use that data object.

 {"stage1/users/(id:[0-9]+)/profile":{
      "oml":{
           "#somediv:Views.MyView":{
                 "data:OSE":"{{json %id}}"
            }
      }
 }

You can also link to a global variable, in our case users

 {"stage1/users/(id:[0-9]+)/profile":{
      "oml": {
           "#somediv:Views.MyView":{
                 "data:OSE":"{{#users[%id]}}"
           }
      }
 }

And to pass as data the entire captured object, in our case {id:123}, set your value to "":

 {"stage1/users/(id:[0-9]+)/profile":{
      "oml": {
           "#somediv:Views.MyView":{
                 "data:OSE":"{{%}}"
            }
       }
 }

Query Strings 1.42.0+

If you prefer, you can use the standard query string method, which will be transformed as route data

 app.goto('mystage/myroute?title=mytitle&date=2024-01-01');

Matching the route

{"stage1/myroute":{
     ...
}

The object representing the query string is available via the % constant

{"stage1/myroute":{
     "oml" : {
         "default:Views.MyView":{
              "data:OSE" : "{{%}}"
         }
     }
}

URL Rewrite 1.42.0+

You can also rewrite URLs, and choose or not to append the query string

{"stage1/myroute":{
    "rewrite": {
         "url" : "stage1/mynewroute",
         "qsa" : true
    }
}};

Origin

You can request that a route can only be visited if the url of the current stage matches a certain origin.

 {"stage1/users":{
      ...,
      "origin": "self,stage1/intro",
 }}

self refers to the same route. You can allow multiple origins by separating them with a coma.

Navigation

Navigating is done by calling

 app.goto(url, {history:true}, {optional:'data'});

A practical example

 app.goto("stage1/users/123456/profile", {history:true}, {stuff:'some additional data'});

You can also push a url, which pushes to history without navigating to the given url, in case you manipulate the url from another object

app.router.add('stage1/users/123456');

Options

Available options are history and reload. If you don't pass any options, it defaults to

 {history:true, reload:false}

reload is only considered when the target url is the same as the current url. By default, the application will ignore going to the same route unless reload is set to true