Class: AbstractRouter

@ima/core.AbstractRouter

The basic implementation of the Router interface, providing the common or default functionality for parts of the API.

Hierarchy

• Router

  ↳ AbstractRouter

  ↳↳ ClientRouter

  ↳↳ ServerRouter

  ↳↳ ClientRouter

  ↳↳ ServerRouter

Constructors

constructor

• new AbstractRouter(pageManager, factory, dispatcher, settings)

Initializes the 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.
settings	undefined | number | { isSPARouted?: (url: string, action?: RouteAction) => boolean ; middlewareTimeout?: number }	-

Example

router.link('article', {articleId: 1});

Example

router.redirect('http://www.example.com/web');

Example

router.add(
       'home',
       '/',
       ns.app.page.home.Controller,
       ns.app.page.home.View,
       {
         onlyUpdate: false,
         autoScroll: true,
         documentView: null,
         managedRootView: null,
         viewAdapter: null
       }
     );

Overrides

Router.constructor

Defined in

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

Properties

_currentMiddlewareId

• Protected _currentMiddlewareId: number = 0

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

Defined in

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

---

_currentlyRoutedPath

• Protected _currentlyRoutedPath: string = ''

Defined in

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

---

_dispatcher

• Protected _dispatcher: Dispatcher

Dispatcher fires events to app.

Defined in

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

---

_factory

• Protected _factory: RouteFactory

Factory for routes.

Defined in

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

---

_host

• Protected _host: string = ''

The application's host.

Defined in

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

---

_isSPARouted

• Protected _isSPARouted: undefined | (url: string, action?: RouteAction) => boolean

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.

Defined in

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

---

_middlewareTimeout

• Protected _middlewareTimeout: number

Defined in

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

---

_pageManager

• Protected _pageManager: PageManager

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

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:).

Defined in

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

---

_root

• Protected _root: string = ''

The URL path pointing to the application's root.

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.

Defined in

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

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

Defined in

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

---

_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.

Defined in

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

---

_getCurrentlyRoutedPath

▸ _getCurrentlyRoutedPath(): string

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

Returns

string

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

RouterMiddleware[]

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.

Defined in

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

---

_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>

Defined in

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

---

add

▸ add(name, pathExpression, controller, view, options?): AbstractRouter

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

AbstractRouter

This router.

Throws

Thrown if a route with the same name already exists.

Overrides

Router.add

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.

Overrides

Router.getBaseUrl

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.

Overrides

Router.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.

Overrides

Router.getDomain

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.

Overrides

Router.getHost

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

Router.getPath

Defined in

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

---

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.

Overrides

Router.getProtocol

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.

Overrides

Router.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

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>

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

Router.getUrl

Defined in

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

---

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

Router.handleError

Defined in

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

---

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	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

Router.handleNotFound

Defined in

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

---

init

▸ init(config): void

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

void

Overrides

Router.init

Defined in

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

---

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.

Overrides

Router.isClientError

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.

Overrides

Router.isRedirection

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.

Overrides

Router.link

Defined in

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

---

listen

▸ listen(): AbstractRouter

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

AbstractRouter

This router.

Overrides

Router.listen

Defined in

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

---

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

Router.redirect

Defined in

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

---

remove

▸ remove(name): AbstractRouter

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

AbstractRouter

This router.

Overrides

Router.remove

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

Router.route

Defined in

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

---

unlisten

▸ unlisten(): AbstractRouter

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

AbstractRouter

This router.

Overrides

Router.unlisten

Defined in

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

---

use

▸ use(middleware): AbstractRouter

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

AbstractRouter

This router.

Throws

Thrown if a middleware with the same name already exists.

Overrides

Router.use

Defined in

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