C class

Router

Router handles URL routing in Viking applications.

The Router maps URLs to controllers and actions, allowing for clean, RESTful URLs. It manages browser history and provides navigation methods to move between application states without full page reloads.

Router Events

EventArgumentsDescription
beforeNavigationurlTriggered when navigation in the app is about to happen
afterNavigationurlTriggered when navigation in the app has completed

Constructor

new Router(application)
application : Application

The application this router belongs to

Instance Properties

P   bindedObjects: Object.<string, Object>

Object containing references to objects this instance is listening to

P   escapeRegExp: RegExp

Regular expression for escaping special characters in routes

P   eventListeners: Object.<string, Array>

Object containing all event listeners

P   handlers: Array.<RouterHandler>

Array of route handlers

P   listenerId: string

Unique identifier for this event bus instance

P   namedParam: RegExp

Regular expression for matching named parameters

P   optionalParam: RegExp

Regular expression for matching optional parameters

P   routes: RouteSet

Static routes configuration

P   splatParam: RegExp

Regular expression for matching splat parameters

Instance Methods

F   addEventListener(name, callback, options) → EventBus

Bind an event to a callback function. Passing "*" will bind the callback to all events fired.

If the options.once is true, the event will only be triggered a single time. After the first time the callback is invoked, its listener will be removed. If multiple events are passed in as an array, the handler will fire once for each event, not once for a combination of all events.

Parameters

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

listener : object optional

The listener object

Returns

EventBus

Returns this for chaining

F   addEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to listen to an event in another object, while keeping track of what it's listening to for easier unbinding later.

Parameters

obj : object | NodeList

The object to listen to events on

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

Returns

EventBus

Returns this for chaining

F   dispatchEvent(name, args) → EventBus

Trigger one or many events, firing all bound callbacks. Callbacks are passed the same arguments as dispatchEvent is, apart from the event name (unless you're listening on "*", which will cause your callback to receive the true name of the event as the first argument).

Parameters

name : string | Array.<string>

Event name or array of event names

args : *

Arguments to pass to the event handlers

Returns

EventBus

Returns this for chaining

F   getPath() → string

Get the current URL path

Returns

string

The current URL path, decoded

F   getSearch() → string

Get the current URL query string

Returns

string

The query string portion of the URL

F   handlerForPath(path) → RouterHandler | undefined

Find the handler for a given path

Parameters

path : string

The path to find a handler for

Returns

RouterHandler | undefined

The handler for the path, or undefined if not found

F   initialize()

Initialize is an empty function by default. Override it with your own initialization logic if needed.

F   loadUrl()

Load the current URL and execute the matching handler

This method is called on popstate events and when navigating programmatically

F   navigateTo(url, params)

Navigate to a specific URL, updating browser history and firing navigation events

Parameters

url : string

The URL to navigate to

params : Object optional

Query parameters to append to the URL

F   removeEventListener(name, callback, options) → EventBus

Remove one or many callbacks that match the arguments. If called with no arguments, removes all callbacks for all events.

Parameters

name : string | Array.<string> | object | null optional

Event name(s) or object of event/callback pairs

callback : function | object | null optional

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

listener : object optional

Match only events bound by this listener

Returns

EventBus

Returns this for chaining

F   removeEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to stop listening to either specific events or to every object it's currently listening to.

Parameters

obj : object | NodeList optional

The object to stop listening to; if omitted, stops listening to all objects

name : string | Array.<string> | object optional

Event name(s) or object of event/callback pairs

callback : function optional

Callback function to remove

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

Returns

EventBus

Returns this for chaining

F   route(route, name, callback) → Viking.Router

Define a route that maps a URL pattern to a controller action or callback function

Parameters

route : string | RegExp

The route pattern to match

name : string | Object | function optional

The name of the route, controller#action string, or handler function

callback : function optional

The callback function to execute when the route matches

Returns

Viking.Router

Returns this for chaining

F   routeToRegExp(route) → RegExp

Convert a route string pattern to a regular expression

The router uses the following syntax for defining routes:

  • :name - Named parameter
  • *splat - Splat parameter
  • (...) - Optional part

Parameters

route : string

The route pattern to convert

Returns

RegExp

A regular expression that matches the route pattern

F   start()

Start the router, loading the current URL

F   stop()

Stop the router, removing event listeners