Bitsmist Frameworks
Docs » RouteOrganizer

RouteOrganizer

Inherit:Organizer

Overview

RouteOrganizer handles the application routings. It can be used to do route-specific jobs.

Determining the route

The RouteOrganizer references routes setting that describes what routes exist in the “routes” section of the component settings. This route setting and the current URL are used to determine the current route. Below is example settings:

"routes": [
  {
    "name": "list",
    "path": "/:resource/list/",
    "specName": "{{:resource}}",
  },
  {
    "name": "top",
    "path": "/",
    "specName": "top",
  }
]

The current route is determined by checking through each route settings whether it matches the following rules. The first matched one is adopted as the current route.

  1. Matches origin (if an origin is specified)
  2. Matches path (if a path is specified)

Spec File

The RouteOrganizer can load an additional settings file specific to the current route. This additional settings file is called a spec file. The settings format in the spec file is as same as the usual component settings.

Changing the Route

Transfer to the new route by calling openRoute() method. openRoute() process as the following:

  1. Transfers to a new route with a page load when options[“jump”] is True or new route information is not specified.
  2. Call history.pushState() and adds a new URL to the browser's history. (optional)
  3. Call updateRoute() method when a new route requires a different spec file. (not implemented yet)
  4. Validate a URL.
  5. Call attaching component's refresh() method.
  6. Normalize URL.

Currently, since updateRoute() method is not working, it causes a page load when the spec file is different. It will be transferred to the new route without a page load in the future.

When a page load occurs, openRoute() method is called automatically for the new URL and URL validation and beyond will be performed.

Popstate Handling

The RouteOrganizer handles popstate events triggered by such as pressing the forward/back button.

When an event occurs, openRoute() method is called for the new route just like the normal loading process. Also, since the “beforePopstate” and “afterPopstate” events are triggered for attaching components, it is possible to do your own processes by writing event handlers on the component.

URL Validation and Correction

RouteOrganizer has a mechanism for URL validation and modification. However, RouteOrganizer does not perform any specific work, but only triggers events. Describes the logic for validation and modification in the event handlers.

This is done by calling the validateRoute() method, which is automatically called in the openRoute() method.

validateRoute() performs the following flow.

  1. Triggers beforeValidate event.
  2. Triggers doCheckValidity organizer event.
  3. Fix the URL if validation failed and “settings.autoFixURL” option is True/
  4. Triggers ValidateURL event.
  5. Triggers afterValidate event.
  6. Throws an error when validation still fails.

Organizing

The RouteOrganizer loads route settings from the “routes” section and add them to the current route settings. These processes are done in beforeStart and afterSpecLoad timings.

Sections

  • routes

Timings

  • beforeStart
  • afterSpecLoad

Settings (Global)

Format:

{
    "system": {
        "specPath": <specPath>,
    }
}

specPath

Type:String

Specify a spec file path.

Settings

The routing settings are placed in the “routes” section. The “routes” section is an array, allowing multiple routes to be configured. Some settings are also placed in the “settings” section.

Format:

{
    "settings": {
        "autoFixURL": <autoFixURL>,
        "validationName": <validationName>,
    },
    "routes": [{
        "name": <name>,
        "origin": <origin>,
        "path": <path>,
        "specName": <specName>,
    }],
}

autoFixURL

Type:Boolean

Whether to fix the URL automatically when URL validation failed.

name

Type:String

A name of the route.

origin

Type:String

An origin of the route.

path

Type:String

A path of the route with regular expressions that can be used with path-to-regexp. When not specified, all URLs match.

specName

Type:String

A name of the spec file for the route. The spec file of the matched route will be loaded.

validationName

Type:String

A validation pattern name to use when validating the URL.

Tag Attributes

Some settings can be specified in tag attributes. Tag attributes have higher priority than settings.

bm-specpath

Type:String

A path to the spec file. Same as "system.specPath".

Events

afterNormalizeURL

Triggered after doNormallizeURL event.

Parameters

None

afterPopstate

Triggered in popstate handling, after the router calls openRoute() method and redraw.

Parameters

None

afterSpecLoad

Triggered right after a spec file is loaded.

Parameters

ParamterTypeDescription
specObjectSpec file JSON contents converted to an object.

afterValidate

Triggered after doValidate event.

Parameters

None

beforeNormalizeURL

Triggered when normalizeURL() method is called.

Parameters

None

beforePopstate

Triggered in popstate handling, before the router calls openRoute() method to redraw.

Parameters

None

beforeValidate

Triggered when validateRoute() method is called.

Parameters

None

doNormalizeURL

Triggered after beforeNormalizeURL event.

Parameters

None

doValidateURL

Triggered after auto fixation of the URL when validating.

Parameters

None

Extended Properties

routeInfo

Type:Object Inject:component get

Returns an object that holds information about the current route.

ItemTypeDescription
nameStringA name of the route.
specNameStringA spec file name of the route.
componentNameStringA main component name of the route.
urlStringThe current URL.
pathStringThe path of the current URL. It doesn't contain a hostname or query parameters.
queryStringThe query part of the current URL.
parsedUrlObjectA URL class created from the current URL.
routeParametersObjectAn object that holds path parameters. E.g. If a path in a route setting is ”/:person” and accessed to ”https://example.com/john”, then the object is {“person”:“John”}.
queryParametersObjectURL query parameters converted to an object.

spec

Type:Object Inject:component get

Returns an object that holds settings specific to the current route. That is spec file JSON contents converted to an object.

Extended Methods

jumpRoute(routeInfo, options)

Type:undefined Inject:component

Trasfers to a route according to the route information passed to the parameter. It causes a page load.

Parameters

ParameterTypeDescription
routeInfoObjectA route information of the destination.
optionsObjectOptions.

Return Value

undefined

loadParameters()

Type:Object Inject:component

Creates an object from the current URL query.

E.g. If a URL query is “?limit=10&offset=30” then the object returned is:

{
  "limit": 10,
  "offset": 30
}

Return Value

A query parameter object.

normalizeRoute(url)

Type:undefined Asynchronous Inject:component

Normalizes a URL passed to the parameter. This method only triggers events and the actual process is done by event handlers triggered.

Parameters

ParameterTypeDescription
urlStringA URL to normalize.

Return Value

undefined

Event

  • beforeNormalizeURL
  • doNormalizeURL
  • afterNormalizeURL

openRoute(routeInfo, options)

Type:undefined Asynchronous Inject:component

Transfers to a route according to the route information passed to the parameter. One of jumpRoute (), updateRoute (), refreshRoute () is called based on the route information passed and the current route information.

If the “name” of the current route information and the destination is different, jumpRoute () is called, if the “specName” is different, updateRoute () is called, and if both are the same, refreshRoute () is called.

Parameters

ParameterTypeDescription
routeInfoObjectA route information of the destination.
optionsObjectOptions for the transition. It has the following keys:
“pushState”
default:True
BooleanWhether to pushState () the new route. pushState() will add a destination URL to your browser history.
“jump”BooleanWhether to trigger a page load when trasferring to the destination route. Triggers a page load when set to True.

Return Value

undefined

refreshRoute(routeInfo, options)

Type:undefined Asynchronous Inject:component

Redraws the current route by calling attaching component's refresh() method.

Parameters

ParameterTypeDescription
routeInfoObjectRoute information to redraw. Currently unused.
optionsObjectOptions. It will be passed to refresh() method.

Return Value

undefined

replaceRoute(routeInfo)

Type:undefined Inject:component

Overwrites the route according to the route information passed to the parameter. Replaces the current URL without leaving the browser history.

Parameters

ParameterTypeDescription
routeInfoObjectA route information of the destination.

Return Value

undefined

switchSpec(specName)

Type:undefined Asynchronous Inject:component

Loads another spec file and switches to it.

Parameters

ParameterTypeDescription
specNameStringA spec name. This name + the extention “.js” is the file name to load.

Return Value

undefined

Referencing Settings

  • system.specPath

updateRoute(routeInfo, options)

Inject:component

It transfers to the route according to the route information passed to the parameter without causing page load.

Parameters

ParameterTypeDescription
routeInfoObjectA route information of the destination.
optionsObjectOptions.

validateRoute(url)

Type:undefined Asynchronous Inject:component

Validates the URL passed to the parameter. This method only triggers an event; the actual validation work is done in the event handler of the triggered events.

In the event handler, if the validation fails set this.validationResult[“result”] to false. If the validation fails and “settings.autoFix” is True, an attempt is made to automatically fix the URL. If the problem is not finally resolved, an exception is thrown.

Parameters

ParameterTypeDescription
urlStringA URL to validate.

Return Value

undefined

Events

  • beforeValidate
  • doValidate
  • afterValidate

Oraganizer Events

  • doCheckValidity

Referencing Settings

  • settings.validationName
  • settings.autoFixURL
Previous Next

© 2019-2023 Masaki Yasutake

Bitsmist Frameworks

Table of Contents

Table of Contents

  • RouteOrganizer
    • Overview
      • Determining the route
      • Spec File
      • Changing the Route
      • Popstate Handling
      • URL Validation and Correction
    • Organizing
    • Settings (Global)
      • specPath
    • Settings
      • autoFixURL
      • name
      • origin
      • path
      • specName
      • validationName
    • Tag Attributes
      • bm-specpath
    • Events
      • afterNormalizeURL
      • afterPopstate
      • afterSpecLoad
      • afterValidate
      • beforeNormalizeURL
      • beforePopstate
      • beforeValidate
      • doNormalizeURL
      • doValidateURL
    • Extended Properties
      • routeInfo
      • spec
    • Extended Methods
      • jumpRoute(routeInfo, options)
      • loadParameters()
      • normalizeRoute(url)
      • openRoute(routeInfo, options)
      • refreshRoute(routeInfo, options)
      • replaceRoute(routeInfo)
      • switchSpec(specName)
      • updateRoute(routeInfo, options)
      • validateRoute(url)

GENERAL

  • Overview
  • Installation

REFERENCE - COMPONENT

  • Router

REFERENCE - ORGANIZER

  • RouteOrganizer