named-routes.md

Named Routes

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 %}

// 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
• getCurrentRoutedURL() - Gives you the complete routed URL pattern that matched the route
• getCurrentRoutedNamespace() - Gives you the current routed namespace, if any