StructureJS

0.15.2

A class based utility library for building modular and scalable web platform applications. Features opt-in classes and utilities which provide a solid foundation and toolset to build your next project.

Router Class

Defined in: ts/service/Router.ts:5
Module: controller
Parent Module: StructureJS

The Router class is a static class allows you to add different route patterns that can be matched to help control your application. Look at the Router.add method for more details and examples.

Index

Show:

Properties

Methods

Properties

_currentRoute RouterEvent private static

Defined in ts/service/Router.ts:79

A reference to the current RouterEvent that was triggered.

_defaultRoute Route private static

Defined in ts/service/Router.ts:59

A reference to default route object.

_hashChangeEvent Any private static

Defined in ts/service/Router.ts:69

A reference to the hash change event that was sent from the Window Object.

_lastHistoryState RouterEvent private static

Defined in ts/service/Router.ts:89

A reference to the last state object this Router creates when this using the HTML5 History API.

_routes Array private static

Defined in ts/service/Router.ts:29

A list of the added Route objects.

_validatorFunc Function private static

Defined in ts/service/Router.ts:49

TODO: YUIDoc_comment

_validators Array private static

Defined in ts/service/Router.ts:39

TODO: YUIDoc_comment

_window Window private static

Defined in ts/service/Router.ts:19

A reference to the browser Window Object.

allowManualDeepLinking Boolean public static

Defined in ts/service/Router.ts:144

The Router.allowManualDeepLinking property tells the Router class weather it should check for route matches if the hash url changes in the browser. This property only works if the Router. useDeepLinking is set to false. This is useful if want to use your added routes but don't want any external forces trigger your routes.

Typically what I do for games is during development/testing I allow the hash url to change the states so testers can jump to sections or levels easily but then when it is ready for production I set the property to false so users cannot jump around if they figure out the url schema.

Default: true

Example:

Router.useDeepLinking = false;
Router.allowManualDeepLinking = false;

allowMultipleMatches Boolean public static

Defined in ts/service/Router.ts:182

The Router.allowMultipleMatches property tells the Router class if it should trigger one or all routes that match a route pattern.

Default: true

Example:

// Only allow the first route matched to be triggered.
Router.allowMultipleMatches = false;

forceHashRouting Boolean public static

Defined in ts/service/Router.ts:100

Determines if the Router should use hash or history routing.

Default: false

Example:

Router.forceHashRouting = true;

forceSlash Boolean public static

Defined in ts/service/Router.ts:164

The Router.forceSlash property tells the Router class if the Router.navigateTo method is called to make sure the hash url has a forward slash after the # character like this #/.

Default: false

Example:

// To turn on forcing the forward slash
Router.forceSlash = true;

// If forceSlash is set to true it will change the url from #contact/bob/ to #/contact/bob/
// when using the navigateTo method.

isEnabled Boolean public static

Defined in ts/service/Router.ts:113

Determines if the Router class is enabled or disabled.

Example:

// Read only.
console.log(Router.isEnabled);

useDeepLinking Boolean public static

Defined in ts/service/Router.ts:127

The Router.useDeepLinking property tells the Router class weather it should change the hash url or not. By default this property is set to true. If you set the property to false and using the Router.navigateTo method the hash url will not change. This can be useful if you are making an application or game and you don't want the user to know how to jump to other sections directly. See the Router.allowManualDeepLinking to fully change the Router class from relying on the hash url to an internal state service.

Default: true

Example:

Router.useDeepLinking = true;

There are no properties that match your current filter settings. You can change your filter settings in the index section on this page. index

Methods

_allowRouteChange () private static

Defined in ts/service/Router.ts:837

TODO: YUIDoc_comment

_changeRoute
(
  • hash
)
private static

Defined in ts/service/Router.ts:717

The method is responsible for check if one of the routes matches the string value passed in.

Parameters:

_onHashChange
(
  • event
)
private static

Defined in ts/service/Router.ts:653

This method will be called if the Window object dispatches a HashChangeEvent. This method will not be called if the Router is disabled.

Parameters:

  • event HashChangeEvent

_onHistoryChange
(
  • event
)
private static

Defined in ts/service/Router.ts:676

This method will be called if the Window object dispatches a popstate event. This method will not be called if the Router is disabled.

Parameters:

  • event HashChangeEvent

add
(
  • routePattern
  • callback
  • callbackScope
)
public static

Defined in ts/service/Router.ts:201

The Router.add method allows you to listen for route patterns to be matched. When a match is found the callback will be executed passing a RouterEvent.

Parameters:

  • routePattern String

    The string pattern you want to have match, which can be any of the following combinations {}, ::, *, ?, ''. See the examples below for more details.

  • callback Function

    The function that should be executed when a request matches the routePattern. It will receive a RouterEvent object.

  • callbackScope Any

    The scope of the callback function that should be executed.

Example:

// Example of adding a route listener and the function callback below.
Router.add('/games/{gameName}/:level:/', this._method, this);

// The above route listener would match the below url:
// www.site.com/#/games/asteroids/2/

// The Call back receives a RouterEvent object.
_onRouteHandler(routerEvent) {
    console.log(routerEvent.params);
}

Route Pattern Options:

:optional: The two colons :: means a part of the hash url is optional for the match. The text between can be anything you want it to be.

Router.add('/contact/:name:/', this._method, this);

// Will match one of the following:
// www.site.com/#/contact/
// www.site.com/#/contact/heather/
// www.site.com/#/contact/john/

{required} The two curly brackets {} means a part of the hash url is required for the match. The text between can be anything you want it to be.

Router.add('/product/{productName}/', this._method, this);

// Will match one of the following:
// www.site.com/#/product/shoes/
// www.site.com/#/product/jackets/

* The asterisk character means it will match all or part of part the hash url.

Router.add('*', this._method, this);

// Will match one of the following:
// www.site.com/#/anything/
// www.site.com/#/matches/any/hash/url/
// www.site.com/#/really/it/matches/any/and/all/hash/urls/

? The question mark character means it will match a query string for the hash url.

Router.add('?', this._method, this);

// Will match one of the following:
// www.site.com/#/?one=1&two=2&three=3
// www.site.com/#?one=1&two=2&three=3

'' The empty string means it will match when there are no hash url.

Router.add('', this._method, this);
Router.add('/', this._method, this);

// Will match one of the following:
// www.site.com/
// www.site.com/#/

Other possible combinations but not limited too:

Router.add('/games/{gameName}/:level:/', this._method1, this);
Router.add('/{category}/blog/', this._method2, this);
Router.add('/home/?', this._method3, this);
Router.add('/about/*', this._method4, this);

addDefault
(
  • callback
  • callbackScope
)
public static

Defined in ts/service/Router.ts:319

The Router.addDefault method is meant to trigger a callback function if there are no route matches are found.

Parameters:

Example:

Router.addDefault(this._noRoutesFoundHandler, this);

buildRoute
(
  • ...rest
)
String public static

Defined in ts/service/Router.ts:572

A simple helper method to create a url route from an unlimited number of arguments.

Parameters:

  • ...rest ...rest

Returns:

String:

Example:

 const someProperty = 'api/endpoint';
 const queryObject = {type: 'car', name: encodeURIComponent('Telsa Motors')};

 Router.buildRoute(someProperty, 'path', 7, queryObject);

 //Creates 'api/endpoint/path/7?type=car&name=Telsa%20Motors'

clear () public static

Defined in ts/service/Router.ts:539

The Router.clear will remove all route's and the default route from the Router class.

Example:

Router.clear();

destroy () public static

Defined in ts/service/Router.ts:555

The Router.destroy method will null out all references to other objects in the Router class.

Example:

Router.destroy();

disable () public static

Defined in ts/service/Router.ts:397

The Router.disable method will stop the Router class from listening for the hashchange event.

Example:

Router.disable();

enable () public static

Defined in ts/service/Router.ts:367

The Router.enable method will allow the Router class to listen for the hashchange event. By default the Router class is enabled.

Example:

Router.enable();

getCurrentRoute () public static

Defined in ts/service/Router.ts:613

Returns the current router event that was last triggered.

Example:

 Router.getCurrentRoute();

getHash () String public static

Defined in ts/service/Router.ts:349

Gets the current hash url minus the # or #! symbol(s).

Returns:

String:

Returns current hash url minus the # or #! symbol(s).

Example:

let str = Router.getHash();

navigateTo
(
  • route
  • [silent=false]
  • [disableHistory=false]
)
public static

Defined in ts/service/Router.ts:453

The Router.navigateTo method allows you to change the hash url and to trigger a route that matches the string value. The second parameter is silent and is false by default. This allows you to update the hash url without causing a route callback to be executed.

Parameters:

Example:

// This will update the hash url and trigger the matching route.
Router.navigateTo('/games/asteroids/2/');

// This will update the hash url but will not trigger the matching route.
Router.navigateTo('/games/asteroids/2/', true);

// This will not update the hash url but will trigger the matching route.
Router.navigateTo('/games/asteroids/2/', true, true);

remove
(
  • routePattern
  • callback
  • callbackScope
)
public static

Defined in ts/service/Router.ts:289

The Router.remove method will remove one of the added routes.

Parameters:

  • routePattern String

    Must be the same string pattern you pasted into the add method.

  • callback Function

    Must be the same function you pasted into the add method.

  • callbackScope Any

    Must be the same scope off the callback pattern you pasted into the add method.

Example:

// Example of adding a route listener.
Router.add('/games/{gameName}/:level:/', this._method, this);

// Example of removing the same added route listener above.
Router.remove('/games/{gameName}/:level:/', this._method, this);

removeDefault () public static

Defined in ts/service/Router.ts:335

The Router.removeDefault method will remove the default callback that was added by the Router.addDefault method.

Example:

Router.removeDefault();

start () public static

Defined in ts/service/Router.ts:427

The Router.start method is meant to trigger or check the hash url on page load. Either you can call this method after you add all your routers or after all data is loaded. It is recommend you only call this once per page or application instantiation.

Example:

// Example of adding routes and calling the start method.
Router.add('/games/{gameName}/:level:/', this._method1, this);
Router.add('/{category}/blog/', this._method2, this);

Router.start();

validate
(
  • func
)
public static

Defined in ts/service/Router.ts:627

TODO: YUIDoc_comment

Parameters:

  • func Function

    The function you wanted called if the validation failed.

Example:

    Router.validate((routerEvent, next) => {
         const allowRouteChange = this._someMethodCheck();

         if (allowRouteChange == false) {
             next(() => {
                 // Do something here.
                 // For example you can call Router.navigateTo to change the route.
             });
         } else {
             next();
         }
    });

There are no methods that match your current filter settings. You can change your filter settings in the index section on this page. index