Skip to main content

Class: Router

@ima/core.Router

The router manages the application's routing configuration and dispatches controllers and views according to the current URL and the route it matches.

Hierarchy

Constructors

constructor

new Router()

Methods

add

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

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

Router

This router.

Throws

Thrown if a route with the same name already exists.

Defined in

packages/core/src/router/Router.ts:128


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.

Defined in

packages/core/src/router/Router.ts:199


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.

Defined in

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


getDomain

getDomain(): string

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

Returns

string

The current application's domain.

Defined in

packages/core/src/router/Router.ts:209


getHost

getHost(): string

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

Returns

string

The current application's host.

Defined in

packages/core/src/router/Router.ts:218


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.

Defined in

packages/core/src/router/Router.ts:180


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.

Defined in

packages/core/src/router/Router.ts:229


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.

Defined in

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


getUrl

getUrl(): string

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

Returns

string

The current absolute URL.

Defined in

packages/core/src/router/Router.ts:189


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.

Defined in

packages/core/src/router/Router.ts:374


handleNotFound

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

Handles a "not found" error by responding with the appropriate "not found" 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.

Defined in

packages/core/src/router/Router.ts:396


init

init(config): void

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

void

Defined in

packages/core/src/router/Router.ts:84


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.

Defined in

packages/core/src/router/Router.ts:413


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.

Defined in

packages/core/src/router/Router.ts:424


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.

Defined in

packages/core/src/router/Router.ts:332


listen

listen(): Router

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

Router

This router.

Defined in

packages/core/src/router/Router.ts:264


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

Defined in

packages/core/src/router/Router.ts:311


remove

remove(name): Router

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

Parameters

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

Returns

Router

This router.

Defined in

packages/core/src/router/Router.ts:158


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.

Defined in

packages/core/src/router/Router.ts:351


unlisten

unlisten(): Router

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

Router

This router.

Defined in

packages/core/src/router/Router.ts:285


use

use(middleware): Router

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

Router

This router.

Throws

Thrown if a middleware with the same name already exists.

Defined in

packages/core/src/router/Router.ts:148