wheels generate route

This command works correctly without options (parameters). Option support is under development and will be available soon.

Generate route definitions for your application.

Synopsis

wheels generate route [objectname] [options]
wheels g route [objectname] [options]

Description

The wheels generate route command helps you create route definitions in your Wheels application's /config/routes.cfm file. It can generate individual routes with different HTTP methods, RESTful resources, or root routes.

Arguments

| Argument | Description | Default | |----------|-------------|---------| | objectname | The name of the resource/route to add | Optional |

Options

| Option | Description | Default | |--------|-------------|---------| | get | Create a GET route (pattern,handler format) | | | post | Create a POST route (pattern,handler format) | | | put | Create a PUT route (pattern,handler format) | | | patch | Create a PATCH route (pattern,handler format) | | | delete | Create a DELETE route (pattern,handler format) | | | --resources | Create a resources route | false | | root | Create a root route with handler | |

Examples

Resources Route (default)

wheels generate route products

Generates in /config/routes.cfm:

.resources("products")

GET Route

wheels generate route get="/about,pages#about"

Generates:

.get(pattern="/about", to="pages#about")

POST Route

wheels generate route post="/contact,contact#send"

Generates:

.post(pattern="/contact", to="contact#send")

Root Route

wheels generate route root="pages#home"

Generates:

.root(to="pages#home")

RESTful Resource

wheels generate route products --resource

Generates:

<cfset resources("products")>

This creates all standard routes:

• GET /products (index)
• GET /products/new (new)
• POST /products (create)
• GET /products/:key (show)
• GET /products/:key/edit (edit)
• PUT/PATCH /products/:key (update)
• DELETE /products/:key (delete)

API Resource

wheels generate route products --api

Generates:

<cfset resources(name="products", nested=false, except="new,edit")>

Nested Resources

wheels generate route comments --resource nested="posts"

Generates:

<cfset resources("posts")>
    <cfset resources("comments")>
</cfset>

Creates routes like:

• /posts/:postKey/comments
• /posts/:postKey/comments/:key

Route Patterns

Dynamic Segments

wheels generate route "/users/[key]/profile" to="users#profile" name="userProfile"

Generates:

<cfset get(name="userProfile", pattern="/users/[key]/profile", to="users##profile")>

Optional Segments

wheels generate route "/blog/[year]/[month?]/[day?]" to="blog#archive" name="blogArchive"

Generates:

<cfset get(name="blogArchive", pattern="/blog/[year]/[month?]/[day?]", to="blog##archive")>

Wildcards

wheels generate route "/docs/*" to="documentation#show" name="docs"

Generates:

<cfset get(name="docs", pattern="/docs/*", to="documentation##show")>

Advanced Routing

With Constraints

wheels generate route "/users/[id]" to="users#show" constraints="id=[0-9]+"

Generates:

<cfset get(pattern="/users/[id]", to="users##show", constraints={id="[0-9]+"})>

Namespace Routes

wheels generate route users --resource namespace="admin"

Generates:

<cfset namespace("admin")>
    <cfset resources("users")>
</cfset>

Module Routes

wheels generate route dashboard --resource namespace="admin" module="backend"

Generates:

<cfset module("backend")>
    <cfset namespace("admin")>
        <cfset resources("dashboard")>
    </cfset>
</cfset>

Shallow Nesting

wheels generate route comments --resource nested="posts" --shallow

Generates:

<cfset resources("posts")>
    <cfset resources(name="comments", shallow=true)>
</cfset>

Custom Actions

Member Routes

wheels generate route "products/[key]/activate" to="products#activate" method="PUT" --member

Generates:

<cfset resources("products")>
    <cfset put(pattern="[key]/activate", to="products##activate", on="member")>
</cfset>

Collection Routes

wheels generate route "products/search" to="products#search" --collection

Generates:

<cfset resources("products")>
    <cfset get(pattern="search", to="products##search", on="collection")>
</cfset>

Route Files Organization

Main Routes File

/config/routes.cfm:

<!--- 
    Routes Configuration
    Define your application routes below
--->

<!--- Public routes --->
<cfset get(name="home", pattern="/", to="main##index")>
<cfset get(name="about", pattern="/about", to="pages##about")>
<cfset get(name="contact", pattern="/contact", to="pages##contact")>
<cfset post(name="sendContact", pattern="/contact", to="pages##sendContact")>

<!--- Authentication --->
<cfset get(name="login", pattern="/login", to="sessions##new")>
<cfset post(name="createSession", pattern="/login", to="sessions##create")>
<cfset delete(name="logout", pattern="/logout", to="sessions##delete")>

<!--- Resources --->
<cfset resources("products")>
<cfset resources("categories")>

<!--- API routes --->
<cfset namespace("api")>
    <cfset namespace("v1")>
        <cfset resources(name="products", nested=false, except="new,edit")>
        <cfset resources(name="users", nested=false, except="new,edit")>
    </cfset>
</cfset>

<!--- Admin routes --->
<cfset namespace("admin")>
    <cfset get(name="adminDashboard", pattern="/", to="dashboard##index")>
    <cfset resources("users")>
    <cfset resources("products")>
    <cfset resources("orders")>
</cfset>

<!--- Catch-all route --->
<cfset get(pattern="*", to="errors##notFound")>

Route Helpers

Generated routes create URL helpers:

Basic Helpers

<!--- For route: get(name="about", pattern="/about", to="pages##about") --->
#linkTo(route="about", text="About Us")#
#urlFor(route="about")#
#redirectTo(route="about")#

Resource Helpers

<!--- For route: resources("products") --->
#linkTo(route="products", text="All Products")# <!--- /products --->
#linkTo(route="product", key=product.id, text="View")# <!--- /products/123 --->
#linkTo(route="newProduct", text="Add Product")# <!--- /products/new --->
#linkTo(route="editProduct", key=product.id, text="Edit")# <!--- /products/123/edit --->

#urlFor(route="products")# <!--- /products --->
#urlFor(route="product", key=123)# <!--- /products/123 --->

Nested Resource Helpers

<!--- For nested resources("posts") > resources("comments") --->
#linkTo(route="postComments", postKey=post.id, text="Comments")# <!--- /posts/1/comments --->
#linkTo(route="postComment", postKey=post.id, key=comment.id, text="View")# <!--- /posts/1/comments/5 --->

Route Constraints

Pattern Constraints

wheels generate route "/posts/[year]/[month]" to="posts#archive" constraints="year=[0-9]{4},month=[0-9]{2}"

Format Constraints

wheels generate route "/api/users" to="api/users#index" format="json"

Generates:

<cfset get(pattern="/api/users", to="api/users##index", format="json")>

Route Testing

Generate Route Tests

wheels generate route products --resource
wheels generate test routes products

Route Test Example

component extends="wheels.Test" {
    
    function test_products_routes() {
        // Test index route
        result = $resolve(path="/products", method="GET");
        assert(result.controller == "products");
        assert(result.action == "index");
        
        // Test show route
        result = $resolve(path="/products/123", method="GET");
        assert(result.controller == "products");
        assert(result.action == "show");
        assert(result.params.key == "123");
        
        // Test create route
        result = $resolve(path="/products", method="POST");
        assert(result.controller == "products");
        assert(result.action == "create");
    }
    
}

Route Debugging

List All Routes

wheels routes list

Test Specific Route

wheels routes test "/products/123" --method=GET

Output:

Route resolved:
  Controller: products
  Action: show
  Params: {key: "123"}
  Name: product

Best Practices

1. Order matters: Place specific routes before generic ones
2. Use RESTful routes: Prefer resources() over individual routes
3. Name your routes: Always provide names for URL helpers
4. Group related routes: Use namespaces and modules
5. Add constraints: Validate dynamic segments
6. Document complex routes: Add comments explaining purpose
7. Test route resolution: Ensure routes work as expected

Common Patterns

Authentication Required

<!--- Public routes --->
<cfset get(name="home", pattern="/", to="main##index")>

<!--- Authenticated routes --->
<cfset namespace(name="authenticated", path="/app")>
    <!--- All routes here require authentication --->
    <cfset resources("projects")>
    <cfset resources("tasks")>
</cfset>

API Versioning

<cfset namespace("api")>
    <cfset namespace(name="v1", path="/v1")>
        <cfset resources(name="users", except="new,edit")>
    </cfset>
    <cfset namespace(name="v2", path="/v2")>
        <cfset resources(name="users", except="new,edit")>
    </cfset>
</cfset>

Subdomain Routing

<cfset subdomain("api")>
    <cfset resources("products")>
</cfset>

<cfset subdomain("admin")>
    <cfset resources("users")>
</cfset>

Redirect Routes

<cfset get(pattern="/old-about", redirect="/about")>
<cfset get(pattern="/products/category/[name]", redirect="/categories/[name]")>

Performance Considerations

1. Route caching: Routes are cached in production
2. Minimize regex: Complex patterns slow routing
3. Avoid wildcards: Be specific when possible
4. Order efficiently: Most-used routes first

Troubleshooting

Route Not Found

• Check route order
• Verify HTTP method
• Test with wheels routes test
• Check for typos in pattern

Naming Conflicts

• Ensure unique route names
• Check for duplicate patterns
• Use namespaces to avoid conflicts

Parameter Issues

• Verify parameter names match
• Check constraint patterns
• Test with various inputs

See Also

• wheels scaffold - Generate complete CRUD with routes
• wheels generate controller - Generate controllers
• wheels generate resource - Generate RESTful resources
• wheels generate api-resource - Generate API resources