Return to v2.5.0 docs


Configuration Routing struct mapper

Create a route that matches a URL requiring an HTTP POST method. We recommend using this matcher to expose actions that create database records.

Name Type Required Default Description
name string No Camel-case name of route to reference when build links and form actions (e.g., blogPosts).
pattern string No Overrides the URL pattern that will match the route. The default value is a dasherized version of name (e.g., a name of blogPosts generates a pattern of blog-posts).
to string No Set controller##action combination to map the route to. You may use either this argument or a combination of controller and action.
controller string No Map the route to a given controller. This must be passed along with the action argument.
action string No Map the route to a given action within the controller. This must be passed along with the controller argument.
package string No Indicates a subfolder that the controller will be referenced from (but not added to the URL pattern). For example, if you set this to admin, the controller will be located at admin/YourController.cfc, but the URL path will not contain admin/.
on string No If this route is within a nested resource, you can set this argument to member or collection. A member route contains a reference to the resource's key, while a collection route does not.
redirect string No Redirect via 302 to this URL when this route is matched. Has precedence over controller/action. Use either an absolute link like /about/, or a full canonical link.

    // Route name:  widgets
    // Example URL: /sites/918/widgets
    // Controller:  Widgets
    // Action:      create
    .post(name="widgets", pattern="sites/[siteKey]/widgets", to="widgets##create")

    // Route name:  wadgets
    // Example URL: /wadgets
    // Controller:  Wadgets
    // Action:      create
    .post(name="wadgets", controller="wadgets", action="create")

    // Route name:  authenticate
    // Example URL: /oauth/token.json
    // Controller:  Tokens
    // Action:      create
    .post(name="authenticate", pattern="oauth/token.json", to="tokens##create")

    // Route name:  usersPreferences
    // Example URL: /preferences
    // Controller:  users.Preferences
    // Action:      create
    .post(name="preferences", to="preferences##create", package="users")

    // Route name:  extranetOrders
    // Example URL: /buy-now/orders
    // Controller:  extranet.Orders
    // Action:      create

    // Example scoping within a nested resource
    .resources(name="customers", nested=true)
        // Route name:  leadsCustomers
        // Example URL: /customers/leads
        // Controller:  Leads
        // Action:      create
        .post(name="leads", to="leads##create", on="collection")

        // Route name:  cancelCustomer
        // Example URL: /customers/3209/cancel
        // Controller:  Cancellations
        // Action:      create
        .post(name="cancel", to="cancellations##create", on="member")


Related Functions