# Routes

## Introduction <a href="#introduction" id="introduction"></a>

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

WIP

### Defaults <a href="#defaults" id="defaults"></a>

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 <a href="#requirements" id="requirements"></a>

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.

> **Important**: Default values must also match these requirements.

### Metadata <a href="#metadata" id="metadata"></a>

WIP


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elentra.org/ejs/1.0/guide/routing/routes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.