Methods
-
add(name, pathExpression, controller, view [, options])
-
Adds a new route to router.
Parameters:
Name Type Argument 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
string The full name of Object Container alias identifying the controller associated with this route.
view
string The full name or Object Container alias identifying the view class associated with this route.
options
Object <optional>
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 aboolean
representing the value of the flag. This flag is disabled by default. TheautoScroll
flag signals whether the page should be scrolled to the top when the navigation takes place. This flag is enabled by default. TheallowSPA
flag can be used to make the route always served from the server and never using the SPA page even if the server is overloaded. This is useful for routes that use different document views (specified by thedocumentView
option), for example for rendering the content of iframes.Throws:
-
Thrown if a route with the same name already exists.
- Type
- ImaError
Returns:
This router.
- Type
- Router
-
-
getBaseUrl()
-
Returns the application's absolute base URL, pointing to the public root of the application.
Returns:
The application's base URL.
- Type
- string
-
getCurrentRouteInfo()
-
Returns the information about the currently active route.
Throws:
-
Thrown if a route is not define for current path.
- Type
- ImaError
Returns:
The information about the current route.
- Type
- Object
-
-
getDomain()
-
Returns the application's domain in the following form
${protocol</code>//${host}
}.Returns:
The current application's domain.
- Type
- string
-
getHost()
-
Returns application's host (domain and, if necessary, the port number).
Returns:
The current application's host.
- Type
- string
-
getPath()
-
Returns the current path part of the current URL, including the query string (if any).
Returns:
The path and query parts of the current URL.
- Type
- string
-
getProtocol()
-
Returns the current protocol used to access the application, terminated by a colon (for example
https:
).Returns:
The current application protocol used to access the application.
- Type
- string
-
getUrl()
-
Returns the current absolute URL (including protocol, host, query, etc).
Returns:
The current absolute URL.
- Type
- string
-
handleError(params [, options])
-
Handles an internal server error by responding with the appropriate "internal server error" error page.
Parameters:
Name Type Argument Default Description params
Object.<string, (Error|string)> Parameters extracted from the current URL path and query.
options
Object <optional>
{} The options overrides route options defined in the
routes.js
configuration file.Returns:
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.
- Type
- Promise.<Object.<string, *>>
-
handleNotFound(params [, options])
-
Handles a "not found" error by responding with the appropriate "not found" error page.
Parameters:
Name Type Argument Default Description params
Object.<string, (Error|string)> Parameters extracted from the current URL path and query.
options
Object <optional>
{} The options overrides route options defined in the
routes.js
configuration file.Returns:
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.
- Type
- Promise.<Object.<string, *>>
-
init(config)
-
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 collon (for examplehttps:
). 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</code>//${host}
}. -
isClientError(reason)
-
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
ImaError | Error The encountered error.
Returns:
true
if the error was caused the action of the client.- Type
- boolean
-
isRedirection(reason)
-
Tests, if possible, whether the specified error lead to redirection.
Parameters:
Name Type Description reason
ImaError | Error The encountered error.
Returns:
true
if the error was caused the action of the redirection.- Type
- boolean
-
link(routeName, params)
-
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
Object.<string, string> Parameter values for the route's parameter placeholders. Extraneous parameters will be added as URL query.
Returns:
An absolute URL for the specified route and parameters.
- Type
- string
-
listen()
-
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 cannot be reverted. This method has no effect at the server side.
Returns:
This router.
- Type
- Router
-
redirect(url [, options])
-
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 Argument Default Description url
string The URL to which the client should be redirected.
options
Object <optional>
{} The options overrides route options defined in the
routes.js
configuration file. -
remove(name)
-
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.
- Type
- Router
-
route(path [, options])
-
Routes the application to the route matching the providing path, renders the route page and sends the result to the client.
Parameters:
Name Type Argument Default Description path
string The URL path part received from the client, with optional query.
options
Object <optional>
{} The options overrides route options defined in the
routes.js
configuration file.Returns:
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.
- Type
- Promise.<Object.<string, *>>