This chapter will introduce you to frameworks in general and later specifically to Wheels. We'll help you decide if you even need a framework at all and what common problems a framework tries to solve. If we're able to convince you that using a framework is the right thing for you, then we'll present our goals with creating Wheels and show you some key Wheels concepts.

So let's get started.

Do I Really Need to Use a Framework?

Short answer, no. If you don't mind doing the same thing over and over again and are getting paid by the hour to do so, then by all means keep doing that.

Slightly longer answer, no. If you're working on a highly customized project that does not fall within what 9 out of 10 web sites/applications normally do then you likely need a high percentage of custom code, and a framework will not help much.

However, if you're like most of us and have noticed that for every new project you start on--or even every new feature you add to an existing project--you waste a lot of time re-creating the wheel, then you should read on because Wheels may just be the solution for you!

Wheels will make starting a new project or building a new feature quick and painless. You can get straight to solving business problems on day one! To understand how this is achieved, we figured that a little background info on frameworks in general may help you out.

All good frameworks rise from the need to solve real problems in real world situations. Wheels is based heavily on the Rails framework for Ruby and also gets inspiration from Django and, though to a lesser extent, other frameworks in the ColdFusion space (like Fusebox, for example). Over the years the contributors to these frameworks have identified problems and tedious tasks in their own development processes, built a solution for it, and abstracted (made it more generic so it suits any project) the solution into the framework in question. Piggy-backing on what all these great programmers have already created and adding a few nice solutions of our own, Wheels stands on solid ground.

OK, so that was the high level overview of what frameworks are meant to do. But let's get a little more specific.

Framework Goals in General

Most web development frameworks set out to address some or all of these common concerns:

• Map incoming requests to the code that handles them.

• Separate your business logic from your presentation code.

• Let you work at a higher level of abstraction, thus making you work faster.

• Give you a good code organization structure to follow.

Like all other good frameworks, Wheels does all this. But there are some subtle differences, and certain things are more important in Wheels than in other frameworks and vice versa. Let's have a look at the specific goals with Wheels so you can see how it relates to the overall goals of frameworks in general.

Our Goals With Wheels

As we've said before, Wheels is heavily based on Ruby on Rails, but it's not a direct port, and there are some things that have been changed to better fit the CFML language. Here's a brief overview of the goals we're striving for with Wheels (most of these will be covered in greater detail in later chapters):

Simplicity

We strive for simplicity on a lot of different levels in Wheels. We'll gladly trade code beauty in the framework's internal code for simplicity for the developers who will use it. This goal to keep things simple is evident in a lot of different areas in Wheels. Here are some of the most notable ones:

• The concept of object oriented programming is very simple and data-centric in Wheels, rather than 100% "pure" at all times.

• By default, you'll always get a query result set back when dealing with multiple records in Wheels, simply because that is the way we're all used to outputting data.

• Wheels encourages best practices, but it will never give you an error if you go against any of them.

• With Wheels, you won't program yourself into a corner. If worse comes to worse, you can always drop right out of the framework and go back to old school code for a while if necessary.

What this means is that you don't have to be a fantastic programmer to use the framework (although it doesn't hurt). It's enough if you're an average programmer. After using Wheels for a while, you'll probably find that you've become a better programmer though!

Documentation

If you've ever downloaded a piece of open source software, then you know that most projects lack documentation. Wheels hopes to change that. We're hoping that by putting together complete, up-to-date documentation that this framework will appeal, and be usable, by everyone. Even someone who has little ColdFusion programming background, let alone experience with frameworks.

Key Wheels Concepts

Besides what is already mentioned above, there are some key concepts in Wheels that makes sense to familiarize yourself with early on. If you don't feel that these concepts are to your liking, feel free to look for a different framework or stick to using no framework at all. Too often programmers choose a framework and spend weeks trying to bend it to do what they want to do rather than follow the framework conventions.

Speaking of conventions, this brings us to the first key concept:

Convention Over Configuration

Instead of having to set up tons of configuration variables, Wheels will just assume you want to do things a certain way by using default settings. In fact, you can start programming a Wheels application without setting any configuration variables at all!

If you find yourself constantly fighting the conventions, then that is a hint that you're not yet ready for Wheels or Wheels is not ready for you.

Beautiful Code

Beautiful (for lack of a better word) code is code that you can scan through and immediately see what it's meant to do. It's code that is never repeated anywhere else. And, most of all, it's code that you'll enjoy writing and will enjoy coming back to 6 months from now.

Sometimes the Wheels structure itself encourages beautiful code (separating business logic from request handling, for example). Sometimes it's just something that comes naturally after reading documentation, viewing other Wheels applications, and talking to other Wheels developers.

Model-View-Controller (MVC)

If you've investigated frameworks in the past, then you've probably heard this terminology before. Model-View-Controller, or MVC, is a way to structure your code so that it is broken down into three easy-to-manage pieces:

• Model: Just another name for the representation of data, usually a database table.

• View: What the user or their browser sees and interacts with (a web page in most cases).

• Controller: The behind-the-scenes guy that's coordinating everything.

"Uh, yeah. So what's this got to do with anything?" you may ask. MVC is how Wheels structures your code for you. As you start working with Wheels applications, you'll see that most of the code you write (database queries, forms, and data manipulation) are very nicely separated into one of these three categories.

The benefits of MVC are limitless, but one of the major ones is that you almost always know right where to go when something needs to change.

If you've added a column to the vehicles table in your database and need to give the user the ability to edit that field, all you need to change is your View. That's where the form is presented to the user for editing.

If you find yourself constantly getting a list of all the red cars in your inventory, you can add a new method to your model called getRedCars() that does all the work for you. Then when you want that list, just add a call to that method in your controller and you've got 'em!

Object Relational Mapping (ORM)

The Object Relational Mapping, or ORM, in Wheels is perhaps the one thing that could potentially speed up your development the most. An ORM handles mapping objects in memory to how they are stored in the database. It can replace a lot of your query writing with simple methods such as user.save(), blogPost.comments(order="date"), and so on. We'll talk a lot more about the ORM in Wheels in the chapters about models.

There's Your Explanation

So there you have it, a completely fair and unbiased introduction to Wheels. ;)

If you've been developing ColdFusion applications for a while, then we know this all seems hard to believe. But trust us; it works. And if you're new to ColdFusion or even web development in general, then you probably aren't aware of most of the pains that Wheels was meant to alleviate!

That's okay. You're welcome in the Wheels camp just the same.

Wheels uses a Docker-based development environment that provides consistent, containerized development with support for multiple CFML engines and databases.

Prerequisites

1. Docker: Install Docker Desktop from docker.com

2. Wheels CLI: Install the Wheels CommandBox module:

Setting up Docker Development Environment

Ensure you are in the application root directory.

Initialize your Docker development environment:

Command Options

cfengine options:

• lucee - Lucee CFML engine

• adobe - Adobe ColdFusion

• boxlang - BoxLang CFML engine

cfversion options:

• Major versions for Adobe ColdFusion: 2018, 2021, 2023, 2025

• Major versions for Lucee: 5, 6, 7

db options:

• mysql - MySQL database

• postgres - PostgreSQL database

• mssql - Microsoft SQL Server

Generated Files

The wheels docker init command creates several files in your project:

• .dockerignore - Specifies files to exclude from Docker build context

• Dockerfile - Container definition for your chosen CFML engine

• docker-compose.yml - Multi-container application definition

Starting Your Development Environment

After running the init command, start your containers:

The containers will take a few minutes to start the first time as Docker downloads the necessary images. Once started, your application will be available at:

• Default: http://localhost:8080

• Custom port: Check your server.json file for the configured port

Managing Your Docker Environment

Additional Configuration

Custom Ports

The default port is 8080, but you can customize this by modifying the server.json:

Database Configuration

The generated CFConfig.json file automatically configures a datasource for your chosen database. The configuration includes:

• Connection settings for your selected database type

• Default datasource named wheels-dev

• Appropriate drivers for the database engine

Development Workflow

1. Make code changes in your directory

2. Changes are reflected immediately due to Docker volume mounting

3. Database changes persist between container restarts

4. Use standard Wheels commands like migrations, generators, etc.

Troubleshooting

Containers won't start:

Database connection issues:

Performance issues:

• Ensure Docker Desktop has adequate memory allocated (4GB+ recommended)

• On Windows/Mac, enable file sharing for your project directory

By far the quickest way to get started with Wheels is via CommandBox. CommandBox brings a whole host of command line capabilities to the CFML developer. It allows you to write scripts that can be executed at the command line written entirely in CFML. It allows you to start a CFML server from any directory on your machine and wire up the code in that directory as the web root of the server. What's more is, those servers can be either Lucee servers or Adobe ColdFusion servers. You can even specify what version of each server to launch. Lastly, CommandBox is a package manager for CFML. That means you can take some CFML code and package it up into a module, host it on ForgeBox.io, and make it available to other CFML developers. In fact we make extensive use of these capabilities to distribute Wheels plugins and templates. More on that later.

One module that we have created is a module that extends CommandBox itself with commands and features specific to the Wheels framework. The Wheels CLI module for CommandBox is modeled after the Ruby on Rails CLI module and gives similar capabilities to the Wheels developer.

Install CommandBox

The first step is to get downloaded and running. CommandBox is available for Windows, Mac & Linux, and can be installed manually or using one of the respective package managers for each OS. You can use on Windows, on MacOS, or Yum/Apt on Linux depending on your flavor of Linux. Please follow the instructions on how to install CommandBox on your particular operating system. At the end of the installation process you want to make sure the box command is part of your system path so you can call the command from any directory on your system.

Once installed, you can either double-click on the box executable which opens the CommandBox shell window, or run box from a CMD window in Windows, Terminal window in MacOS, or shell prompt on a Linux server. Sometimes you only want to call a single CommandBox command and don't need to launch a whole CommandBox shell window to do that, for these instances you can call the CommandBox command directly from your default system terminal window by prefixing the command with the box prefix.

So to run the CommandBox version command you could run box version from the shell or you could launch the CommandBox shell and run version inside it.

This is a good concept to grasp, cause depending on your workflow, you may find it easier to do one versus the other. Most of the commands you will see in these CLI guides will assume that you are entering the command in the actual CommandBox shell so the box prefix is left off.

Install the wheels-cli CommandBox Module

Okay, now that we have CommandBox installed, let's add the Wheels CLI module.

Installing this module will add a number of commands to your default CommandBox installation. All of these commands are prefixed by the wheels name space. There are commands to create a brand new Wheels application or scaffold out sections of your application. We'll see some of these commands in action momentarily.

Start a new Application using the Wizard

To install a new application using version 3.0, we can use the new application wizard and select Bleeding Edge when prompted to select the template to use.

Start a New Application Using the Command Line

Now that we have CommandBox installed and extended it with the Wheels CLI module, let's start our first Wheels app from the command line. We'll look at the simplest method for creating a Wheels app and starting our development server.

A few minutes after submitting the above commands a new browser window should open up and display the default Wheels congratulations screen.

So what just happened? Since we only passed the application name myApp to the wheels generate app command, it used default values for most of its parameters and downloaded our Base template (wheels-base-template) from ForgeBox.io, then downloaded the framework core files (wheels.dev) from ForgeBox.io and placed it in the vendor/wheels directory, then configured the application name and reload password, and started a Lucee server on a random port.

This Getting Started guide has taken you from the very beginning and gotten you to the point where you can go into any empty directory on your local development machine and start a Wheels project by issuing a couple of CLI commands. In later guides we'll explore these options further and see what else the CLI can do for us.

Switch to a different environment in your Wheels application.

Synopsis

Description

The wheels env switch command changes the active environment for your Wheels application by updating the wheels_env variable in the .env file. It validates the environment configuration, optionally creates backups, and can restart the application server.

Arguments

Options

Examples

Switch to staging

Switch with application restart

Force switch without validation

Switch with backup

Quiet switch for scripts

Combine multiple options

What It Does

1. Validates Target Environment (if --check is enabled):

   • Checks for .env.[environment] file

   • Checks for config/[environment]/settings.cfm file

Output Example

Environment File Updates

.env File

The command updates or creates the wheels_env variable:

Before:

After:

If no environment variable exists, it adds:

Validation Process

The validation checks for required environment files:

1. Environment Configuration File:

   • Checks: .env.[environment]

   • Location: Project root

2. Wheels Settings File:

Validation Rules:

• Valid: Both files exist

• Valid with warning: One file exists

• Invalid: Neither file exists (unless --force is used)

Options Details

--check (default: true)

Validates the target environment before switching:

--backup (default: false)

Creates timestamped backups before switching:

--restart (default: false)

Automatically restarts the application:

--force (default: false)

Bypasses validation and confirmation prompts:

--quiet (default: false)

Minimal output for scripting:

Production Safety

When switching to production from another environment:

• Displays warning about production implications

• Requires confirmation (unless --force or --quiet)

• Shows warnings about debug mode, caching, and error handling

Warning message:

Error Handling

If the switch fails:

• Displays error message

• Provides troubleshooting suggestions

• Sets exit code 1 for scripting

Example error output:

Backup Files

The --backup option creates timestamped backup files:

Created Files:

• .env.backup-YYYYMMDD-HHMMSS - Backup of current .env file

• server.json.backup-YYYYMMDD-HHMMSS - Backup of server.json (if exists)

Manual Restore:

If you need to restore from a backup:

Service Management

With --restart Option

When using --restart, the command will:

1. If server.json exists:

   • Stop CommandBox server

   • Start CommandBox server

2. If server.json doesn't exist:

Manual Restart

If --restart is not used, you need to manually restart:

Environment-Specific Configuration

The command reads additional configuration from .env.[environment] files if they exist:

Supported Variables:

• database - Database connection name

• debug - Debug mode (true/false)

• cache - Cache configuration

Example .env.production:

Integration Examples

CI/CD Pipeline

Deployment Scripts

Automated Testing

Troubleshooting

Switch Failed

• Check validation errors in output

• Verify .env.[environment] file exists

• Verify config/[environment]/settings.cfm exists

• Use --force

Application Not Responding After Switch

• Ensure server was restarted

• Check .env file for correct wheels_env value

• Review application logs for errors

• Manually restart services if needed

Permission Issues

• Check write permissions for .env file

• Run with appropriate privileges

• Ensure backup directory is writable

Validation Warnings

• Warning appears if only one configuration file exists

• Environment may work but might not be fully configured

• Check both .env.[environment] and config/[environment]/settings.cfm

Best Practices

1. Always validate: Keep --check enabled for production switches

2. Create backups: Use --backup for critical environment changes

3. Test first: Switch in staging before production

Security Considerations

• Production switches require explicit confirmation

• Backup files contain sensitive configuration

• .env files should be in .gitignore

• Use --quiet

Notes

• The command modifies the .env file in place

• Creates wheels_env variable if it doesn't exist

• Falls back to updating environment variable if found

Exit Codes

• 0 - Success

• 1 - Failure (validation error, write error, or user cancellation)

See Also

• - Environment management overview

• - List available environments

• - Setup new environments

• - Show current environment

Run TestBox tests for your Wheels application using the TestBox CLI integration.

Note: This command replaces the deprecated wheels test command.

Prerequisites

Generate route definitions for your Wheels application's /config/routes.cfm file.

Synopsis

Description

The wheels generate route command helps you create route definitions in your Wheels application's /config/routes.cfm file. It supports individual HTTP method routes, RESTful resource routes, and root routes.

IMPORTANT: All HTTP method parameters must use the equals syntax: --get="pattern,handler" not --get pattern,handler

Parameter Syntax

CommandBox supports multiple parameter formats:

• Named parameters: name=value (e.g., objectname=products, get="pattern,handler")

• Flag parameters: --flag equals flag=true (e.g., --resources equals resources=true)

Note: Flag syntax (--flag) avoids positional/named parameter conflicts and is recommended for boolean options.

Arguments

Options

Examples

Resources Route (default)

Generates in /config/routes.cfm:

This creates all standard RESTful routes:

• GET /products (index)

• GET /products/new (new)

• POST /products (create)

GET Route

Generates:

POST Route

Generates:

PUT Route

Generates:

DELETE Route

Generates:

Root Route

Generates:

Explicit Resources Route

Generates:

Route Patterns

Dynamic Segments

Routes support dynamic segments using [key] notation:

Generates:

The [key] parameter will be available as params.key in your controller.

Custom Parameters

You can use any parameter name:

Generates:

Parameters will be available as params.year and params.month in your controller.

Pattern Only Routes

If you omit the handler, the route will use standard controller/action mapping:

Generates:

This will map to the search action in the products controller.

Route File Integration

Generated Routes Location

All routes are added to /config/routes.cfm at the CLI marker position:

Route Order

The command automatically places new routes at the correct position before the wildcard route. Routes are processed in order, so specific routes must come before general ones.

Using Generated Routes

Route Helpers

Resource routes automatically create URL helpers:

Custom Route Helpers

For custom routes, you'll need to manually create route names in your routes.cfm:

Detailed Parameter Usage

Command Line Parameter Formats

Building on CommandBox's parameter syntax, Wheels route generation supports:

1. Named Parameters (Recommended)

2. Positional Parameters

3. Mixed Parameters

Parameter Validation Rules

HTTP Method Parameters

• Format: --method="pattern,handler" or --method="pattern"

• Methods: get, post, put, patch, delete

Resources Parameters

• Format: --resources=true objectname or objectname --resources=true

• Boolean: Must be explicit true or false

• Objectname: Required when using resources flag

Root Parameters

• Format: --root="controller##action"

• Handler: Required controller and action

• Quotes: Always use quotes

Parameter Examples by Type

String Parameters with Handlers

String Parameters without Handlers

Boolean Parameters

Mixed Parameter Combinations

Common Parameter Mistakes

❌ Missing equals sign:

❌ Missing quotes:

❌ Single hash instead of double:

❌ Missing objectname with resources:

✅ Correct formats:

Advanced Parameter Usage

Dynamic URL Segments

API-Style Routes

Namespace-Style Controllers

Parameter Processing Details

Command Line Processing

1. Quoted Parameters: Preserve spaces and special characters

2. Equals Processing: Splits parameter name from value

3. Boolean Conversion: Converts "true"/"false" strings to boolean values

4. Array Processing: CommandBox processes space-separated values as arrays

Internal Parameter Handling

1. reconstructArgs(): Processes CommandBox parameter format

2. Validation: Checks required parameters are present

3. Route Generation: Formats parameters for Wheels router syntax

4. File Injection: Places routes at correct position in routes.cfm

Integration with Routes.cfm

CLI Marker

The command looks for // CLI-Appends-Here comment to place new routes. If not found, it tries different indentation levels:

1. // CLI-Appends-Here (3 tabs)

2. // CLI-Appends-Here (2 tabs)

3. // CLI-Appends-Here (1 tab)

Manual Route Organization

After using the CLI, you may want to reorganize routes manually:

Best Practices

1. Use equals syntax: Always use --get="pattern,handler" format

2. Resources for CRUD: Use resources route for full CRUD operations

3. Custom routes for special actions: Use HTTP method routes for non-CRUD actions

4. Check route order

Troubleshooting

Common Issues and Solutions

1. Parameter Syntax Errors

Issue: "Missing argument" errors when using HTTP method parameters

❌ Incorrect:

✅ Correct:

Solution: Always use equals syntax with quotes for HTTP method parameters.

2. CFML Syntax Errors

Issue: Template compilation errors with single hash (#) in handlers

❌ Incorrect:

✅ Correct:

Solution: Always use double hash (##) in controller##action handlers.

3. Routes Not Working

Issue: Generated routes don't respond or show 404 errors

Possible Causes:

• Application not reloaded after route changes

• Route order conflicts (specific routes after wildcard)

• Controller or action doesn't exist

Solutions:

4. Parameter Parsing Issues

Issue: Complex patterns not parsed correctly

❌ Problematic:

✅ Solutions:

5. Resources Route Issues

Issue: Resources flag not working or missing objectname

❌ Common Mistakes:

✅ Correct Usage:

6. Route Placement Issues

Issue: Routes added in wrong location or break existing routes

Common Problems:

• CLI marker // CLI-Appends-Here not found

• Routes added after wildcard route

• Malformed routes.cfm syntax

Solutions:

Validation and Testing

Pre-Generation Checklist

Before generating routes, verify:

Post-Generation Validation

After generating routes, always:

Testing Generated Routes

Error Reference

Common Error Messages

"Please provide either an objectname for a resources route or specify a route type"

• Cause: No parameters provided to command

• Solution: Provide either objectname or HTTP method parameter

"key [TYPE] doesn't exist"

• Cause: Internal processing error (rare)

• Solution: Try simpler route first, then add complexity

"Template compilation error"

• Cause: Single hash (#) in generated route

• Solution: Check for double hash (##) in all handlers

"Route not found" (404 errors)

• Cause: Route not added or application not reloaded

• Solution: Check routes.cfm and reload application

Best Practices for Avoiding Issues

1. Parameter Formatting

2. Route Planning

3. Testing Strategy

4. Documentation

Getting Help

If you encounter issues not covered here:

1. Check the debug footer: Shows all registered routes

2. Verify controller exists: Match route handler to actual controller/action

3. Test with simple routes first: Basic patterns before complex ones

4. Check Wheels routing guide: For advanced routing features

See Also

• - Generate complete CRUD with routes

• - Generate controllers

• - Generate models

• - Complete routing documentation

Display CLI and Wheels framework version information.

Synopsis

Description

The wheels info command displays information about the Wheels CLI module and identifies the Wheels framework version in the current directory.

Arguments

This command has no arguments.

Output

The command displays:

1. Wheels ASCII Art - A colorful banner

2. Current Working Directory - Where you're running the command from

3. CommandBox Module Root - Where the CLI module is installed

4. Current Wheels Version - The detected Wheels framework version in this directory

Example Output

Use Cases

• Verify CLI installation location

• Check Wheels framework version in current directory

• Troubleshoot path issues

• Quick visual confirmation of Wheels environment

Notes

• The Wheels version is detected by looking for box.json files in the vendor/wheels directory

• If no Wheels version is found, it will show "Not Found"

• The colorful ASCII art helps quickly identify you're using Wheels CLI

See Also

• - Initialize a Wheels application

• - Manage dependencies

Run the next pending database migration.

Synopsis

Alias: wheels db up

Description

The dbmigrate up command executes the next pending migration in your database migration queue. This command is used to incrementally apply database changes one migration at a time, allowing for controlled and reversible database schema updates.

Parameters

None.

Examples

Run the next pending migration

This will execute the next migration in the sequence and update the database schema version.

Use Cases

Incremental Database Updates

When you want to apply database changes one at a time rather than all at once:

Controlled Migration Application

Apply migrations one at a time for better control:

Notes

• Migrations are executed in chronological order based on their timestamps

• Each migration is tracked in the database to prevent duplicate execution

• If already at latest version, displays: "We're all up to date already!"

• If no more versions available, displays: "No more versions to go to?"

Related Commands

• - Rollback the last migration

• - Run all pending migrations

• - View migration status

• - Reset all migrations

⚠️ DEPRECATED: This command has been deprecated. Please use wheels security scan instead.

Migration Notice

The analyze security command has been moved to provide better organization and expanded functionality.

Wheels was designed to be as lightweight as possible, so this keeps your options fairly open for developing AJAX features into your application.

While there are several flavors of JavaScript libraries out there with AJAX support, we will be using the jQuery framework in this tutorial. Let's assume that you are fairly familiar with the basics of jQuery and know how to set it up.

For this tutorial, let's create the simplest example of all: a link that will render a message back to the user without refreshing the page.

A Simple Example

In this example, we'll wire up some simple JavaScript code that calls a Wheels action asynchronously. All of this will be done with basic jQuery code and built-in Wheels functionality.

First, let's make sure we've got an appropriate route setup. It might be you're still using the default wildcard() route which will create some default GET routes for the controller/action pattern, but we'll add a new route here just for practice. We are going to create a route named sayHello and direct it to the hello action of the say controller. There are two ways you could write this code a long hand method specifying the controller and action separately as well as a short hand method that combines the two into a single parameter.

The longhand way would look like:

The shorthand method would look like:

You can decide which method you prefer. Both sets of code above are equivalent.

Then, let's create a link to a controller's action in a view file, like so:

That piece of code by itself will work just like you expect it to. When you click the link, you will load the hello action inside the say controller.

But let's make it into an asynchronous request. Add this JavaScript (either on the page inside script tags or in a separate .js file included via ):

With that code, we are listening to the click event of the hyperlink, which will make an asynchronous request to the hello action in the say controller. Additionally, the JavaScript call is passing a URL parameter called format set to json.

Note that the success block inserts keys from the response into the empty h1 and p blocks in the calling view. (You may have been wondering about those when you saw the first example. Mystery solved.)

The last thing that we need to do is implement the say/hello action. Note that the request expects a dataType of JSON. By default, Wheels controllers only generate HTML responses, but there is an easy way to generate JSON instead using Wheels's and functions:

In this controller's config() method, we use the function to indicate that we want all actions in the controller to be able to respond with the data in HTML or JSON formats. Note that the client calling the action can request the type by passing a URL parameter named format or by sending the format in the request header.

The call to in the hello action takes care of the translation to the requested format. Our JavaScript is requesting JSON, so Wheels will format the greeting struct as JSON automatically and send it back to the client. If the client requested HTML or the default of none, Wheels will process and serve the view template at /app/views/say/hello.cfm. For more information about and , reference the chapter on .

Lastly, notice the lines where we're setting greeting["message"] and greeting["time"]. Due to the case-insensitive nature of ColdFusion, we recommend setting variables to be consumed by JavaScript using bracket notation like that. If you do not use that notation (i.e., greetings.message and greetings.time instead), your JavaScript will need to reference those keys from the JSON as MESSAGE and TIME (all caps). Unless you like turning caps lock on and off, you can see how that would get annoying after some time.

Assuming you already included jQuery in your application and you followed the code examples above, you now have a simple AJAX-powered web application built on Wheels. After clicking that Alert me! link, your say controller will respond back to you the serialized message via AJAX. jQuery will parse the JSON object and populate the h1 and pwith the appropriate data.

AJAX in Wheels Explained

That is it! Hopefully now you have a clearer picture on how to create AJAX-based features for your web applications.

Installing Wheels is so simple that there is barely a need for a chapter devoted to it. But we figured we'd better make one anyway in case anyone is specifically looking for a chapter about installation.

So, here are the simple steps you need to follow to get rolling on Wheels...

Manual Installation

1. Download Wheels

You have 2 choices when downloading Wheels. You can either use the latest official release of Wheels, or you can take a walk on the wild side and go with the latest committed source code in our Git repository.

The latest official releases can always be found in the section of GitHub, and the Git repository is available at our .

In most cases, we recommend going with the official release because it's well documented and has been through a lot of bug testing. Only if you're in desperate need of a feature that has not been released yet would we advise you to go with the version stored in the Git master branch.

Let's assume you have downloaded the latest official release. (Really, you should go with this option.) You now have a .zip file saved somewhere on your computer. On to the next step...

2. Setup the Website

Getting an empty website running with Wheels installed is an easy process if you already know your way around IIS or Apache. Basically, you need to create a new website in your web server of choice and unzip the contents of the file into the root of it.

In case you're not sure, here are the instructions for setting up an empty Wheels site that can be accessed when typing localhost in your browser. The instructions refer to a system running Windows Server 2003 and IIS, but you should be able to follow along and apply the instructions with minor modifications to your system. (See for a list of tested systems).

• Create a new folder under your web root (usually C:\Inetpub\wwwroot) named wheels_site and unzip the Wheels .zip file into the root of it.

• Create a new website using IIS called Wheels Site with localhost as the host header name and C:\Inetpub\wwwroot\mysite as the path to your home directory.

If you want to run a Wheels-powered application from a subfolder in an existing website, this is entirely possible, but you may need to get a little creative with your URL rewrite rules if you want to get pretty URLs--it will only work out of the box on recent versions of Apache. (Read more about this in the chapter.)

3. Setup the Database (Optional)

Create a new database in MySQL, PostgreSQL, Microsoft SQL Server, Oracle, SQLite or H2 and add a new data source for it in the ColdFusion/Lucee Administrator, just as you'd normally do. Now open up /config/settings.cfm and call set(dataSourceName="") with the name you chose for the data source.

If you don't want to be bothered by opening up a Wheels configuration file at all, there is a nice convention you can follow for the naming. Just name your data source with the same name as the folder you are running your website from (mysite in the example above), and Wheels will use that when you haven't set the dataSourceName setting using the function.

4. Test It

When you've followed the steps above, you can test your installation by typing http://localhost/ (or whatever you set as the host header name) in your web browser. You should get a "Congratulations!" page.

That's it. You're done. This is where the fun begins!

Reset all database migrations by migrating to version 0.

Synopsis

Description

The dbmigrate reset

Execute a specific database migration by version number.

Synopsis

Alias: wheels db exec

Reload the Wheels application in different modes.

Synopsis

Description

The wheels reload

Wheels 2.x

Create a basic CRUD interface in Wheels 2.x

Create a basic JSON API in Wheels 2.x

Routing in Wheels 2.x - Part 1

Routing in Wheels 2.x - Part 2

Introduction to Unit Testing in Wheels 2.x

Unit Testing Controllers in Wheels 2.x

Rollback the last executed database migration.

Synopsis

Alias: wheels db down

Shows detailed information about a Wheels plugin, including version, description, author, and links.

Usage

Parameters

Description

The plugins info command displays comprehensive information about a Wheels plugin. It prioritizes local installation data when available, only querying ForgeBox when the plugin is not installed locally.

Information Displayed

When the plugin is installed locally, the command shows:

• Installation status

• Plugin name and version

• Slug

• Type (mvc, plugin, etc.)

When the plugin is not installed, the command shows:

• Installation status

• ForgeBox package information

• Available versions

• Installation instructions

Examples

Check installed plugin

Output:

Check plugin not installed

Output:

Plugin not found anywhere

Output:

How It Works

1. Check Local Installation: First checks if the plugin is installed in:

   • box.json dependencies

   • box.json devDependencies

Notes

• The command prioritizes local plugin data over ForgeBox data for accuracy

• No network call is made for installed plugins (faster response)

• Use wheels plugin search to browse all available plugins

• Plugin names can include variations (e.g., "wheels-core", "cfwheels-core")