Wheels CFML MVC Framework

The 'Basics' section of Wheels provides task-oriented guides for the core components of a Wheels application. These guides follow the lifecycle of a request through the framework and cover the following areas:

• Routing: Defining resources, nested resources, namespaced routes, custom patterns, and using route helpers.
• Controllers and Actions: Writing controllers, implementing the seven REST actions, using filters, handling params, rendering, redirecting, and using flash messages.
• Views, Layouts, and Partials: Rendering templates, using the default layout, extracting partials, and understanding how controller data is passed to views.
• Forms and Form Helpers: Using object-bound and tag-style form helpers, including data-auto-id for stable test selectors.
• Validation and Error Display: Using built-in validations, understanding when they fire, using the errors API, and rendering errors inline.
• Models and the ORM: Defining models, using finders, managing persistence, and implementing lifecycle callbacks.
• Associations: Modeling relationships using hasMany, belongsTo, hasOne, nested creation, eager loading, and cascade deletes.
• Migrations: Writing and running schema migrations, including column types, indexes, foreign keys, and rollbacks.
• Seeding: Idempotently populating development and production databases with default records.
• Query Builder and Scopes: Using the chainable query builder, defining reusable scopes, declaring enums, and performing batch processing.
• Database and Multiple Datasources: Configuring default datasources, overriding datasources per model, using transactions, and executing raw queries.
• Shared Development Databases: Managing migration tracking tables when multiple developers share a single development database.

The 'Digging Deeper' section provides task-oriented guides for implementing advanced features in Wheels that go beyond the core MVC (Model-View-Controller) pattern. These guides are designed as how-to manuals for specific implementation tasks rather than pure API references.

Key advanced topics covered include:

• Security & Access: Authentication patterns (Session, JWT, API tokens), Authorization & Filters (access control, role rules, policies), and CORS configuration.
• Asynchronous & Real-time: Background Jobs (queues, retries, priorities) and Server-Sent Events (SSE) for streaming updates.
• Data & Storage: Caching (action, fragment, view, and query caching), File Uploads & Downloads, and unified Storage (Local and S3 via named disks).
• Application Architecture: Multi-tenancy (tenant isolation via TenantResolver), Packages (first-party and custom packages), and Dependency Injection (DI) patterns.
• Developer Experience: The built-in Debug Panel, Route Model Binding, and overriding core framework methods.

Wheels is a web development framework for CFML designed to accelerate development by abstracting common web tasks. Its primary goals are:

• Simplicity: Wheels prioritizes developer simplicity over "pure" object-oriented patterns. It uses data-centric OOP, returns query result sets by default for multiple records, and uses standard CFML code instead of XML. It is designed so you can always "drop out" of the framework and use standard CFML if necessary.
• Documentation: A core goal is providing complete, up-to-date documentation to make the framework accessible to both experienced and novice CFML developers.
• Convention Over Configuration: Wheels assumes default settings and patterns to minimize the need for manual configuration. You can often start programming without setting any configuration variables at all.
• Beautiful Code: The framework structure encourages code that is non-repetitive, easy to scan, and separates business logic from request handling.

This glossary provides definitions for key terms used throughout the Wheels framework. Key concepts include:

MVC & Controllers

• Action: A public method on a controller that handles a single request (reading params, calling models, and picking a response).
• beforeAction filter: A private controller method registered to run before an action, typically used for authentication or record loading.
• afterAction filter: A private controller method registered to run after an action, typically used for logging.
• Flash: A struct that survives exactly one redirect. Use flashInsert(key, value) or redirectTo(..., success="...") to write, and flash() to read on the subsequent request.
• Layout: The outer template (usually app/views/layout.cfm) that wraps views. Control via renderView(layout=...) in an action or usesLayout() in a controller.

ORM & Data

• ActiveRecord: The ORM pattern used by Wheels where one class represents a table and one instance represents a row.
• Association: Relationships between models (hasMany, belongsTo, hasOne) that generate dynamic methods for navigation.
• Callback: Lifecycle hooks on a model (e.g., beforeSave, afterCreate) registered in config().
• Finder: Read methods on a model like findAll, findOne, findByKey, exists, and count.
• Eager loading: Using include= in a finder to join associated tables and avoid N+1 query problems.
• Primary key: The identity column, defaulting to id. Can be changed via setPrimaryKey().

Routing & Middleware

• Middleware: A (request, next) function in the dispatch chain that runs before controller instantiation (e.g., for CORS or rate limiting).
• Mapper: The fluent mapper() chain in config/routes.cfm used to declare routes and resources.
• Resource: A .resources("name") call that generates seven standard REST routes (index, new, create, show, edit, update, delete).
• Named route: A route with a name argument, allowing helpers like linkTo or urlFor to look up URLs by name instead of string.
• Route model binding: Automatically loading a model instance from the database based on params.<singular> during the dispatch stage.

Background Jobs & Migrations

• Job: A CFC in app/jobs/ extending wheels.Job that implements perform(struct data).
• Backoff: The exponential delay between retries for failed jobs: Min(baseDelay * 2^attempt, maxDelay).
• Migration: A versioned CFC in app/migrator/migrations/ with up() and down() methods for schema changes.
• createTable: A migration method that returns a table-builder; column methods are chained until .create() is called.
• references(): A migration shortcut that adds a <name>Id integer column and a foreign-key constraint.

Dependency Injection & Packages

• DI container: The service container in config/services.cfm used to map names to components.
• Auto-wiring: The DI container's fallback where it automatically resolves and injects parameters in a component's init() if they match other registered names.
• inject(): A declarative call in a controller's config() to resolve and assign services to this.<name>.
• Package: A standalone module installed into vendor/<name>/ and discovered by PackageLoader at startup.
• package.json: The manifest for packages containing name, version, provides.mixins, provides.middleware, and dependency fields (requires, replaces, suggests).

A Wheels 4 application follows a standardized directory structure. Understanding this layout is essential for knowing where to place application code, configuration, and static assets.

Core Directory Map

• app/: Contains all your application logic.
  • controllers/: Controllers (plural PascalCase, e.g., Users.cfc).
  • models/: Models (singular PascalCase, e.g., User.cfc).
  • views/: One folder per controller, plus layout.cfm.
  • events/: Lifecycle hooks for application/requests.
  • global/: User-defined global functions.
  • jobs/: Background jobs (must extend wheels.Job).
  • middleware/: Custom middleware components.
  • migrator/migrations/: Database migration CFCs.
  • snippets/: Scaffolded snippet templates.
• config/: Application configuration loaded at startup.
  • settings.cfm: Datasource, reload password, URL rewriting, etc.
  • routes.cfm: Route definitions using mapper() ... .end().
  • environment.cfm: Current deployment environment.
  • app.cfm: Application.cfc-level settings (e.g., this.name, mappings).
  • <environment>/: Per-environment overrides (e.g., production/settings.cfm).
• public/: THE WEB ROOT. This is the only folder accessible via a browser.
  • Application.cfc: Bootstraps the app, defines mappings, and loads .env.
  • index.cfm: The single entry point that hands requests to the dispatcher.
  • urlrewrite.xml: Rewrite rules for Tuckey (used by CommandBox/wheels CLI).
  • stylesheets/, javascripts/, images/, files/, miscellaneous/: Static assets.
• vendor/: Third-party code and the framework itself. Do not edit files here.
  • wheels/: The Wheels framework.
  • <package>/: Installed packages (e.g., wheels-sentry).
• tests/: Your test suite.
  • specs/: Model, controller, functional, view, integration, and browser specs.
  • populate.cfm: Optional test-data seeding.
• db/: SQLite database files (if using SQLite).
• .env: Environment variables (copy from env.example; do not commit).
• box.json / server.json: CommandBox metadata files.