# 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**

```javascript
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**

```javascript
// 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**

```javascript
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`.

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

### 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.

{% hint style="warning" %}
Default values must also match these requirements.
{% endhint %}

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

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.

{% hint style="warning" %}
This example is only hypothetical.  Adding a `permission` property (or any property) to a route's metadata has no effect at this time.
{% endhint %}

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


---

# 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.1/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.