Routing Deep-Dive: Resources, Nested Callbacks, and Route Model Binding

[bpamiri]

There's a block of code you write the same way in every resourceful controller: findByKey the record, check it isn't null, 404 if it is. Three lines, four times (show/edit/update/delete), in every controller. The findByKey is mechanical. The not-found check is the part everyone forgets — and the day you forget it, /posts/999999 hands a visitor a stack trace instead of a 404.

This post is a complete tour of the Wheels 4.0 routing surface, ending with the feature that takes that boilerplate off your plate.

Read: https://blog.wheels.dev/posts/routing-resources-model-binding

What it covers

resources() — the seven RESTful routes (index/new/create/show/edit/update/delete) from a single call, each as a named route, materialized at end(). The detail people miss: update registers TWO routes — a PATCH and a PUT — both pointing at the update action. only/except filter the set, but a typo in them only throws in development; production silently drops the unknown name.

Nested resources — the opposite-behavior trap. Passing a callback auto-enables nesting and auto-calls end() for you — you do NOT add your own. The manual nested=true form suppresses the auto-end(), so you MUST call .end() yourself. They're mirror images, and mixing them (callback + manual end) leaves an extra end() that pops an empty scope stack and throws Wheels.InvalidRoute. The post has the table.

Named routes, root, wildcard. Why to="sessions##new" needs the ## escape (a literal # is an expression delimiter in CFML strings). Why root() and wildcard() are GET-only by default. And why route order is load-bearing: the dispatcher scans routes in registration order and stops at the first match — so wildcard() goes LAST or it shadows everything below it. (Fun wrinkle: the shipped config/routes.cfm puts wildcard before root — that's fine because wildcard doesn't match /, but any named route you add by hand has to go above the wildcard line.)

Route model binding — the headline feature. binding=true on a resource resolves params.post into a real model instance, and 404s a missing record, before the controller is even instantiated. The action body drops to the part that's actually yours. The post covers:

• Convention (binding=true → params.post) vs explicit (binding="Author" → params.author)
• How binding cascades down a .scope(path="/api", binding=true) — every nested resource is bound without binding appearing on its own line
• The global set(routeModelBinding=true) switch, and how per-route binding overrides it in both directions (including binding=false to opt out)
• Exactly how a miss behaves: a missing record always 404s, but Wheels.RecordNotFound is only THROWN in development — production sets 404 and renders the missing-template page. Don't try/catch for the typed exception in prod.
• The subtler divergence: a missing model class is silently skipped + negative-cached under convention binding, but RE-THROWS under explicit binding (it's treated as a config error).

The protected-action-names trap. You cannot name a controller action after any public framework helper — model, redirectTo, linkTo, env, the is* request predicates, the flash helpers. The framework builds the protected list from live component metadata (across wheels.Global, wheels.controller.*, and wheels.view.*) at app start; a matching action name throws Wheels.ActionNotAllowed (→ 404) and never dispatches. The seven standard REST names are safe because none of them are helpers.

Discuss

• Are you using route model binding per-resource, or did you flip the global set(routeModelBinding=true) switch app-wide? Where did the convention-vs-explicit divergence catch you?
• Callback nesting or manual nested=true — which form do you reach for, and why?
• Ever been bitten by the protected-action-names 404? What was the action name?

Every claim in the post is grounded in the 4.0 source, with a full worked config/routes.cfm you can lift directly. Feedback and war stories welcome in this thread.