Constructor
new Router()
- Source:
- See:
Requires
- module:ojs/ojcore
- module:knockout
Classes
Fields
-
<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.- Source:
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. If not specified, it is the current URL without the document. For example http://www.example.com/myApp
. This is needed to properly parse the URL.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
.Examples
Change the default URL adapter to the urlParamAdapter
oj.Router.defaults['urlAdapter'] = new oj.Router.urlParamAdapter();
Change the default base URL
oj.Router.defaults['baseUrl'] = 'http://www.example.com/myApp';
Change the default root router name to 'id'
oj.Router.defaults['rootInstanceName'] = 'id';
-
<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' } });
-
<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(); });
-
<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 forrouter.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:
-
<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 provide the following functionality to the ojModule binding:- it defines the name of the module by setting the
name
option to the value of the current router state. - it makes the parent router accessible to the module using the
params['ojRouter']['parentRouter']
property. - it defines a direction hint that can be use for the module animation.
- it makes the callback
canExit
invokable on the viewModel. IfcanExit
is not defined on the viewModel, it will be invoked on the RouterState
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 thevalue
is not defined or if it is not a string, the id property is used.params
: an object with a property namedojRouter
which value is a object with two propertiesparentRouter
which value is the parent router anddirection
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 theojRouter.parentRouter
property ofparams
.lifecycleListener
: an object implementing the attached callback to bind canExit to the router if it is defined on the viewModel.
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; });
- it defines the name of the module by setting the
-
<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:
-
<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 forojButtonset
or selection forojNavigationList
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:
Methods
-
<static> sync() → {Promise.<{hasChanged: boolean}>}
-
Synchronise the router with the current URL. The process parse the URL and
- transition the router to a new state matching the URL.
- initialize the bookmarkable storage.
- dispatch a transitionedToState signal.
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 propertyhasChanged
.
The value ofhasChanged
is:- true: If the router state changed.
- 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 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. 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. canEnter
function(): boolean) | (function(): Promise <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 <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) → {oj.Router}
-
Create a child router for the current router state with the given name.
Parameters:
Name Type Description name
string The unique name representing 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
Example
Create a child router of the root:
router = oj.Router.rootInstance; childRouter = router.createChildRouter('chapter');
-
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) → {Promise.<{hasChanged: boolean}>}
-
Go is used to transition to a new state. In version 1.1 the argument was a state id. In this release the syntax has been extended to accept a path 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' (1.1 syntax)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, go 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. - 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 propertyhasChanged
.
The value ofhasChanged
is:- true: If the router state changed.
- 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); } );
-
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); }