Routing

ColdBox supports a Routing Service that will provide you with robust URL mappings for building expressive applications and RESTFul services. By convention URL routing will allow you to create URL's without using verbose parameter delimiters like ?event=this.that&m1=val and execute ColdBox events.

// Old Style
http://localhost/index.cfm?event=home.about&page=2
http://localhost/index.cfm?city=24&page=3&county=234324324

// New Routing Style
http://localhost/home/about/page/2
http://localhost/dade/miami/page/3

If you are leveraging CommandBox as your server, then full URL rewrites are enabled by default. This means you do not need a web server to remove the index.cfm from the URL.

What is a route?

A route is a declared URL pattern that if matched it will translate the URL into one of the following:

A ColdBox event to execute
A View/Layout to render
A Reponse function to execute
A Redirection to occur

It will also inspect the URL for placeholders and translate them into the incoming Request Collection variables (RC).

Examples

config/Router.cfc

function configure(){

    // Routing with placeholders to an event with placeholders
    route( "/blog/:year-numeric{4}/:month?/:day?" )
        .to( "blog.list" );

    // Redirects
    route( "/old/book" )
        .toRedirect( "/mybook" );

    // Responses
    route( "/echo" ).toResponse( (event,rc,prc) => {
        return "hello luis";
    } );

    // Shortcut to above
    route( "/echo", (event,rc,prc) => {
        return "hello luis";
    } );

    // Show view
    route( "/contact-us" )
        .toView( "main/contact" );

    // Direct to handler with action from URL
    route( "/users/:action" )
        .toHandler( "users" );

    // Inline pattern + target and name
    route( pattern="/wiki/:page", target="wiki.show", name="wikipage" );

}

Routing Benefits

There are several benefits that you will get by using our routing system:

Complete control of how URL's are built and managed
Ability to create or build URLs' dynamically
Technology hiding
Greater application portability
URL's are more descriptive and easier to remember

Route Visualizer

box install route-visualizer

Last updated 5 years ago

Was this helpful?

What is a route?

A route is a declared URL pattern that if matched it will translate the URL into one of the following:

A ColdBox event to execute

A View/Layout to render

A Reponse function to execute

A Redirection to occur

It will also inspect the URL for placeholders and translate them into the incoming Request Collection variables (RC).

Examples

config/Router.cfc

function configure(){

    // Routing with placeholders to an event with placeholders
    route( "/blog/:year-numeric{4}/:month?/:day?" )
        .to( "blog.list" );

    // Redirects
    route( "/old/book" )
        .toRedirect( "/mybook" );

    // Responses
    route( "/echo" ).toResponse( (event,rc,prc) => {
        return "hello luis";
    } );

    // Shortcut to above
    route( "/echo", (event,rc,prc) => {
        return "hello luis";
    } );

    // Show view
    route( "/contact-us" )
        .toView( "main/contact" );

    // Direct to handler with action from URL
    route( "/users/:action" )
        .toHandler( "users" );

    // Inline pattern + target and name
    route( pattern="/wiki/:page", target="wiki.show", name="wikipage" );

}