Routes

Introduction

A route is an object that maps a path to a controller. The router will attempt to match the path in the address bar to a previously defined route. If the router finds a match, it passes the logical controller to the Kernel where the appropriate class is resolved and loaded, and the controller method executed. If the controller returns a component, the application will insert it into the layout.

Routes are also assigned a name. A route's name may be used to generate a path instead of hard-coding; this allows us to change an existing URL without breaking any links in the application.

Class Synopsis

class Route
{
    constructor(name, pattern, defaults = {}, requirements = {}, metadata = {});

    getName() : string;
    getPattern() : string;
    getDefaults() : Object;
    getRequirements() : Object;
    getMeta() : Object;

    getCollection() : RouteCollection|null;
    setCollection(RouteCollection);
}

Example: Define a named route for URL #/sandbox/index

// With standard notation of logical controller
new Route('sandbox.index', '/sandbox/index', {
    _controller: 'Sandbox.SandboxController.indexAction'
});

// With short-hand notation of logical controller
new Route('sandbox.index', '/sandbox/index', {
    _controller: 'Sandbox.Sandbox.index'
});

// Simple route definition
new Route('sandbox.index', '/sandbox/index', 'Sandbox.Sandbox.index');

Advanced Routing

Example

new Route(
    'sandbox.foo',
    '/foo/{someId}/{fooParam}/{barParam}', {
        _controller: 'Sandbox.Sandbox.foo',
        someId: 1,
        fooParam: 'FOODEFAULT',
        barParam: 'bardefault'
    }, {
        someId: /\d+/,        // must be an integer
        fooParam: /[A-Z]+/,   // must be an uppercase string
        barParam: /[a-z]+/    // must be a lowercase string
    }, {
        metaFoo: 'metaBar'
    }
);

Parameters

A route parameter is a variable embedded into the route's pattern which allows a route to be matched dynamically against many different paths. These variables must match in the position specified in the route pattern and their values must match the associated requirement. Once matched, the parameter values are included in the compiled route that is returned.

The most common use case for parameters is capturing entity identifiers.

Example

In this example, the user's ID matches any integer and is returned to the application so it can load the correct profile. A path that would match this route is /user/profile/37.

new Route('user.profile', '/user/profile/{userId}', {
    _controller: 'User.Profile.index',
}, {
    userId: /\d+/,    // must be an integer
});

Defaults

Each route accepts a defaults object as an argument to allow default parameter values to be specified. When generating a path, any missing parameters will fallback to these defaults.

The defaults object may also include the special _controller property that contains the logical controller string that is used to link the route to a specific part of the system.

Requirements

Each route must also include a requirements object with a regular expression for each of the route's parameters. Only parameter values that match these requirements will match the route.

Default values must also match these requirements.

Metadata

The metadata argument allows arbitrary data to be assigned to a route for use at runtime. Individual applications may define a set of properties and supported values which may influence how a route is processed once matched.

Example

In this example, we specify the name of a permission that the user must have to access this route. When the route matches, an application could verify that the authenticated user has this permission and only execute the controller if successful.

This example is only hypothetical. Adding a permission property (or any property) to a route's metadata has no effect at this time.

new Route('sandbox.meta', '/meta', { _controller: 'Sandbox.Sandbox.meta' }, {}, {
    permission: 'sandbox.access'
});