The last lesson ended with a gap: vanilla CFML has no built-in router, no automatic Controller dispatch, and no view() helper. ColdBox, built and maintained by Ortus Solutions, is the most widely used answer to that gap in the ColdFusion ecosystem, a full convention-based HMVC (Hierarchical MVC) framework with several other pieces built in.
Learning Objectives
After completing this lesson, you'll be able to:
- Describe what ColdBox actually provides beyond the MVC pattern itself.
- Recognize ColdBox's standard folder structure and naming conventions.
- Know ColdBox's three core pillars: WireBox, CacheBox, and LogBox.
- Know how a ColdBox app is scaffolded and run with CommandBox.
How a Request Flows Through ColdBox
URL or Form Submission
e.g. index.cfm?event=users.list
Router Resolves the Event
maps it to a handler action
Handler Calls a Service
the Model layer, via WireBox DI
View Renders the Response
matching .cfm in the views folder
Conventions Over Configuration
ColdBox's core idea is that following its naming conventions means most of the wiring from the previous lesson's "real gap" is handled for you. A handler's action method and a view file are connected automatically by naming them to match, rather than registering each route by hand.
| Folder | Holds |
|---|---|
| handlers/ | Handler CFCs, ColdBox's name for Controllers, each public function is an action |
| views/ | .cfm templates, matched to a handler/action by naming convention |
| models/ | Services, DAOs, and other Model-layer CFCs |
| config/ | Router.cfc (URL routing) and Coldbox.cfc (app-wide settings) |
| modules_app/ | Self-contained ColdBox modules, reusable packaged functionality |
The Three Core Pillars
| Pillar | Does |
|---|---|
| WireBox | Dependency injection, so a handler can simply declare a property it needs rather than instantiating it manually, with built-in aspect-oriented programming support too |
| CacheBox | A caching framework with pluggable providers, conceptually similar to the cachePut()/cacheGet() built-ins from the Caching lesson, but framework-managed |
| LogBox | A structured logging framework with configurable appenders (file, console, database, and more) |
These three are what people mean when they say ColdBox is more than just a router, routing solves the dispatch problem from the previous lesson, WireBox/CacheBox/LogBox solve three more problems most real applications eventually need solved anyway.
A Real Detail: The "H" in HMVC
ColdBox describes itself as HMVC, Hierarchical MVC, specifically because of its module system. The modules_app/ folder from the table above isn't just a place for extra files, each module is a self-contained, nestable unit with its own handlers/views/models, interceptors, and config, that can be dropped into an application (or shared across several) as one package. That nesting is the "hierarchical" part, a module can itself be built from smaller modules. ColdBox has maintained this architecture since 2005, making it one of the longer-running frameworks in the CFML ecosystem.
| Plain MVC | HMVC (ColdBox) | |
|---|---|---|
| Structure | One flat set of Models, Views, and Controllers for the whole app | Nestable modules, each with its own Models, Views, and Controllers |
| Reuse across apps | Usually copy-paste between projects | A module is a self-contained package, installable via CommandBox the same way a library is |
| Scale as the app grows | Everything lives in one set of handlers/views/models, which can get large | New functionality can be added as a new module instead of growing the core app |
| The vanilla pattern from the previous lesson | This is exactly what Introduction to MVC covered | Builds on top of it, each module is its own small MVC, nested inside the larger app |
Scaffolding and Running a ColdBox App
ColdBox apps are created and run through CommandBox, covered in depth in its own upcoming lesson.
# scaffold a new ColdBox app coldbox create app myApp # generate a new handler coldbox create handler name=Users # run it server start
Common Beginner Mistakes
Treating ColdBox as just a routing layer
Routing (the handler/view dispatch) is only one piece. WireBox, CacheBox, and LogBox are core parts of what ColdBox actually provides, skipping them and wiring dependencies manually gives up most of the framework's value.
Fighting the folder/naming conventions instead of following them
ColdBox's conventions are what let a handler and its view connect automatically. Deviating from them without understanding why usually means more manual configuration, not less.
Confusing a ColdBox Handler with the generic term Controller from the previous lesson
They're the same concept, ColdBox's naming convention just calls them Handlers, with public functions inside them called actions.
Best Practices
- Let WireBox manage dependencies between Handlers and Models instead of instantiating components manually inside a handler.
- Keep business logic in Models/Services, Handlers should stay thin, matching the Controller discipline from the previous lesson.
- Reach for a ColdBox module when packaging reusable functionality, rather than copy-pasting code between applications.
Interview Questions
What does ColdBox actually add on top of the MVC pattern itself?
The routing and dispatch wiring between Model, View, and Controller (the gap from the previous lesson), plus dependency injection (WireBox), caching (CacheBox), and logging (LogBox) built in.
What's WireBox, and what problem does it solve?
ColdBox's dependency injection framework. Instead of a handler manually instantiating the Models/Services it depends on, it declares them as properties and WireBox supplies the actual instances.
What does ColdBox call a Controller, and what does it call its action methods?
A Handler, with each public function inside it called an action.
Summary
In this lesson, you saw what ColdBox actually provides beyond the MVC pattern: convention-based routing between Handlers and Views, and three core pillars, WireBox for dependency injection, CacheBox for caching, and LogBox for logging. You also saw how an app is scaffolded and run through CommandBox.
What's Next?
The next lesson covers FW/1, a lighter-weight alternative framework built around the same convention-over-configuration idea.