Class: ClientRouter
@ima/core.ClientRouter
The client-side implementation of the Router interface.
Hierarchy
↳
ClientRouter
Constructors
constructor
• new ClientRouter(pageManager, factory, dispatcher, window, settings)
Initializes the client-side router.
Parameters
| Name | Type | Description |
|---|---|---|
pageManager | PageManager | The page manager handling UI rendering, and transitions between pages if at the client side. |
factory | RouteFactory | Factory for routes. |
dispatcher | Dispatcher | Dispatcher fires events to app. |
window | Window | The current global client-side APIs provider. |
settings | undefined | number | { isSPARouted?: (url: string, action?: RouteAction) => boolean ; middlewareTimeout?: number } | $Router settings. |
Overrides
Defined in
packages/core/src/router/ClientRouter.ts:79
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:92
_currentlyRoutedPath
• Protected _currentlyRoutedPath: string = ''
Inherited from
AbstractRouter._currentlyRoutedPath
Defined in
packages/core/src/router/AbstractRouter.ts:93
_dispatcher
• Protected _dispatcher: Dispatcher
Dispatcher fires events to app.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:62
_factory
• Protected _factory: RouteFactory
Factory for routes.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:58
_host
• Protected _host: string = ''
The application's host.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:71
_isSPARouted
• Protected _isSPARouted: undefined | (url: string, action?: RouteAction) => boolean
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:95
_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:80
_middlewareTimeout
• Protected _middlewareTimeout: number
Inherited from
AbstractRouter._middlewareTimeout
Defined in
packages/core/src/router/AbstractRouter.ts:94
_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:53
_pageManager
• Protected _pageManager: PageManager
The page manager handling UI rendering, and transitions between pages if at the client side.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:54
_protocol
• Protected _protocol: string = ''
The current protocol used to access the application, terminated by a
colon (for example https:).
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:67
_root
• Protected _root: string = ''
The URL path pointing to the application's root.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:75
_routeHandlers
• Protected _routeHandlers: Map<string, AbstractRoute<string | RoutePathExpression> | RouterMiddleware>
Storage of all known routes and middlewares. The key are their names.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:84
_window
• Protected _window: Window
Defined in
packages/core/src/router/ClientRouter.ts:44
Accessors
$dependencies
• Static get $dependencies(): Dependencies
Returns
Defined in
packages/core/src/router/ClientRouter.ts:59
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
| Name | Type | Description |
|---|---|---|
params | RouteParams | Route 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:737
#handleMounted
▸ Private #handleMounted(): void
Returns
void
Defined in
packages/core/src/router/ClientRouter.ts:476
#isSPARouted
▸ Private #isSPARouted(url?, action?): boolean
This option allows user to override how certain URLs are handled during SPA (client) routing. This adds possibility to opt-out of SPA routing for specific URLs and let them be handled by browser natively.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
url? | string | '' | The URL. |
action? | RouteAction | undefined | - |
Returns
boolean
true if url routing should be handled by IMA.
Defined in
packages/core/src/router/ClientRouter.ts:472
_boundHandleClick
▸ Protected _boundHandleClick(event): void
Parameters
| Name | Type |
|---|---|
event | Event |
Returns
void
Defined in
packages/core/src/router/ClientRouter.ts:45
_boundHandlePopState
▸ Protected _boundHandlePopState(event): void
Parameters
| Name | Type |
|---|---|
event | Event |
Returns
void
Defined in
packages/core/src/router/ClientRouter.ts:47
_extractRoutePath
▸ Protected _extractRoutePath(path): string
Strips the URL path part that points to the application's root (base URL) from the provided path.
Parameters
| Name | Type | Description |
|---|---|---|
path | string | Relative 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:526
_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
| Name | Type |
|---|---|
target | Node |
Returns
Node
Defined in
packages/core/src/router/ClientRouter.ts:408
_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:668
_getMiddlewaresForRoute
▸ _getMiddlewaresForRoute(routeName): RouterMiddleware[]
Returns middlewares preceding given route name.
Parameters
| Name | Type |
|---|---|
routeName | string |
Returns
Inherited from
AbstractRouter._getMiddlewaresForRoute
Defined in
packages/core/src/router/AbstractRouter.ts:646
_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
| Name | Type | Description |
|---|---|---|
route | AbstractRoute<string | RoutePathExpression> | The route that should have its associated controller rendered via the associated view. |
params | RouteParams | Parameters extracted from the URL path and query. |
options? | Partial<RouteOptions> | The options overrides route options defined in the routes.js configuration file. |
action? | RouteAction | An 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
Defined in
packages/core/src/router/AbstractRouter.ts:549
_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
| Name | Type | Description |
|---|---|---|
event | MouseEvent | The click event. |
Returns
void
Defined in
packages/core/src/router/ClientRouter.ts:350
_handleFatalError
▸ _handleFatalError(error): void
Handle a fatal error application state. IMA handle fatal error when IMA handle error.
Parameters
| Name | Type |
|---|---|
error | Error |
Returns
void
Defined in
packages/core/src/router/ClientRouter.ts:305
_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
| Name | Type | Description |
|---|---|---|
event | PopStateEvent | The popstate event. |
Returns
void
Defined in
packages/core/src/router/ClientRouter.ts:326
_isHashLink
▸ _isHashLink(targetUrl): boolean
Tests whether the provided target URL contains only an update of the hash fragment of the current URL.
Parameters
| Name | Type | Description |
|---|---|---|
targetUrl | string | The 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:436
_isSameDomain
▸ _isSameDomain(url?): boolean
Tests whether the the protocol and domain of the provided URL are the same as the current.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
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:459
_runMiddlewares
▸ _runMiddlewares(middlewares, params, locals): Promise<void>
Runs provided middlewares in sequence.
Parameters
| Name | Type | Description |
|---|---|---|
middlewares | undefined | RouterMiddleware[] | Array of middlewares. |
params | RouteParams | Router params that can be mutated by middlewares. |
locals | RouteLocals | The 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:681
add
▸ add(name, pathExpression, controller, view, options?): ClientRouter
Adds a new route to router.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The unique name of this route, identifying it among the rest of the routes in the application. |
pathExpression | string | A 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. |
controller | AsyncRouteController | The full name of Object Container alias identifying the controller associated with this route. |
view | AsyncRouteView | The 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
This router.
Throws
Thrown if a route with the same name already exists.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:167
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
Defined in
packages/core/src/router/AbstractRouter.ts:243
getCurrentRouteInfo
▸ getCurrentRouteInfo(): Object
Returns the information about the currently active route.
Returns
Object
| Name | Type |
|---|---|
params | RouteParams<{}> |
path | string |
route | AbstractRoute<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:271
getDomain
▸ getDomain(): string
Returns the application's domain in the following form
${protocol}//${host}.
Returns
string
The current application's domain.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:250
getHost
▸ getHost(): string
Returns application's host (domain and, if necessary, the port number).
Returns
string
The current application's host.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:257
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
Defined in
packages/core/src/router/ClientRouter.ts:120
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
Defined in
packages/core/src/router/AbstractRouter.ts:264
getRouteHandler
▸ getRouteHandler(name): undefined | AbstractRoute<string | RoutePathExpression> | RouterMiddleware
Returns specified handler from registered route handlers.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The 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:220
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:297
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
| Name | Type | Description |
|---|---|---|
path | string | The URL path. |
Returns
Object
The route
matching the path and middlewares preceding it or {}
(empty object) if no such route exists.
| Name | Type |
|---|---|
middlewares | RouterMiddleware[] |
route? | AbstractRoute<string | RoutePathExpression> |
Inherited from
AbstractRouter.getRouteHandlersByPath
Defined in
packages/core/src/router/AbstractRouter.ts:619
getUrl
▸ getUrl(): string
Returns the current absolute URL (including protocol, host, query, etc).
Returns
string
The current absolute URL.
Overrides
Defined in
packages/core/src/router/ClientRouter.ts:113
handleError
▸ handleError(params, options?, locals?): Promise<void | UnknownParameters>
Handles an internal server error by responding with the appropriate "internal server error" error page.
Parameters
| Name | Type | Description |
|---|---|---|
params | RouteParams | Parameters extracted from the current URL path and query. |
options? | Partial<RouteOptions> | The options overrides route options defined in the routes.js configuration file. |
locals? | RouteLocals | The 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
Defined in
packages/core/src/router/ClientRouter.ts:233
handleNotFound
▸ handleNotFound(params, options?, locals?): Promise<void | UnknownParameters>
Handles a "not found" error by responding with the appropriate "not found" error page.
Parameters
| Name | Type | Description |
|---|---|---|
params | StringParameters | Parameters extracted from the current URL path and query. |
options | Object | The options overrides route options defined in the routes.js configuration file. |
locals | Object | The 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
Defined in
packages/core/src/router/ClientRouter.ts:293
init
▸ init(config): ClientRouter
Initializes the router with the provided configuration.
Parameters
| Name | Type | Description |
|---|---|---|
config | Object | Router 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.$Host | string | - |
config.$LanguagePartPath | string | - |
config.$Protocol | string | - |
config.$Root | string | - |
Returns
Overrides
Defined in
packages/core/src/router/ClientRouter.ts:97
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
| Name | Type | Description |
|---|---|---|
reason | Error | Error | The encountered error. |
Returns
boolean
true if the error was caused the action of the
client.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:507
isRedirection
▸ isRedirection(reason): boolean
Tests, if possible, whether the specified error lead to redirection.
Parameters
| Name | Type | Description |
|---|---|---|
reason | Error | Error | The encountered error. |
Returns
boolean
true if the error was caused the action of the
redirection.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:514
link
▸ 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
| Name | Type | Description |
|---|---|---|
routeName | string | The unique name of the route, identifying the route to use. |
params | RouteParams | Parameter 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
Defined in
packages/core/src/router/AbstractRouter.ts:338
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
This router.
Overrides
Defined in
packages/core/src/router/ClientRouter.ts:127
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
| Name | Type | Description |
|---|---|---|
url | string | The URL to which the client should be redirected. |
options? | Partial<RouteOptions> | The options overrides route options defined in the routes.js configuration file. |
action? | RouteAction | An action object describing what triggered this routing. |
locals? | RouteLocals | The locals param is used to pass local data between middlewares. |
Returns
void
Overrides
Defined in
packages/core/src/router/ClientRouter.ts:169
remove
▸ remove(name): ClientRouter
Removes the specified route from the router's known routes.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The route's unique name, identifying the route to remove. |
Returns
This router.
Inherited from
Defined in
packages/core/src/router/AbstractRouter.ts:211
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
| Name | Type | Description |
|---|---|---|
path | string | The 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? | RouteAction | An action object describing what triggered this routing. |
locals? | RouteLocals | The 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
Defined in
packages/core/src/router/ClientRouter.ts:198
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
This router.
Overrides
Defined in
packages/core/src/router/ClientRouter.ts:148
use
▸ use(middleware): ClientRouter
Adds a new middleware to router.
Parameters
| Name | Type | Description |
|---|---|---|
middleware | RouterMiddleware | Middleware 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
This router.
Throws
Thrown if a middleware with the same name already exists.