Documentation

Namespace

router

kiss.router

A simple client router

The router allows to navigate between different views in a single-page application. It also works with local files paths (file:///)

The router is based on the url hash, for example:

/index.html#ui=homepage

The "ui" parameter is mandatory and represents the main view to display. Other parameters can be added to the url hash to manage deeper navigation:

/index.html#ui=homepage&applicationId=123&viewId=456

If you need to display multiple views simultaneously, you can use multiple parameters starting with "ui":

/index.html#ui=homepage&ui1=map&ui2=account

To use the router:

kiss.router.navigateTo(newRoute)

You can pass a single string if you just want to change the main view:

kiss.router.navigateTo("homepage")

This is equivalent to:

kiss.router.navigateTo({ui: "homepage"})

If you need deeper navigation, you can pass an object:

kiss.router.navigateTo({ui: "homepage", applicationId: "123", viewId: "456"})

The router observes url hash changes and automatically triggers new routes accordingly.

When initializing the router, you can optionally define public routes:

// Init your app router:
kiss.router.init({
 publicRoutes: ["login", "register"]
})

// Setting public routes after initialization:
kiss.router.setPublicRoutes(["login", "register"])

// Adding routing guards, to check if a route is valid before routing:
kiss.router.addRoutingGuards([
 async function(newRoute) {
     return await app.api.checkViewAuthorization(newRoute)
 }
])

// Adding routing actions, to perform some actions after routing:
kiss.router.addRoutingActions([
 async function() {
     // Do something after routing
 }
])

// Navigating to a new route:
kiss.router.navigateTo({ui: "homepage", applicationId: "123", viewId: "456"})

// Get the current application route by reading the url hash:
const currentApplicationRoute = kiss.router.getRoute() // {ui: "homepage", applicationId: "123", viewId: "456"}

View Source client/core/modules/router.js, line 81

Members

# static publicRoutes

Default list of public routes which doesn't require authentication.

Add custom public routes using addPublicRoutes([...]) method.

By default, the following routes are public:

  • authentication-login
  • authentication-register
  • authentication-reset-password
  • authentication-error

View Source client/core/modules/router.js, line 93

Methods

# static addPublicRoutes(publicRoutes)

Add some public routes

Parameters:
Name Type Description
publicRoutes Array.<string>

View Source client/core/modules/router.js, line 146

# static addRoutingActions(actions)

Add routing actions

Actions are used to perform some actions after routing. Must be an array of async functions to execute sequentially.

Parameters:
Name Type Description
actions Array.<function()>

View Source client/core/modules/router.js, line 173

# static addRoutingGuards(guards)

Add routing guards

Guards are used to check if a route is valid before routing. Must be an array of async functions where each function must return a boolean. The route is accepted if all guards return true.

Parameters:
Name Type Description
guards Array.<function()>

View Source client/core/modules/router.js, line 159

# static getRoute() → {object}

Get the current application route from the url hash.

For example:

  • if current url is: http://.../...#ui=homepage&applicationId=123&viewId=456
  • the output is: {ui: "homepage", applicationId: "123", viewId: "456"}

View Source client/core/modules/router.js, line 231

object

# static init(config)

Init the router

It will observe any url hash change, which will:

  • perform a custom action before triggering the new route
  • perform a custom action after the routing
Parameters:
Name Type Attributes Description
config object

The router config, containing the 2 methods:
publicRoutes Array.<string> <optional>

Define public routes (skip login)

View Source client/core/modules/router.js, line 110

# static isPublicRoute() → {boolean}

Check if the current route (given by the ui parameter) is public

View Source client/core/modules/router.js, line 184

boolean

# static navigateTo(newRoute, resetopt)

Navigate to a new hash It indirectly triggers the new route by dispatching the window's hashchange event.

Parameters:
Name Type Attributes Description
newRoute object | string
reset boolean <optional>

Set to true to reset the previous route before routing to a new one

View Source client/core/modules/router.js, line 205

Example
// Using an object
const newRoute = {ui: "homepage", applicationId: "123", viewId: "456"}
kiss.router.navigateTo(newRoute)

// Using a string
kiss.router.navigateTo("home-start") // Is equivalent to: kiss.router.navigateTo({ui: "home-start"})

# static setPublicRoutes(publicRoutes)

Set the public routes

Parameters:
Name Type Description
publicRoutes Array.<string>

View Source client/core/modules/router.js, line 137

# static updateUrlHash(newRoute, resetopt)

Update URL hash according to new route params.

Parameters:
Name Type Attributes Description
newRoute object
reset boolean <optional>

True to reset the current hash

View Source client/core/modules/router.js, line 244

Example
kiss.router.updateUrlHash({chapter: 10, section: 2}, true)