Skip to main content

Class: ClientRouter

@ima/core.ClientRouter

The client-side implementation of the Router interface.

Hierarchy

Constructors

constructor

new ClientRouter(pageManager, factory, dispatcher, window, middlewareTimeout)

Initializes the client-side router.

Parameters

NameTypeDescription
pageManagerPageManagerThe page manager handling UI rendering, and transitions between pages if at the client side.
factoryRouteFactoryFactory for routes.
dispatcherDispatcherDispatcher fires events to app.
windowWindowThe current global client-side APIs provider.
middlewareTimeoutundefined | numberMiddleware timeout value in ms.

Overrides

AbstractRouter.constructor

Defined in

packages/core/src/router/ClientRouter.ts:78

Properties

_currentMiddlewareId

Protected _currentMiddlewareId: number = 0

Middleware ID counter which is used to auto-generate unique middleware names when adding them to routeHandlers map.

Inherited from

AbstractRouter._currentMiddlewareId

Defined in

packages/core/src/router/AbstractRouter.ts:91


_currentlyRoutedPath

Protected _currentlyRoutedPath: string = ''

Inherited from

AbstractRouter._currentlyRoutedPath

Defined in

packages/core/src/router/AbstractRouter.ts:92


_dispatcher

Protected _dispatcher: Dispatcher

Dispatcher fires events to app.

Inherited from

AbstractRouter._dispatcher

Defined in

packages/core/src/router/AbstractRouter.ts:61


_factory

Protected _factory: RouteFactory

Factory for routes.

Inherited from

AbstractRouter._factory

Defined in

packages/core/src/router/AbstractRouter.ts:57


_host

Protected _host: string = ''

The application's host.

Inherited from

AbstractRouter._host

Defined in

packages/core/src/router/AbstractRouter.ts:70


_languagePartPath

Protected _languagePartPath: string = ''

The URL path fragment used as a suffix to the _root field that specifies the current language.

Inherited from

AbstractRouter._languagePartPath

Defined in

packages/core/src/router/AbstractRouter.ts:79


_middlewareTimeout

Protected _middlewareTimeout: number

Inherited from

AbstractRouter._middlewareTimeout

Defined in

packages/core/src/router/AbstractRouter.ts:93


_mountedPromise

Protected _mountedPromise: null | { promise: Promise<void> ; reject: () => void ; resolve: () => void } = null

Mounted promise to prevent routing until app is fully mounted.

Defined in

packages/core/src/router/ClientRouter.ts:52


_pageManager

Protected _pageManager: PageManager

The page manager handling UI rendering, and transitions between pages if at the client side.

Inherited from

AbstractRouter._pageManager

Defined in

packages/core/src/router/AbstractRouter.ts:53


_protocol

Protected _protocol: string = ''

The current protocol used to access the application, terminated by a colon (for example https:).

Inherited from

AbstractRouter._protocol

Defined in

packages/core/src/router/AbstractRouter.ts:66


_root

Protected _root: string = ''

The URL path pointing to the application's root.

Inherited from

AbstractRouter._root

Defined in

packages/core/src/router/AbstractRouter.ts:74


_routeHandlers

Protected _routeHandlers: Map<string, AbstractRoute<string | RoutePathExpression> | RouterMiddleware>

Storage of all known routes and middlewares. The key are their names.

Inherited from

AbstractRouter._routeHandlers

Defined in

packages/core/src/router/AbstractRouter.ts:83


_window

Protected _window: Window

Defined in

packages/core/src/router/ClientRouter.ts:43

Accessors

$dependencies

Static get $dependencies(): Dependencies

Returns

Dependencies

Defined in

packages/core/src/router/ClientRouter.ts:58

Methods

#addParamsFromOriginalRoute

Private #addParamsFromOriginalRoute(params): Object

Obtains original route that was handled before not-found / error route and assigns its params to current params

Parameters

NameTypeDescription
paramsRouteParamsRoute params for not-found or error page

Returns

Object

Provided params merged with params from original route

Inherited from

AbstractRouter.#addParamsFromOriginalRoute

Defined in

packages/core/src/router/AbstractRouter.ts:724


#handleMounted

Private #handleMounted(): void

Returns

void

Defined in

packages/core/src/router/ClientRouter.ts:454


_boundHandleClick

Protected _boundHandleClick(event): void

Parameters

NameType
eventEvent

Returns

void

Defined in

packages/core/src/router/ClientRouter.ts:44


_boundHandlePopState

Protected _boundHandlePopState(event): void

Parameters

NameType
eventEvent

Returns

void

Defined in

packages/core/src/router/ClientRouter.ts:46


_extractRoutePath

Protected _extractRoutePath(path): string

Strips the URL path part that points to the application's root (base URL) from the provided path.

Parameters

NameTypeDescription
pathstringRelative or absolute URL path.

Returns

string

URL path relative to the application's base URL.

Inherited from

AbstractRouter._extractRoutePath

Defined in

packages/core/src/router/AbstractRouter.ts:513


_getAnchorElement

_getAnchorElement(target): Node

The method determines whether an anchor element or a child of an anchor element has been clicked, and if it was, the method returns anchor element else null.

Parameters

NameType
targetNode

Returns

Node

Defined in

packages/core/src/router/ClientRouter.ts:399


_getCurrentlyRoutedPath

_getCurrentlyRoutedPath(): string

Returns path that is stored in private property when a route method is called.

Returns

string

Inherited from

AbstractRouter._getCurrentlyRoutedPath

Defined in

packages/core/src/router/AbstractRouter.ts:655


_getMiddlewaresForRoute

_getMiddlewaresForRoute(routeName): RouterMiddleware[]

Returns middlewares preceding given route name.

Parameters

NameType
routeNamestring

Returns

RouterMiddleware[]

Inherited from

AbstractRouter._getMiddlewaresForRoute

Defined in

packages/core/src/router/AbstractRouter.ts:633


_handle

_handle(route, params, options?, action?): Promise<void | UnknownParameters>

Handles the provided route and parameters by initializing the route's controller and rendering its state via the route's view.

The result is then sent to the client if used at the server side, or displayed if used as the client side.

Parameters

NameTypeDescription
routeAbstractRoute<string | RoutePathExpression>The route that should have its associated controller rendered via the associated view.
paramsRouteParamsParameters extracted from the URL path and query.
options?Partial<RouteOptions>The options overrides route options defined in the routes.js configuration file.
action?RouteActionAn action object describing what triggered this routing.

Returns

Promise<void | UnknownParameters>

A promise that resolves when the page is rendered and the result is sent to the client, or displayed if used at the client side.

Inherited from

AbstractRouter._handle

Defined in

packages/core/src/router/AbstractRouter.ts:536


_handleClick

_handleClick(event): void

Handles a click event. The method performs navigation to the target location of the anchor (if it has one).

The navigation will be handled by the router if the protocol and domain of the anchor's target location (href) is the same as the current, otherwise the method results in a hard redirect.

Parameters

NameTypeDescription
eventMouseEventThe click event.

Returns

void

Defined in

packages/core/src/router/ClientRouter.ts:349


_handleFatalError

_handleFatalError(error): void

Handle a fatal error application state. IMA handle fatal error when IMA handle error.

Parameters

NameType
errorError

Returns

void

Defined in

packages/core/src/router/ClientRouter.ts:304


_handlePopState

_handlePopState(event): void

Handles a popstate event. The method is performed when the active history entry changes.

The navigation will be handled by the router if the event state is defined and event is not defaultPrevented.

Parameters

NameTypeDescription
eventPopStateEventThe popstate event.

Returns

void

Defined in

packages/core/src/router/ClientRouter.ts:325


_isHashLink(targetUrl): boolean

Tests whether the provided target URL contains only an update of the hash fragment of the current URL.

Parameters

NameTypeDescription
targetUrlstringThe target URL.

Returns

boolean

true if the navigation to target URL would result only in updating the hash fragment of the current URL.

Defined in

packages/core/src/router/ClientRouter.ts:427


_isSameDomain

_isSameDomain(url?): boolean

Tests whether the the protocol and domain of the provided URL are the same as the current.

Parameters

NameTypeDefault valueDescription
url?string''The URL.

Returns

boolean

true if the protocol and domain of the provided URL are the same as the current.

Defined in

packages/core/src/router/ClientRouter.ts:450


_runMiddlewares

_runMiddlewares(middlewares, params, locals): Promise<void>

Runs provided middlewares in sequence.

Parameters

NameTypeDescription
middlewaresundefined | RouterMiddleware[]Array of middlewares.
paramsRouteParamsRouter params that can be mutated by middlewares.
localsRouteLocalsThe locals param is used to pass local data between middlewares.

Returns

Promise<void>

Inherited from

AbstractRouter._runMiddlewares

Defined in

packages/core/src/router/AbstractRouter.ts:668


add

add(name, pathExpression, controller, view, options?): ClientRouter

Adds a new route to router.

Parameters

NameTypeDescription
namestringThe unique name of this route, identifying it among the rest of the routes in the application.
pathExpressionstringA path expression specifying the URL path part matching this route (must not contain a query string), optionally containing named parameter placeholders specified as :parameterName. The name of the parameter is terminated by a forward slash (/) or the end of the path expression string. The path expression may also contain optional parameters, which are specified as :?parameterName. It is recommended to specify the optional parameters at the end of the path expression.
controllerAsyncRouteControllerThe full name of Object Container alias identifying the controller associated with this route.
viewAsyncRouteViewThe full name or Object Container alias identifying the view class associated with this route.
options?Partial<RouteOptions>Additional route options, specified how the navigation to the route will be handled. The onlyUpdate can be either a flag signalling whether the current controller and view instances should be kept if they match the ones used by the previous route; or a callback function that will receive the previous controller and view identifiers used in the previously matching route, and returns a boolean representing the value of the flag. This flag is disabled by default. The autoScroll flag signals whether the page should be scrolled to the top when the navigation takes place. This flag is enabled by default.

Returns

ClientRouter

This router.

Throws

Thrown if a route with the same name already exists.

Inherited from

AbstractRouter.add

Defined in

packages/core/src/router/AbstractRouter.ts:154


getBaseUrl

getBaseUrl(): string

Returns the application's absolute base URL, pointing to the public root of the application.

Returns

string

The application's base URL.

Inherited from

AbstractRouter.getBaseUrl

Defined in

packages/core/src/router/AbstractRouter.ts:230


getCurrentRouteInfo

getCurrentRouteInfo(): Object

Returns the information about the currently active route.

Returns

Object

NameType
paramsRouteParams
pathstring
routeAbstractRoute<string | RoutePathExpression>

Throws

Thrown if a route is not define for current path.

Inherited from

AbstractRouter.getCurrentRouteInfo

Defined in

packages/core/src/router/AbstractRouter.ts:258


getDomain

getDomain(): string

Returns the application's domain in the following form ${protocol}//${host}.

Returns

string

The current application's domain.

Inherited from

AbstractRouter.getDomain

Defined in

packages/core/src/router/AbstractRouter.ts:237


getHost

getHost(): string

Returns application's host (domain and, if necessary, the port number).

Returns

string

The current application's host.

Inherited from

AbstractRouter.getHost

Defined in

packages/core/src/router/AbstractRouter.ts:244


getPath

getPath(): string

Returns the current path part of the current URL, including the query string (if any).

Returns

string

The path and query parts of the current URL.

Overrides

AbstractRouter.getPath

Defined in

packages/core/src/router/ClientRouter.ts:119


getProtocol

getProtocol(): string

Returns the current protocol used to access the application, terminated by a colon (for example https:).

Returns

string

The current application protocol used to access the application.

Inherited from

AbstractRouter.getProtocol

Defined in

packages/core/src/router/AbstractRouter.ts:251


getRouteHandler

getRouteHandler(name): undefined | AbstractRoute<string | RoutePathExpression> | RouterMiddleware

Returns specified handler from registered route handlers.

Parameters

NameTypeDescription
namestringThe route's unique name.

Returns

undefined | AbstractRoute<string | RoutePathExpression> | RouterMiddleware

Route with given name or undefined.

Inherited from

AbstractRouter.getRouteHandler

Defined in

packages/core/src/router/AbstractRouter.ts:207


getRouteHandlers

getRouteHandlers(): Map<string, AbstractRoute<string | RoutePathExpression> | RouterMiddleware>

Returns

Map<string, AbstractRoute<string | RoutePathExpression> | RouterMiddleware>

Inherit Doc

Inherited from

AbstractRouter.getRouteHandlers

Defined in

packages/core/src/router/AbstractRouter.ts:284


getRouteHandlersByPath

getRouteHandlersByPath(path): Object

Returns the route matching the provided URL path part (the path may contain a query) and all middlewares preceding this route definition.

Parameters

NameTypeDescription
pathstringThe URL path.

Returns

Object

The route matching the path and middlewares preceding it or {} (empty object) if no such route exists.

NameType
middlewaresRouterMiddleware[]
route?AbstractRoute<string | RoutePathExpression>

Inherited from

AbstractRouter.getRouteHandlersByPath

Defined in

packages/core/src/router/AbstractRouter.ts:606


getUrl

getUrl(): string

Returns the current absolute URL (including protocol, host, query, etc).

Returns

string

The current absolute URL.

Overrides

AbstractRouter.getUrl

Defined in

packages/core/src/router/ClientRouter.ts:112


handleError

handleError(params, options?, locals?): Promise<void | UnknownParameters>

Handles an internal server error by responding with the appropriate "internal server error" error page.

Parameters

NameTypeDescription
paramsRouteParamsParameters extracted from the current URL path and query.
options?Partial<RouteOptions>The options overrides route options defined in the routes.js configuration file.
locals?RouteLocalsThe locals param is used to pass local data between middlewares.

Returns

Promise<void | UnknownParameters>

A promise resolved when the error has been handled and the response has been sent to the client, or displayed if used at the client side.

Overrides

AbstractRouter.handleError

Defined in

packages/core/src/router/ClientRouter.ts:232


handleNotFound

handleNotFound(params, options?, locals?): Promise<void | UnknownParameters>

Handles a "not found" error by responding with the appropriate "not found" error page.

Parameters

NameTypeDescription
paramsStringParametersParameters extracted from the current URL path and query.
optionsObjectThe options overrides route options defined in the routes.js configuration file.
localsObjectThe locals param is used to pass local data between middlewares.

Returns

Promise<void | UnknownParameters>

A promise resolved when the error has been handled and the response has been sent to the client, or displayed if used at the client side.

Overrides

AbstractRouter.handleNotFound

Defined in

packages/core/src/router/ClientRouter.ts:292


init

init(config): ClientRouter

Initializes the router with the provided configuration.

Parameters

NameTypeDescription
configObjectRouter configuration. The $Protocol field must be the current protocol used to access the application, terminated by a colon (for example https:). The $Root field must specify the URL path pointing to the application's root. The $LanguagePartPath field must be the URL path fragment used as a suffix to the $Root field that specifies the current language. The $Host field must be the application's domain (and the port number if other than the default is used) in the following form: ${protocol}//${host}.
config.$Hoststring-
config.$LanguagePartPathstring-
config.$Protocolstring-
config.$Rootstring-

Returns

ClientRouter

Overrides

AbstractRouter.init

Defined in

packages/core/src/router/ClientRouter.ts:96


isClientError

isClientError(reason): boolean

Tests, if possible, whether the specified error was caused by the client's action (for example wrong URL or request encoding) or by a failure at the server side.

Parameters

NameTypeDescription
reasonError | ErrorThe encountered error.

Returns

boolean

true if the error was caused the action of the client.

Inherited from

AbstractRouter.isClientError

Defined in

packages/core/src/router/AbstractRouter.ts:494


isRedirection

isRedirection(reason): boolean

Tests, if possible, whether the specified error lead to redirection.

Parameters

NameTypeDescription
reasonError | ErrorThe encountered error.

Returns

boolean

true if the error was caused the action of the redirection.

Inherited from

AbstractRouter.isRedirection

Defined in

packages/core/src/router/AbstractRouter.ts:501


link(routeName, params): string

Generates an absolute URL (including protocol, domain, etc) for the specified route by substituting the route's parameter placeholders with the provided parameter values.

Parameters

NameTypeDescription
routeNamestringThe unique name of the route, identifying the route to use.
paramsRouteParamsParameter values for the route's parameter placeholders. Extraneous parameters will be added as URL query.

Returns

string

An absolute URL for the specified route and parameters.

Inherited from

AbstractRouter.link

Defined in

packages/core/src/router/AbstractRouter.ts:325


listen

listen(): ClientRouter

Registers event listeners at the client side window object allowing the router to capture user's history (history pop state - going "back") and page (clicking links) navigation.

The router will start processing the navigation internally, handling the user's navigation to display the page related to the URL resulting from the user's action.

Note that the router will not prevent forms from being submitted to the server.

The effects of this method can be reverted with unlisten. This method has no effect at the server side.

Returns

ClientRouter

This router.

Overrides

AbstractRouter.listen

Defined in

packages/core/src/router/ClientRouter.ts:126


redirect

redirect(url, options?, action?, locals?): void

Redirects the client to the specified location.

At the server side the method results in responding to the client with a redirect HTTP status code and the Location header.

At the client side the method updates the current URL by manipulating the browser history (if the target URL is at the same domain and protocol as the current one) or performs a hard redirect (if the target URL points to a different protocol or domain).

The method will result in the router handling the new URL and routing the client to the related page if the URL is set at the client side and points to the same domain and protocol.

Parameters

NameTypeDescription
urlstringThe URL to which the client should be redirected.
options?Partial<RouteOptions>The options overrides route options defined in the routes.js configuration file.
action?RouteActionAn action object describing what triggered this routing.
locals?RouteLocalsThe locals param is used to pass local data between middlewares.

Returns

void

Overrides

AbstractRouter.redirect

Defined in

packages/core/src/router/ClientRouter.ts:168


remove

remove(name): ClientRouter

Removes the specified route from the router's known routes.

Parameters

NameTypeDescription
namestringThe route's unique name, identifying the route to remove.

Returns

ClientRouter

This router.

Inherited from

AbstractRouter.remove

Defined in

packages/core/src/router/AbstractRouter.ts:198


route

route(path, options?, action?, locals?): Promise<void | UnknownParameters>

Routes the application to the route matching the providing path, renders the route page and sends the result to the client.

Parameters

NameTypeDescription
pathstringThe URL path part received from the client, with optional query.
options?Partial<RouteOptions>The options overrides route options defined in the routes.js configuration file.
action?RouteActionAn action object describing what triggered this routing.
locals?RouteLocalsThe locals param is used to pass local data between middlewares.

Returns

Promise<void | UnknownParameters>

A promise resolved when the error has been handled and the response has been sent to the client, or displayed if used at the client side.

Overrides

AbstractRouter.route

Defined in

packages/core/src/router/ClientRouter.ts:197


unlisten

unlisten(): ClientRouter

Unregisters event listeners at the client side window object allowing the router to capture user's history (history pop state - going "back") and page (clicking links) navigation.

The router will stop processing the navigation internally, handling the user's navigation to display the page related to the URL resulting from the user's action.

Note that the router will not prevent forms from being submitted to the server.

The effects of this method can be reverted with unlisten. This method has no effect at the server side.

Returns

ClientRouter

This router.

Overrides

AbstractRouter.unlisten

Defined in

packages/core/src/router/ClientRouter.ts:147


use

use(middleware): ClientRouter

Adds a new middleware to router.

Parameters

NameTypeDescription
middlewareRouterMiddlewareMiddleware function accepting routeParams as a first argument, which can be mutated and locals object as second argument. This can be used to pass data between middlewares.

Returns

ClientRouter

This router.

Throws

Thrown if a middleware with the same name already exists.

Inherited from

AbstractRouter.use

Defined in

packages/core/src/router/AbstractRouter.ts:186