> For the complete documentation index, see [llms.txt](https://coldbox.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coldbox.ortusbooks.com/the-basics/routing/routing-dsl/named-routes.md).

# Named Routes

Register named routes with the name argument or as() method and generate URLs to them later.

You can register routes in ColdBox with a human friendly name so you can reference them later for link generation and more.

### Registering Named Routes

You will do this in two forms:

1. Using the `route()` method and the `name` argument
2. Using the `as()` method

{% hint style="info" %}
If you do not pass the `name` argument to the `route()` method, we will use the `pattern` as the name of the route.
{% endhint %}

```java
// Using the pattern by convention
route( pattern="/healthcheck" ).to( "healthcheck" );

// Using the name argument
route( 
    pattern = "/users/list", 
    target = "users.index", 
    name = "usermanager" 
);

route( 
    pattern = "/user/:id/profile", 
    target = "users.show", 
    name = "userprofile"
);

// Using the as() method
route( "/users/:id/profile" )
  .as( "usersprofile" )
  .to( "users.show" )
```

### Generating URLs to Named Routes

You will generate URLs to named routes by leveraging the `route()` method in the request context object (**event**).

```javascript
route(
    // The name of the route
    required name,
    // The params to pass, can be a struct or array
    struct params={},
    // Force or un-force SSL, by default we keep the same protocol of the request
    boolean ssl
);
```

Let's say you register the following named routes:

```java
route( 
    pattern = "/users/list", 
    target = "users.index", 
    name = "usermanager" 
);

route( 
    pattern = "/user/:id/profile", 
    target = "users.show", 
    name = "userprofile"
);
```

Then we can create routing URLs to them easily with the `event.route()` method:

```markup
<!-- Named Route with no params -->
<a href="#event.route( 'usermanager' )#">Manage Users</a>

<!-- Named Route with struct params -->
<a href="#event.route( 'userprofile', { id = 3 } )#">View User</a>

<!-- Named Route with array params -->
<a href="#event.route( 'userprofile', [ 3 ] )#">View User</a>

<a href="#event.route( '/healthcheck' )#">Health check</a>
```

### **Inspecting The Current Route**

The request context object (**event**) also has some handy methods to tell you the name or even the current route that was selected for execution:

* `getCurrentRouteName()` - Gives you the name of the current route, if any
* `getCurrentRoute()` - Gives you the currently executed route
* `getCurrentRouteRecord()` - Gives you the currently executed route's full record/struct
* `getCurrentRouteMeta()` - Gives you the metadata struct assigned to the current route via the `meta()` modifier
* `getCurrentRoutedURL()` - Gives you the complete routed URL pattern that matched the route
* `getCurrentRoutedNamespace()` - Gives you the current routed namespace, if any
* `routeIs( name )` - Boolean check to verify if the passed name is the same as the current route's name
* `urlMatches( path, exact=false )` - Boolean check to test if the given `path` exists (or, when `exact` is `true`, matches exactly) within the currently routed URL
* `urlMatchesExact( path )` - Boolean check, shortcut to `urlMatches( path, true )`, to test if the given `path` matches the currently routed URL exactly

```javascript
// Was this the "usermanager" route?
if ( event.routeIs( "usermanager" ) ) {
    // do something route-specific
}

// Does the routed URL contain "users/list" anywhere in it?
if ( event.urlMatches( "users/list" ) ) {
    // ...
}

// Does the routed URL match "users/list" exactly?
if ( event.urlMatchesExact( "users/list" ) ) {
    // ...
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://coldbox.ortusbooks.com/the-basics/routing/routing-dsl/named-routes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.