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 80

Members

# static pathnameToRoute

Optional mapper used in pathname mode to convert a pathname to a route object. Signature: pathnameToRoute(pathname) => routeObject

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

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

# static routeToPathname

Optional mapper used in pathname mode to convert a route object to a pathname. Signature: routeToPathname(routeObject) => pathname

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

# static routerMode

Routing mode.

  • "hash" (default): route is read/written from URL hash
  • "pathname": route is read/written from URL pathname using mapping functions

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

Methods

# static addPublicRoutes(publicRoutes)

Add some public routes

Parameters:
Name Type Description
publicRoutes Array.<string>

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

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

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

# static getRoute() → {object}

Get the current application route from the current URL.

Route priority:

  • if URL hash is exploitable, it's always used
  • otherwise, if pathname mode is enabled, pathnameToRoute(pathname) is used

A route is considered exploitable when it contains a non-empty "ui" string.

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 288

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

Routing modes:

  • "hash" (default): route is stored in URL hash (example: /index.html#ui=homepage&applicationId=123)
  • "pathname": route is stored in URL pathname using 2 optional mapping functions (example: /fr/landing mapped to {ui: "start", content: "landing", language: "fr"})

In pathname mode, you can inject:

  • pathnameToRoute(pathname): converts current URL pathname to a route object
  • routeToPathname(route): converts a route object to a pathname for navigation

Example:

kiss.router.init({
  routerMode: "pathname",
  pathnameToRoute(pathname) {
    if (pathname === "/fr/landing") return {ui: "start", content: "landing", language: "fr"}
    if (pathname === "/en/landing") return {ui: "start", content: "landing", language: "en"}
    return {}
  },
  routeToPathname(route) {
    if (route.ui === "start" && route.content === "landing") {
      return `/${route.language || "en"}/landing`
    }
    return "/"
  }
})
Parameters:
Name Type Attributes Description
config object

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

Define public routes (skip login)
routerMode string <optional>

"hash" (default) or "pathname"
usePathRouting boolean <optional>

Shortcut to set routerMode to "pathname"
pathnameToRoute function <optional>

Mapper: pathname => route object
routeToPathname function <optional>

Mapper: route object => pathname

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

# static isPublicRoute() → {boolean}

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

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

boolean

# static navigateTo(newRoute, resetopt)

Navigate to a new route.

URL update strategy depends on router mode:

  • hash mode: write to URL hash
  • pathname mode: write to URL pathname if routeToPathname is provided
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 265

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 194

# static updateUrlHash(newRoute, resetopt)

Update URL according to new route params.

Kept as updateUrlHash for backward compatibility. In pathname mode, if reset is true, it uses history.replaceState to avoid creating a new browser history entry.

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

True to reset the current hash

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

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