Oracle JET Routing

Single page applications require routing and navigation in a different way than the traditional web applications. The SPA applications will update URL to reflect the application state at a given time and update the browser history. In Oracle JET we have the mechanism to do the routing through oj.Router but it gets a bit complicated when you have many more parameter to store in the URL. At the end of this blog I offer a simple solution that can be used by any page that requires storing state in URL.

Overview

1. Routing overview in Oracle JET
2. Generic routing utility class

Routing overview in Oracle JET

In the Oracle JET cookbook you can find some really nice example on how oj.Router is working, you can have a look here: https://www.oracle.com/webfolder/technetwork/jet/jetCookbook.html?component=router&demo=simple 

A typical Oracle JET application will have a main navigation and routing system. This helps the user navigating through the application pages or modules as they are called in OJET. Each module that requires to store the state in URL will have to implement child routers. For child routers you can have a look at this cookbook example: https://www.oracle.com/webfolder/technetwork/jet/jetCookbook.html?component=router&demo=child

There are some particularities and challenges attached to child routers, which have unknown list of states (e.g. date intervals, employee ID, etc.):

• You need to create them for each parameter you want to store in URL, using Router.rootInstance. createChildRouter.
• Each router can have only one child router, so this must be chained. This applies also to the root instance.

The oj.Router class has a function transitionedToState which you can subscribe to. This event handles the transition state, as we don’t know all the states for the router, we need to catch any new state and add it to the router. This event can be used also to identify value change for an URL parameter, so here we will store the new value of the parameter in an observable. The observable variable will automatic refresh the page because of the binding mechanism.

Generic Routing utility class

In order to have a cleaner code we developed an utility class for handling all these particularities of routers with unknown states.

The source code for this utility class can be found in this GitHub repository: https://github.com/ciancu/oj-routing-utility/blob/master/src/js/libs/RoutingUtils.js

The code bellow shoes how would you configure such a routing mechanism in your module. First, you must create an array of objects, each has a name, type and the associated observable with it.

self.routers = [
{
    name: "inputNumber",
    type: "int",
    observable: self.inputNumber
}, {
    name: "isoDate",
    type: "string",
    observable: self.isoDate
}
];

The routing can be initialized by the following code, this will create all child routers and chain them. The function must be called in the loading event for the module, e.g. transitionCompleted.

self.transitionCompleted = function() {
    return self.RoutingUtils.initRouters(self.routers).then();
};

Handling missing states event is handled by the utility class without any change in your module.

At the moent when your applicatio requires to navigate, to a new module state, you must call the following function. There you must provide the values for the routers in te same order as they were defined.

let _inputNumberAsString = '' + self.inputNumber();
self.RoutingUtils.go([_inputNumberAsString, self.isoDate()]);

Observation: In the above sample the employee has been casted to a string, this is very important for routers in OJET, it will not work with integers.

Here is a video that shows the routing behaviour:

Summary

Oracle JET offers a wide variety of components and mechanisms to help developers develop Single Page Applications. Routing is an important aspect for such applications, as such we wanted to provide with this utility class an even better approach for unknown states routers in Oracle JET.