Class: Router

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

Fields

oj. Router

Version:
  • 3.2.0
Since:
  • 1.1.0

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) {
      oj.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' data-bind="foreach: router.states">
     <!-- Use the go function of the state as the handler for a click binding -->
     <input type="button"
            data-bind="click: go,  attr: {id: id},
            ojComponent: {component: 'ojButton', label: label}"/>
   </div>
</div>
Listen to the state change and updates the dependent parts:

<!-- Display the content of the current state -->
<h2 id="pageContent" data-bind="text: router.currentValue"/>

Constructor

new Router()

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.
Source:
See:

Requires

  • module:ojs/ojcore
  • module:knockout

Classes

urlParamAdapter
urlPathAdapter

Fields

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

A Knockout observable on the current RouterState object.
Source:
Example

Hide a panel when the state of the router is not yet defined:

   <div data-bind="if: router.currentState()">
      <!-- content of the panel -->
   </div>

<readonly> currentValue :function()

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;
Source:
Example

Display the content of the current state:

<h2 id="pageContent" data-bind="text: router.currentValue"/>

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.
Source:

<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 Description
urlAdapter Object 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.
baseUrl string 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 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.
Source:
Examples

Change the default URL adapter to the urlParamAdapter

oj.Router.defaults['urlAdapter'] = new oj.Router.urlParamAdapter();

Set the base URL for an application located at the root and a starting page named index.html. This is the default.

oj.Router.defaults['baseUrl'] = '/';

Set the base URL for an application with a page named main.html and located in the /myApp folder.

oj.Router.defaults['baseUrl'] = '/myApp/main.html';

Change the default root router name to 'id'

oj.Router.defaults['rootInstanceName'] = 'id';

<readonly> moduleConfig

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. It is recommended to use $.extend as described in the third example below.
Source:
Examples

Configure an ojModule binding with a router

<!-- This is where your main page content will be loaded -->
<div id="mainContainer" data-bind="ojModule: router.moduleConfig"></div>

Creates a child router in the viewModel of a module

var viewModel = {
   initialize: function(params) {
      // Retrieve the parent router from the parameters
      var parentRouter = params.valueAccessor().params['ojRouter']['parentRouter'];
      // Create a child router for this viewModel
      this.router = parentRouter.createChildRouter('chapter')
         .configure({
            'preface':  { label: 'Preface',   value: storage['preface']  },
            'chapter1': { label: 'Chapter 1', value: storage['chapter1'] },
            'chapter2': { label: 'Chapter 2', value: storage['chapter2'] },
            'chapter3': { label: 'Chapter 3', value: storage['chapter3'] }
         });
      oj.Router.sync();
   },

   // canExit callback will be called here
   canExit: function() {
      return (okToExit) ? true: false;
   }
};

Creates a custom moduleConfig replacing the name property

dynamicConfig = ko.pureComputed(function () {
   if (smallOnly()) {
      // Add the prefix 'phone/' to change the viewModel location
      return $.extend({},
                      router.moduleConfig,
                      {name: 'phone/' + router.moduleConfig.name()});
   }
   return router.moduleConfig;
});

<readonly> name :string

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

<readonly> parent :oj.Router|undefined

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

<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.
Source:
Example

Retrieve the root router and configure it:

var router = oj.Router.rootInstance;
router.configure({
   'home':   { label: 'Home',   value: 'homeContent', isDefault: true },
   'book':   { label: 'Book',   value: 'bookContent' },
   'tables': { label: 'Tables', value: 'tablesContent' }
});

<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 checked for ojButtonset or selection for ojNavigationList because it does not require a click on optionChange handler (See example below).
Source:
Example

A buttonSet using the router stateId for 2-way binding:

<div data-bind="ojComponent: { component: 'ojButtonset',
                               checked: router.stateId,
                               focusManagement:'none' }">
   <!-- ko foreach: router.states -->
      <label data-bind="attr: {for: id}"></label>
      <input type="radio" name="chapter"
             data-bind="value: id, attr: {id: id},
                        ojComponent: { component: 'ojButton',
                                       label: label}"/>
   <!-- /ko -->
</div>

<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.
Source:
See:

<static, readonly> transitionedToState

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.
Source:
Example

Creates promise that resolve when the state transition is complete.

var promise = new Promise(function(resolve, reject) {
      oj.Router.transitionedToState.add(function(result) {
         if (result.hasChanged) {
            oj.Logger.info('The state has changed');
         }
         resolve();
      });

Methods

<static> sync() → {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.
Source:
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}>
Examples

Start the root instance

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) {
      oj.Logger.error('Error when starting the router: ' + error.message);
   }
);

Synchronise a newly created child Router and retrieve the bookmarkable state

 oj.Router.sync().then(
    function() {
       var color = viewModel.router.retrieve();
       if (color) {
          $('#chapter').css('background', color);
       }
    },
    function(error) {
       oj.Logger.error('Error during sync: ' + error.message);
    }
 );

configure(option) → {oj.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 reset any previous configuration.
This operation is chainable.
Parameters:
Name Type Description
option !(Object.<string, {label: string, value, isDefault: boolean}> | function(string): (oj.RouterState | undefined)) 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.
See first example below.
Key
Type Description
string the state id. See the RouterState id property.
Properties
Name Type Argument Description
label string <optional>
the string for the link. This is also used to compose the title of the page when no title property is defined. See the oj.RouterState#label property.
value * <optional>
the object associated with this state. See the oj.RouterState#value property.
isDefault boolean <optional>
true if this state is the default. See the Router defaultStateId property.
title string | function():string <optional>
the string to be used for the title of the page. See the oj.RouterState#title property.
canEnter function(): boolean | function(): Promise.<boolean> <optional>
A callback that either returns a boolean or the Promise of a boolean. If the boolean is true the transition will continue. The default value is a method that always returns true. See the oj.RouterState#canEnter property.
enter function() | function(): Promise <optional>
A callback or the promise of a callback which execute when entering this state. See the oj.RouterState#enter property.
canExit function(): boolean | function(): Promise.<boolean> <optional>
A callback that either returns a boolean or the Promise of a boolean. If the boolean is true the transition will continue. The default value is a method that always returns true. See the oj.RouterState#canExit property.
exit function() | function(): Promise <optional>
A callback or the promise of a callback which execute when exiting this state. See the oj.RouterState#exit property.
Source:
See:
Returns:
the oj.Router object this method was called on.
Type
oj.Router
Examples

Add three states 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' }
});

Define a function to retrieve the state:

router.configure(function(stateId) {
   var state;

   if (stateId) {
      state = new oj.RouterState(stateId, { value: data[stateId] }, router);
   }
   return state;
});

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

Create a child router with the given name. A router can either have one child router that handle all possible states or one child router per state. In the first scenario, the child router is not attached to a specific state of the parent and needs to be configured dynamically. In the second scenario, a child router is attached to a specific state of the parent. If the id of the parent state is not specified using the parentState argument, the child router is attached to the current state of the router.
Parameters:
Name Type Argument Description
name string The unique name representing the router.
parentStateId string <optional>
The id of the state of the parent router for this child router. If not defined, the child router is created for the current state of the router.
Source:
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
Examples

Create a child router of the root:

router = oj.Router.rootInstance;
childRouter = router.createChildRouter('chapter');

Create a child router for parent state id 'book':

router = oj.Router.rootInstance;
childRouter = router.createChildRouter('chapter', 'book');

dispose()

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.
Source:

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

Return a child router by name.
Parameters:
Name Type Description
name string The name of of the child router to find
Since:
  • 1.2.0
Source:
Returns:
The child router
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.
Source:
Returns:
the state object matching the id.
Type
oj.RouterState | undefined
Example

Retrieve the RouterState for id 'home':

var homeState = router.getState('home');
var homeStateValue = homeState.value;

go(stateIdPath, options) → {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'

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 <optional>
A path of ids representing the state to transition to.
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
Source:
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}>
Examples

Transition a router to the state id 'home':

router.go('home');

Transition a router to its default state and handle errors:

router.go().then(
   function(result) {
      if (result.hasChanged) {
         oj.Logger.info('Router transitioned to default state.');
      }
      else {
         oj.Logger.info('No transition, Router was already in default state.');
      }
   },
   function(error) {
      oj.Logger.error('Transition to default state failed: ' + error.message);
   }
);

Transition a router to state id 'stepB' without updating the URL:

wizardRouter.go('stepB', { historyUpdate: 'skip' });

retrieve() → {*}

Retrieve the additional data stored in the URL.
Source:
Returns:
the content stored in the URL
Type
*
Example

Retrieve the value of the background color stored in the URL:

 oj.Router.sync().then(
    function() {
       var color = viewModel.router.retrieve();
       if (color) {
          $('#chapter').css('background', color);
       }
    },
    function(error) {
       oj.Logger.error('Error during sync: ' + error.message);
    }
 );

store(data)

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 Description
data Object the data to store with this state.
Source:
Throws:
An error if the bookmarkable state is too big.
Example

Store a color in the URL:

try {
   var color = '#99CCFF';
   router.store(color);
   $('#chapter').css('background', color);
}
catch (error) {
   oj.Logger.error('Error while storing data: ' + error.message);
}