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. 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 defined, it is the current URL without the document. For example http://www.example.com/myApp
. This is needed by the Router to properly parse the URL.Examples
Change the default URL adapter to the urlParamAdapter
oj.Router.defaults['urlAdapter'] = new oj.Router.urlParamAdapter();
Change the base URL
oj.Router.defaults['baseUrl'] = 'http://www.example.com/myApp';
-
<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 property of this router is 'root'. The parent property is null.- 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 the module name specified in the value of the current RouterState object.
The object moduleConfig provide the following functionality to the ojModule binding:- the name of ojModule binding will be the value property
of the current state of the router. If
value
is not defined or if it is not a string, the id property will be used - The router object is passed as a parameter to the viewModel of the module
- The callback
canExit
will be invoked on the viewModel. IfcanExit
is not defined on the viewModel, it will be invoked on the RouterState
- 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; // 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; } };
- the name of ojModule binding will be the value property
of the current state of the router. If
-
<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 that returns the id of the current state of the router.
- Source:
-
<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); $('#globalBody').show(); }, 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 - 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); }