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

If you do not pass the name argument to the route() method, we will use the pattern as the name of the route.

// 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).

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:

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:

<!-- 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

// 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" ) ) {
    // ...
}