Class: RouterState

Oracle® JavaScript Extension Toolkit (JET)
5.0.0

E90577-01

QuickNav

Fields

RouterState

Version:
  • 5.0.0
Since:
  • 1.1.0
Module:
  • ojrouter
Object representing a state of the router.

Constructor

new RouterState(id, options, router)

It is the type of the currentState property and type of the value returned by getState(String).
Parameters:
Name Type Argument Description
id string <not nullable>
the state id. See the oj.RouterState#id property.
options oj.RouterState.ConfigOptions <optional>
<not nullable>
an object defining the state.
router oj.Router <optional>
The router this state belongs to. If undefined, the method go and isCurrent will not work.

Fields

canEnter :(function(): boolean|function(): Promise.<boolean>)

A callback that either returns a boolean or the Promise of a boolean. When defined, this callback is executed before entering this state. If the boolean is true the transition will continue, otherwise the state is not entered and the current state of the router does not change.
This allows the application to veto the transition into the state if there are known conditions that must be met before the state should be entered into.
If the operation (to check if the state can be entered) is synchronous, return a boolean directly; if asynchronous, a Promise of a boolean should be returned. The state transition will not occur until either the boolean returned is true, or the Promise is resolved and returns true.
The default value is a method that always returns true.

canExit :(function(): boolean|function(): Promise.<boolean>)

A callback that either returns a boolean or the Promise of a boolean. When defined, this callback is executed before exiting this state. If the boolean is true the transition will continue, otherwise the state is not exited and the current state of the router does not change.
This is typically used by states which need to verify user input is correct before moving on. Synchronous checks can return a boolean directly, and asynchronous checks can return a Promise of a boolean. The state transition will not occur until either the boolean returned is true, or the Promise returned is resolved and returns true.
The default value is a method that always returns true.

enter :(function(): void|function(): Promise.<void>)

A callback or the promise of a callback which executes when entering this state. This callback executes after the router stateId changes.

exit :(function(): void|function(): Promise.<void>)

A callback or the promise of a callback which execute when exiting this state. This callback executes before the router stateId changes.

(readonly, non-null) id :string

The id of this state.
It uniquely identify a state object in a router. The id property can be used as the attribute id of a navigation component like link or button.
Example

Use the state id property for the attribute id of anchor tags in a list:

<ul id="foreachMenu" data-bind="foreach: router.states">
  <li>
    <a data-bind="text: label, css: {'active': isCurrent()},
                  attr: {id: id}, click: go"> </a>
  </li>
</ul>

label :string|undefined

The string to be used for the navigation component that will transition to this state. This is also used to build the title of the page when the oj.RouterState#title property is not defined. The title will be composed of the labels of all current states in the router hierarchy like "My Page | label lvl1 | label lvl2".
Example

Use the label property for the text of anchor tags in a list:

<ul id="foreachMenu" data-bind="foreach: router.states">
  <li>
    <a data-bind="text: label, css: {'active': isCurrent()},
                  attr: {id: id}, click: go"> </a>
  </li>
</ul>

parameters :Object

PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

The newly-activated state is passed the 'parameters' Object alongside the oj.Router#instance property to the View Model of the state (if oj.Router#moduleConfig is used). To reference the values, use the key name by which the router states were configured.
Since:
  • 4.2.0
Examples

Configure router with a parameterized state

oj.Router.rootInstance.configure({
   'list': { label: 'List' },
   'detail/{empId}/{edit}'
});

Parameter values are passed in the URL, and are position- dependent.

/app/detail/e100/true

Retrieve parameter values from router

function ViewModel(config) {
   var router = config['ojRouter']['instance'];
   var params = config['ojRouter']['parameters'];
   var empId = params['empId'];
   var edit = params['edit'];
}

title :(string|function(): (string|undefined))

The string to be used for the page title. This can either be a string or a function returning a string. When more than one level of child router is defined, the title of the current state of the router nested the deepest has precedence. If the leaf router current state does not have a title property defined, the title of the current state of the parent router is used. If no title property is defined in the router hierarchy, a title is built using the oj.RouterState#label property.

value :*

The value associated with this state. When this state is the current state of the router, it is the value returned by the observable oj.Router#currentValue.

Methods

go() → (non-null) {Promise.<{hasChanged: boolean}>}

Transition the router to this state. This is a convenience method used as the event handler for a Knockout click binding on a button or a tag.
A transitionedToState signal is dispatched when the state transition has completed.
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}>
Example

Use the go function as the handler for a click binding:

<ul id="foreachMenu" data-bind="foreach: router.states">
  <li>
    <a data-bind="text: label, css: {'active': isCurrent()},
                  attr: {id: id}, click: go"> </a>
  </li>
</ul>

isCurrent() → {boolean}

Determine if the router current state is this state. This method is typically used by elements in the markup to show the appropriate selection value.
Throws:
An error if an owning router was not specified when the state was created.
Returns:
true if this state is the current router state.
Type
boolean
Example

Use the is function to change the css of the state links:

<ul id="foreachMenu" data-bind="foreach: router.states">
  <li>
    <a data-bind="text: label, css: {'active': isCurrent()},
                  attr: {id: id}, click: go"> </a>
  </li>
</ul>

Type Definitions

ConfigOptions

Properties:
Name Type Argument Description
label string <optional>
the string to be displayed in the command component. 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 defaultStateId 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():void | function(): Promise.<void> <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():void | function(): Promise.<void> <optional>
A callback or the promise of a callback which execute when exiting this state. See the oj.RouterState#canExit property.