Class: Router

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 1.1.0
Module:
  • ojrouter

Note: This class is deprecated since 9.0.0. Use alternative: CoreRouter.

QuickNav

Fields

Methods

Type Definitions

Description

JET Router

The router is designed to simplify writing navigation for Single Page Applications. The approach taken is to think of navigation in terms of states and transitions instead of URLs and hashes. A router is always in one in a number of possible states and when a UI action is taken in the application, a transition between states is executed. The router is responsible to properly format the URL to reflect the current state and to restore the application to the matching state when the URL changes.

Building navigation is done in three steps:

Define the states that can be taken by the router:

var router = oj.Router.rootInstance;
// Add three states to the router with id 'home', 'book' and 'tables
router.configure({
   'home':   { label: 'Home',   value: 'homeContent', isDefault: true },
   'book':   { label: 'Book',   value: 'bookContent' },
   'tables': { label: 'Tables', value: 'tablesContent' }
});

var viewModel = {
   router: router
};

oj.Router.sync().then(
   function() {
      ko.applyBindings(viewModel);
   },
   function(error) {
      Logger.error('Error when starting router: ' + error.message);
   });
Trigger a state transition when user ask to navigate:

<div id="routing-container">
   <div id='buttons-container'>
     <oj-bind-for-each data="[[router.states]]">
       <template>
         <!-- Use the go function of the state as the handler for a click binding -->
         <oj-button :id="[[$current.data.id]]" on-oj-action="[[go]]">
           <oj-bind-text value="[[$current.data.label]]"></oj-bind-text>
         </oj-button>
       </template>
     </oj-bind-for-each>
   </div>
</div>
Listen to the state change and updates the dependent parts:

<!-- Display the content of the current state -->
<h2 id="pageContent">
  <oj-bind-text value="[[router.currentValue]]"></oj-bind-text>
</h2>


Usage

Javascript Import Format
define(['ojs/ojrouter'], function(Router) {
 // Application should call API on Router 
})
Typescript Import Format
//This class is exported directly as module. To import it
import Router= require("ojs/ojrouter");

For additional information visit:


See:
A Router cannot be instantiated. A static Router is created when the module is loaded and can be accessed using the method rootInstance. A child router can be created using the method createChildRouter.
See:

Requires

  • module:ojs/ojcore

Classes

urlParamAdapter
urlPathAdapter

Fields

(readonly) currentState :function(): (oj.RouterState|undefined)

A Knockout observable on the current RouterState object.

(readonly) currentValue :function(): (string|undefined)

A Knockout observable on the value property of the current state.
The state value property is the part of the state object that will be used in the application. It is a shortcut for router.currentState().value;

defaultStateId :string|undefined

The state id of the default state for this router. The value is set when configure is called on the router and the state isDefault property is true. If it is undefined, the router will start without a state selected. This property is writable and can be used to set the default state id when the router is configured using a callback.

(static) defaults

A set of Router defaults properties.
Warning:
Defaults can not be changed after the first call to sync() has been made. To re-initialize the router, you need to call dispose() on the rootInstance first then change the defaults.
Properties:
Name Type Argument Description
baseUrl string <optional>
 the base URL to be used for relative URL addresses. The value can be absolute or relative. If not specified, the default value is '/'.
Warning: When using the path URL adapter it is necessary to set the base URL if your application is not using index.html or is not starting at the root folder. Using the base URL is the only way the router can retrieve the part of the URL representing the state.
rootInstanceName string <optional>
 the name used for the root router. If not defined, the name is 'root'. This is used by the urlParamAdapter to build the URL in the form of /index.html?root=book.
urlAdapter oj.Router.urlPathAdapter | oj.Router.urlParamAdapter <optional>
 an instance of the url adapter to use. If not specified, the router will be using the path url adapter. Possible values are an instance of oj.Router.urlPathAdapter or oj.Router.urlParamAdapter.

(readonly) direction :string|undefined

The current navigation direction of the router, used for module animations. The value will either be undefined if navigating forward, or "back" if navigating backwards. This is the same value available as part of moduleConfig.
Since:
  • 5.0.0

(readonly) moduleConfig :Object

An object to simplify integration between ojRouter and ojModule. Use this object to configure an ojModule where the module name is the router state. When the router changes state, ojModule will automatically load and render the content of a new module based on the name specified in the value or id property of the current RouterState.
The object moduleConfig provides the following functionality to the ojModule binding:
  1. it defines the name of the module by setting the name option to the value of the current router state.
  2. it makes the parent router accessible to the module using the params['ojRouter']['parentRouter'] property.
  3. it defines a direction hint that can be use for the module animation.
  4. it makes the callback canExit invokable on the viewModel. If canExit is not defined on the viewModel, it will be invoked on the RouterState.
The moduleConfig object has the following properties:
  • name: is set to the value property of the current state of the router. If a current state is not defined, the default state is used and if the default state is not defined, the first state is used. On the state object, if the value is not defined or if it is not a string, the id property is used.
  • params: an object with a property named ojRouter which value is a object with two properties parentRouter which value is the parent router and direction which value is undefined or the string 'back'. In JET version 1.1, the parent router was the entire params object making it impossible to pass any other parameters. Application built using version 1.1 of JET now need to retrieve the parent router from the ojRouter.parentRouter property of params.
  • lifecycleListener: an object implementing the attached callback to bind canExit to the router if it is defined on the viewModel. If you override attached, this functionality will be lost unless you set the viewModel to the current state of the parent router in your custom attached implementation.
The router calculate the direction of the navigation and make it available to the child module using the parameter ojRouter.direction.
This can be used to specify a different module animation when going 'back'. The value of direction is either undefined or 'back'. It is 'back' when the state transition is caused by a back button on the browser and the new state is equal to the previous state. To customize the behavior of the moduleduleConfig object, it is possible to create your own moduleConfig and merge other properties or modifies the value of existing properties.
Properties:
Name Type Description
lifecycleListener Object
Properties
Name Type
attached function(any):void
name ko.Observable.<string>
params Object
Properties
Name Type Description
ojRouter Object
Properties
Name Type
direction string
parentRouter oj.Router

(readonly, non-null) name :string

A string identifier of the router. It is required the name is unique within all the sibling routers.
See:

(readonly) observableModuleConfig :ko.Observable.<oj.Router.ModuleConfigType>

Similar to oj.Router#moduleConfig, this object is meant to be used to configure a module binding which reacts to changes in the router state or its parameters. This configuration also creates observables around all of the oj.RouterState#parameters found in the router state.

This observable is dyanmically created only when it's first requested. To use observableModuleConfig and its observable parameters, first reference the property in your own code, which will setup the observable and add observable state parameters. To use the observable parameters, retrieve the instance from the parameters passed to your view model.

Since:
  • 4.2.0

(readonly) parent :oj.Router|undefined

The parent router if it exits. Only the 'root' router does not have a parent router.

(static, readonly) rootInstance :oj.Router

The static instance of oj.Router representing the unique root router. This instance is created at the time the module is loaded.
All other routers will be children of this object.
The name of this router is 'root'. To change this name use the rootInstanceName property.

(readonly) stateId :function(string=): string

A Knockout observable for the id of the current state.
stateId() returns the string id.
stateId('book') transitions the router to the state with id 'book'.
It is convenient to use the stateId observable when working with component with 2-way binding like value for ojButtonset or selection for ojNavigationList because it does not require a click on optionChange handler (See example below).

(readonly) states :Array.<oj.RouterState>|null

An array of all the possible states of the router. This array is null if the router is configured using a callback.
See:

(static, readonly) transitionedToState :signals.Signal

A signal dispatched when the state transition has completed either by successfully changing the state or cancelling.
The parameter of the event handler is a boolean true when the state has changed.
This is usefull when some post processing is needed or to test the result after a state change.

Methods

(static) sync : (non-null) {Promise.<{hasChanged: boolean}>}

Synchronise the router with the current URL. The process parse the URL and
  1. transition the router to a new state matching the URL.
  2. initialize the bookmarkable storage.
  3. dispatch a transitionedToState signal.
It has to be called after a router is configured, to synchronise the URL with the router state.
If a default state is defined, the router will transition to it, otherwise no transition will occur and the router will be in an undefined state.
Because the process of transitioning between two states invokes callbacks (canExit, canEnter) that are promises, this function also returns a promise.
Returns:

A Promise that resolves when the router is done with the state transition.
When the Promise is fullfilled, the parameter value is an object with the property hasChanged.
The value of hasChanged is:

  • true: If the router state changed.
When the Promise is rejected, the parameter value is:
  • An Error object stipulating the reason for the rejection when an error occurred during the resolution.

Type
Promise.<{hasChanged: boolean}>

configure(option) : {Router}

Configure the states of the router. The router can be configured in two ways:
  • By describing all of the possible states that can be taken by this router.
  • By providing a callback returning a RouterState object given a string state id.
This operation resets any previous configuration, and is chainable.
Configuring router state parameters should be done here. See the example below.
Parameters:
Name Type Argument Description
option {[key:string]: RouterState.ConfigOptions} | ((id:string)=> RouterState | oj.RouterState.ConfigOptions | undefined | null) <not nullable>
 Either a callback or a dictionary of states.
A callback:

stateFromIdCallback (stateId) → {oj.RouterState|undefined}

A function returning a RouterState given a string state id.
When using a callback, the states property will always be null since states are defined on the fly.
See second example below.
A dictionary of states:
It is a dictionary in which the keys are state ids and values are objects defining the state. Note that the forward slash character '/' is not allowed in the state Id. See ConfigOptions.
See first example below.
Key
Type Description
string the state id. See the RouterState id property.
oj.RouterState.ConfigOptions See ConfigOptions for the options available for configuring router states
See:
Returns:
Type
Router

createChildRouter(name, parentStateId) : {oj.Router}

Create a child router with the given name. A router can either have one child router that handles all possible states, or one child router per state. See the examples below.
Parameters:
Name Type Argument Description
name string <not nullable>
 The unique name representing the router. The name is used by the function getChildRouter to retrieve the child router.
parentStateId string <optional>
 The state Id of the parent router for determining when this child router is used. If not defined, the child router is created for the current state of the router.
Throws:
An error if a child router exist with the same name or if the current state already has a child router.
Returns:

the child router

Type
oj.Router

dispose : {undefined}

Dispose the router.
Erase all states of this router and its children. Remove itself from parent router child list.
When this method is invoked on the rootInstance, it also remove internal event listeners and re-initialize the defaults.
Returns:
Type
undefined

getChildRouter(name) : {oj.Router|undefined}

Return a child router by name. The name is the value given to createChildRouter.
Parameters:
Name Type Argument Description
name string <not nullable>
 The name of of the child router to find
Since:
  • 1.2.0
Returns:

The child router

Type
oj.Router | undefined

getCurrentChildRouter : {oj.Router|undefined}

Get the child router associated with the parent's current state. See createChildRouter for details on how child routers are associated with parent states.
Since:
  • 5.0.0
Returns:

The child router for the current state, if defined.

Type
oj.Router | undefined

getState(stateId) : {oj.RouterState|undefined}

Return the oj.RouterState object which state id matches one of the possible states of the router.
Parameters:
Name Type Description
stateId string the id of the requested oj.RouterState object.
Returns:

the state object matching the id.

Type
oj.RouterState | undefined

go(stateIdPath, options) : (non-null) {Promise.<{hasChanged: boolean}>}

Go is used to transition to a new state using a path made of state ids separated by a slash. The path can be absolute or relative.

Example of valid path:
  • router.go('home'): transition router to state id 'home'
  • router.go('/book/chapt2'): transition the root instance to state id 'book' and the child router to state id 'chapt2'
  • router.go('chapt2/edit'): transition router to state id 'chapt2' and child router to state id 'edit'
  • router.go(['chapt2','edit']): equivalent to the previous transition, but using an array of path strings in place of forward slashes.

If the stateIdPath argument is undefined or an empty string, go transition to the default state of the router.
A transitionedToState signal is dispatched when the state transition has completed.
Parameters:
Name Type Argument Description
stateIdPath string | Array.<string> <optional>
 A path of ids representing the state to which to transition, separated by forward slashes (/). This can also be an Array of strings, each segment representing individual states. An array is typically used if the forward slash should be part of the state Id and needs to be distinguished from the path separators.
options Object <optional>
 an object with additional information on how to execute the transition.
Properties
Name Type Description
historyUpdate string Specify how the transition should act on the browser history. If this property is not specified, a new URL is added to the history.
Supported Values:
'skip': does not update the history with the new URL
'replace': modifies the current history with the new URL
Returns:

A Promise that resolves when the router is done with the state transition.
When the promise is fullfilled, the parameter value is an object with the property hasChanged.
The value of hasChanged is:

  • true: If the router state changed.
When the Promise is rejected, the parameter value is:
  • An Error object stipulating the reason for the rejection during the resolution. Possible errors are:
    • If stateIdPath is defined but is not of type string.
    • If stateIdPath is undefined but the router has no default state.
    • If a state id part of the path cannot be found in a router.

Type
Promise.<{hasChanged: boolean}>

retrieve : {{[key:string]:any}}

Retrieve the additional data stored in the URL.
Returns:

the content stored in the URL

Type
{[key:string]:any}

store(data) : {undefined}

Store additional data for this router that will be added in a compressed form to the URL so it can be bookmarked. When calling this method, the URL is immediately modified.
Parameters:
Name Type Argument Description
data {[key:string]:any} <not nullable>
 the data to store with this state.
Throws:
An error if the bookmarkable state is too big.
Returns:
Type
undefined

Type Definitions

ModuleConfigType

Properties:
Name Type Description
lifecycleListener Object
Properties
Name Type Description
attached function(any):void The 'attached' listener for the module
name ko.Observable.<string> The value of the current state. See oj.Router#currentValue
params Object
Properties
Name Type Description
ojRouter Object
Properties
Name Type Description
direction string The animation direction of the module, if defined.
parameters {[key:string]:any} An object containing the observable parameters of the current router state.
parentRouter oj.Router A reference to the current router