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:

   Copy

   box install wheels-cli

Setting up Docker Development Environment

Ensure you are in the application root directory.

Initialize your Docker development environment:

wheels docker init cfengine=adobe cfversion=2018 db=mysql

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

• Major versions for BoxLang: 1

db options:

• mysql - MySQL database

• postgres - PostgreSQL database

• mssql - Microsoft SQL Server

• h2 - H2 embedded database

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

• CFConfig.json - CFML engine configuration with datasource setup

Starting Your Development Environment

After running the init command, start your containers:

docker-compose up -d

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

# Stop the containers
docker-compose down

# View running containers
docker-compose ps

# View container logs
docker-compose logs

# Rebuild and restart
docker-compose up -d --build

Additional Configuration

Custom Ports

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

{
    "name":"wheels",
    "web":{
        "host":"localhost",
        "http":{
            "port":3000
        },
        "webroot":"public",
        "rewrites":{
            "enable":true,
            "config":"public/urlrewrite.xml"
        }
    }
}

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:

# Check if ports are in use
docker-compose ps
netstat -an | grep 8080

# Force recreate containers
docker-compose down
docker-compose up -d --force-recreate

Database connection issues:

# Check database container logs
docker-compose logs db

# Restart just the database
docker-compose restart db

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 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.

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:

mapper()
  .get(name="sayHello", controller="say", action="hello")
.end()

The shorthand method would look like:

mapper()
  .get(name="sayHello", to="say##hello")
.end()

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:

<cfoutput>

<!--- View code --->
<h1></h1>
<p></p>

#linkTo(text="Alert me!", route="sayHello", id="alert-button")#

</cfoutput>

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 javaScriptIncludeTag() ):

(function($) {
    // Listen to the "click" event of the "alert-button" link and make an AJAX request
    $("#alert-button").on("click", function(event) {
        $.ajax({
            type: "GET",
            // References "/say/hello?format=json"
            url: $(this).attr("href") + "?format=json",
            dataType: "json",
            success: function(response) {
                $("h1").html(response.message);
                $("p").html(response.time);
            }
        });

        event.preventDefault();
    });
})(jQuery);

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 provides() and renderWith() functions:

component extends="Controller" {
    function config() {
        provides("html,json");
    }

    function hello() {
        // Prepare the message for the user.
        greeting = {};
        greeting["message"] = "Hi there";
        greeting["time"] = Now();

        // Respond to all requests with `renderWith()`.
        renderWith(greeting);
    }
}

In this controller's config() method, we use the provides() 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 renderWith() 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 provides() and renderWith(), reference the chapter on Responding with Multiple Formats.

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.

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.

• Encourage clean and pragmatic design.

• Simplify saving data to a storage layer.

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.

• Good old CFML code is used for everything, so there is no need to mess with XML for example.

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.

We can identify 3 different types of requirements that you should be aware of:

• Project Requirements. Is Wheels a good fit for your project?

• Developer Requirements. Do you have the knowledge and mindset to program effectively in Wheels?

• System Requirements. Is your server ready for Wheels?

Project Requirements

Before you start learning Wheels and making sure all the necessary software is installed on your computer, you really need to take a moment and think about the project you intend to use Wheels on. Is it a ten page website that won't be updated very often? Is it a space flight simulator program for NASA? Is it something in between?

Most websites are, at their cores, simple data manipulation applications. You fetch a row, make some updates to it, stick it back in the database and so on. This is the "target market" for Wheels--simple CRUD (create, read, update, delete) website applications.

A simple ten page website won't do much data manipulation, so you don't need Wheels for that (or even ColdFusion in some cases). A flight simulator program will do so much more than simple CRUD work, so in that case, Wheels is a poor match for you (and so perhaps, is ColdFusion).

If your website falls somewhere in between these two extreme examples, then read on. If not, go look for another programming language and framework. ;)

Another thing worth noting right off the bat (and one that ties in with the simple CRUD reasoning above) is that Wheels takes a very data-centric approach to the development process. What we mean by that is that it should be possible to visualize and implement the database design early on in the project's life cycle. So, if you're about to embark on a project with an extensive period of object oriented analysis and design which, as a last step almost, looks at how to persist objects, then you should probably also look for another framework.

Still reading?

Good!

Moving on...

Developer Requirements

Yes, there are actually some things you should familiarize yourself with before starting to use Wheels. Don't worry though. You don't need to be an expert on any on of them. A basic understanding is good enough.

• CFML. You should know CFML, the ColdFusion programming language. (Surprise!)

• Object Oriented Programming. You should grasp the concept of object oriented programming and how it applies to CFML.

• Model-View-Controller. You should know the theory behind the Model-View-Controller development pattern.

CFML

Simply the best web development language in the world! The best way to learn it, in our humble opinion, is to get the free developer edition of Adobe ColdFusion, buy Ben Forta's ColdFusion Web Application Construction Kit series, and start coding using your programming editor of choice. Remember it's not just the commercial Adobe offering that's available; Lucee offers an excellent open source alternative. Using CommandBox is a great and simple way to get a local development environment of your choice up and running quickly.

Object Oriented Programming (OOP)

This is a programming methodology that uses constructs called objects to design applications. Objects model real world entities in your application. OOP is based on several techniques including inheritance, modularity, polymorphism, and encapsulation. Most of these techniques are supported in CFML, making it a fairly functional object oriented language. At the most basic level, a .cfc file in CFML is a class, and you create an instance of a class by using the CreateObject function or the <cfobject> tag.

Trying to squeeze an explanation of object oriented programming and how it's used in CFML into a few sentences is impossible, and a detailed overview of it is outside the scope of this chapter. There is lots of high quality information online, so go ahead and Google it.

Model-View-Controller

Model-View-Controller, or MVC for short, is a way to structure your code so that it is broken down into 3 easy-to-manage pieces:

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

• View. What the user sees and interacts with (a web page in our case).

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

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 is very nicely separated into one of these 3 categories.

System Requirements

Wheels requires that you use one of these CFML engines:

• Adobe ColdFusion 2018 / 2021 / 2023 / 2025

• Lucee 5.2.1.9+ / 6 / 7

• BoxLang 1

Operating Systems

Your ColdFusion or Lucee engine can be installed on Windows, Mac, UNIX, or Linux—they all work just fine.

Web Servers

You also need a web server. Wheels runs on all popular web servers, including Apache, Microsoft IIS, Jetty, and the JRun or Tomcat web server that ships with Adobe ColdFusion. Some web servers support URL rewriting out of the box, some support the cgi.PATH_INFO variable which is used to achieve partial rewriting, and some don't have support for either. For local development, we strongly encourage the use of CommandBox.

Don't worry though. Wheels will adopt to your setup and run just fine, but the URLs that it creates might differ a bit. You can read more about this in the URL Rewriting chapter.

Database Engines

Finally, to build any kind of meaningful website application, you will likely interact with a database. These are the currently supported databases:

• SQL Server 7+

• MySQL 5+ *

• PostgreSQL 8.4+

• H2 1.4+

• Oracle 19c+

OK, hopefully this chapter didn't scare you too much. You can move on knowing that you have the basic knowledge needed, the software to run Wheels, and a suitable project to start with.

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?"

• Automatically runs dbmigrate info after successful migration

• Always backup your database before running migrations in production

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.

Old Command (Still Works)

New Command

Why the Change?

• Better command organization with dedicated security namespace

• Enhanced scanning capabilities

• Improved reporting options

• Integration with security vulnerability databases

See Also

• - The replacement command with enhanced features

Deprecation Timeline

• Deprecated: v1.5.0

• Warning Added: v1.6.0

• Removal Planned: v2.0.0

The command currently redirects to wheels security scan with a deprecation warning.

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

Wheels 2.x

Create a basic CRUD interface in Wheels 2.x https://youtu.be/K5HLItTru1g

Create a basic JSON API in Wheels 2.x https://youtu.be/qZr5JzO0vo4

Routing in Wheels 2.x - Part 1 https://youtu.be/BnPGApAvMVQ

Routing in Wheels 2.x - Part 2 https://youtu.be/0CiGxJyJEIQ

Introduction to Unit Testing in Wheels 2.x https://youtu.be/XgMuzzmBQ98

Unit Testing Controllers in Wheels 2.x https://youtu.be/cygj9WDqHjY

Wheels 1.x

View all screencasts on Vimeo

CRUD series

Episode 1: "C" Is for "Create" - Basic CRUD Learn about basic create operations when building standard CRUD functionality in Wheels

Episode 2: "R"; Is for "Read" - Basic CRUD Learn about basic read operations when building standard CRUD functionality in Wheels

Episode 3: "U" Is for "Update" - Basic CRUD Chris Peters demonstrates updating data in a simple CRUD Wheels application

Episode 4: "D" Is for Delete - Basic CRUD Learn how simple it is to delete records in a basic CRUD application using Wheels

"Building a Social Network"

Episode 1: Setting up ColdFusion on Wheels Chris Peters starts the webcast series by demonstrating how to set up ColdFusion on Wheels;

Episode 2: Form Helpers Chris Peters demonstrates how to bind a Wheels model object to a form through the use of form helpers

Episode 3: Object Validation and Showing Errors

Chris Peters adds data validation to the user registration form

Episode 4: Redirects and the Flash Chris Peters finishes the "success" portion of the registration functionality by adding a success message to the Flash and redirecting the user to their home screen

Episode 5: Object Validation Chris Peters teaches you about more validation options and how you can add them to the registration form quickly and easily

Episode 6: Styling Forms Chris Peters stylizes form markup globally using a Wheels feature called global helpers

Episode 7: Authentication with Filters Learn how to set up simple user authentication on a website by using a Wheels feature called filters

Episode 8: Reading and Displaying a Single Record Learn the mechanics of reading a single record from the database and displaying its data in the view

Episode 9: Adding a Route for User Profiles Creating custom URL patterns is a breeze in ColdFusion on Wheels

Episode 10: Displaying Sets of Records Learn how to fetch multiple records from your model with findAll() and then display them to the user using ColdFusion on Wheels

Episode 11: Custom View Helpers Learn how to factor out logic in your view templates into custom helper functions in ColdFusion on Wheels

Episode 12: Joining Models with Associations Chris Peters demonstrates joining data together with model associations using ColdFusion on Wheels

Episode 13: Pagination All it takes to offer pagination is two extra arguments to findAll() and a call to a view helper called paginationLinks()

Episode 14: Responding with Multiple Formats Learn how to use the provides() and renderWith() functions to automatically serialize data into XML, JSON, and more

Other

Hello World Peter Amiri walks you through setting up a "Hello World" application using the ColdFusion on Wheels framework;

CFUnited 2010: Simplifying Database Code with the ColdFusion on Wheels ORM Chris Peters gives a high level overview of the ORM included with ColdFusion on Wheels

ColdRoute Plugin Chris Peters from Liquifusion demonstrates the ColdRoute plugin for Wheels

Wirebox Plugin for Wheels Doug Boude demonstrates using his new Wirebox plugin for Wheels

Database Migrations Chris Peters from Liquifusion demonstrates creating tables and records using database migrations in ColdFusion on Wheels

CF Meetup, March 10 2011 Online ColdFusion Meetup (coldfusionmeetup.com) session for March 10 2011, "What's New in Wheels 1.1", with Chris Peters:

Wheels Textmate Bundle Demo A quick demo of the Wheels Textmate bundle by Russ Johnson

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 Releases section of GitHub, and the Git repository is available at our GitHub repo.

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 Requirements 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 URL Rewriting chapter.)

3. Setup the Database (Optional)

Create a new database in MySQL, PostgreSQL, Microsoft SQL Server, Oracle 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 Set() 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!

Testing Your Install

Let's make sure we're all on the same page. I'm going to assume that you've followed the Getting Started guide and have CommandBox all setup. If you haven't done that, stop and read that guide get everything setup. It's okay, this web page will wait for you.

Okay, so you have Wheels installed and can see the Wheels "Congratulations!" page as shown below. That wasn't that hard now, was it?

Hello World: Your First Wheels App

Okay, let's get to some example code. We know that you've been dying to get your hands on some code!

To continue with Programming Tutorial Tradition, we'll create the ubiquitous Hello World! application. But to keep things interesting, let's add a little Wheels magic along the way.

Setting up the Controller

Let's create a controller from scratch to illustrate how easy it is to set up a controller and plug it into the Wheels framework.

First, create a file called Say.cfc in the /app/controllers directory and add the code below to the file.

component extends="Controller"{
}

Congratulations, you just created your first Wheels controller! What does this controller do, you might ask? Well, to be honest, not much. It has no methods defined, so it doesn't add any new functionality to our application. But because it extends the base Controller component, it inherits quite a bit of powerful functionality and is now tied into our Wheels application.

So what happens if we try to call our new controller right now? Lets take a look. Open your browser and point your browser to the new controller. Because my local server is installed on port 60000, my URL is http://127.0.0.1:60000/say. You may need to enter a different URL, depending on how your web server is configured. In my case, I'm using CommandBox.

The error says "Could not find the view page for the 'index' action in the 'say' controller." Where did "index" come from? The URL we typed in only specified a controller name but no action. When an action is not specified in the URL, Wheels assumes that we want the default action. Out of the box, the default action in Wheels is set to index. So in our example, Wheels tried to find the index action within the say controller, and it threw an error because it couldn't find its view page.

Setting up an Action

But let's jump ahead. Now that we have the controller created, let's add an action to it called hello. Change your say controller so it looks like the code block below:

component extends="Controller" {
    function hello() {
    }
}

As you can see, we created an empty method named hello.

Now let's call our new action in the browser and see what we get. To call the hello action, we simply add /hello to the end of the previous URL that we used to call our say controller:

http://127.0.0.1:60000/say/hello

Once again, we get a ColdFusion error. Although we have created the controller and added the hello action to it, we haven't created the view.

Setting up the View

By default, when an action is called, Wheels will look for a view file with the same name as the action. It then hands off the processing to the view to display the user interface. In our case, Wheels tried to find a view file for our say/hello action and couldn't find one.

Let's remedy the situation and create a view file. View files are simple CFML pages that handle the output of our application. In most cases, views will return HTML code to the browser. By default, the view files will have the same name as our controller actions and will be grouped into a directory under the view directory. This new directory will have the same name as our controller.

Find the views directory inside the app directory, located at / in your Wheels installation. There will be a few directories in there already. For now, we need to create a new directory in the views directory called say. This is the same name as the controller that we created above.

Now inside the say directory, create a file called hello.cfm. In the hello.cfm file, add the following line of code:

<h1>Hello World!</h1>

Save your hello.cfm file, and let's call our say/hello action once again. You have your first working Wheels page if your browser looks like Figure 3 below.

You have just created your first functional Wheels page, albeit it is a very simple one. Pat yourself on the back, go grab a snack, and when you're ready, let's go on and extend the functionality of our Hello World! application a little more.

Adding Dynamic Content to Your View

We will add some simple dynamic content to our hello action and add a second action to the application. We'll then use some Wheels code to tie the 2 actions together. Let's get get to it!

The Dynamic Content

The first thing we are going to do is to add some dynamic content to our say/hello action. Modify your say controller so it looks like the code block below:

component extends="Controller" {
    function hello() {
        time = Now();
    }
}

All we are doing here is creating a variable called time and setting its value to the current server time using the basic ColdFusion Now() function. When we do this, the variable becomes immediately available to our view code.

Why not just set up this value directly in the view? If you think about it, maybe the logic behind the value of time may eventually change. What if eventually we want to display its value based on the user's time zone? What if later we decide to pull it from a web service instead? Remember, the controller is supposed to coordinate all of the data and business logic, not the view.

Displaying the Dynamic Content

Next, we will modify our say/hello.cfm view file so that it looks like the code block below. When we do this, the value will be displayed in the browser.

<h1>Hello World!</h1>
<p>Current time: <cfoutput>#time#</cfoutput></p>

call your say/hello action again in your browser. Your browser should look like Figure 4 below.

This simple example showed that any dynamic content created in a controller action is available to the corresponding view file. In our application, we created a time variable in the say/hello controller action and display that variable in our say/hello.cfm view file.

Adding a Second Action: Goodbye

Now we will expand the functionality of our application once again by adding a second action to our say controller. If you feel adventurous, go ahead and add a goodbye action to the say controller on your own, then create a goodbye.cfm view file that displays a "Goodbye" message to the user. If you're not feeling that adventurous, we'll quickly go step by step.

First, modify the the say controller file so that it looks like the code block below.

component extends="Controller" {
    function hello() {
        time = Now();
    }

    function goodbye() {
    }
}

Now go to the /app/views/say directory and create a goodbye.cfm page.

Add the following code to the goodbye.cfm page and save it.

Goodbye World!

If we did everything right, we should be able to call the new say/goodbye action using the following URL:

http://127.0.0.1:60000/say/goodbye

Your browser should look like Figure 5 below:

Linking to Other Actions

Now let's link our two actions together. We will do this by adding a link to the bottom of each page so that it calls the other page.

Linking Hello to Goodbye

Open the say/hello.cfm view file. We are going to add a line of code to the end of this file so our say/hello.cfm view file looks like the code block below:

<h1>Hello World!</h1>
<p>Current time: <cfoutput>#time#</cfoutput></p>
<p>Time to say <cfoutput>#linkTo(text="goodbye", action="goodbye")#?</cfoutput></p>

The linkTo() function is a built-in Wheels function. In this case, we are passing 2 named parameters to it. The first parameter, text, is the text that will be displayed in the hyperlink. The second parameter, action, defines the action to point the link to. By using this built-in function, your application's main URL may change, and even controllers and actions may get shifted around, but you won't suffer from the dreaded dead link. Wheels will always create a valid link for you as long as you configure it correctly when you make infrastructure changes to your application.

Once you have added the additional line of code to the end of the say/hello.cfm view file, save your file and call the say/hello action from your browser. Your browser should look like Figure 6 below.

You can see that Wheels created a link for us and added an appropriate URL for the say/goodbye action to the link.

Linking Goodbye to Hello

Let's complete our little app and add a corresponding link to the bottom of our say/goodbye.cfm view page.

Open your say/goodbye.cfm view page and modify it so it looks like the code block below.

<h1>Goodbye World!</h1>
<p>Time to say <cfoutput>#linkTo(text="hello", action="hello")#?</cfoutput></p>

If you now call the say/goodbye action in your browser, your browser should look like Figure 7 below.

Much More to Learn

You now know enough to be dangerous with Wheels. Look out! But there are many more powerful features to cover. You may have noticed that we haven't even talked about the M in MVC.

No worries. We will get there. And we think you will enjoy it.

Bootstrap an existing Wheels application for CLI usage.

Synopsis

Description

The wheels init command initializes an existing Wheels application to work with the Wheels CLI. It's an interactive command that helps set up necessary configuration files (box.json and server.json) for an existing Wheels installation.

Arguments

This command has no arguments - it runs interactively and prompts for required information.

Interactive Prompts

When you run wheels init, you'll be prompted for:

1. Confirmation - Confirm you want to proceed with initialization

2. Application Name - Used to make server.json server name unique (if box.json doesn't exist)

3. CF Engine - Default CFML engine (e.g., lucee5, adobe2021) (if server.json doesn't exist)

Examples

Initialize current directory

Example interaction:

What It Does

1. Creates vendor/wheels/box.json - Tracks the Wheels framework version

2. Creates server.json - Configures CommandBox server settings with:

   • Unique server name based on application name

   • Selected CF engine

   • Default port and settings

3. Creates box.json - Main project configuration file with:

   • Application name

   • Wheels version dependency

   • Project metadata

Generated Files

server.json

box.json

Prerequisites

Before running wheels init:

• Have an existing Wheels application

• Database/datasource already configured

• Reload password already set in your application settings

Notes

• Run this command in the root directory of your Wheels application

• Files are only created if they don't already exist

• The command detects your current Wheels version automatically

• Special characters are stripped from application names

See Also

• - Create a new Wheels application

• - Reload the application

• - Display version information

Rollback the last executed database migration.

Synopsis

Alias: wheels db down

Description

The dbmigrate down command reverses the last executed migration by running its down() method. This is useful for undoing database changes when issues are discovered or when you need to modify a migration. The command ensures safe rollback of schema changes while maintaining database integrity.

Parameters

None.

Examples

Rollback the last migration

This will execute the down() method of the most recently applied migration, reverting the database changes.

Use Cases

Fixing Migration Errors

When a migration contains errors or needs modification:

Development Iteration

During development when refining migrations:

Emergency Rollback

When a migration causes issues:

Important Considerations

Data Loss Warning

Rolling back migrations that drop columns or tables will result in data loss. Always ensure you have backups before rolling back destructive migrations.

Down Method Requirements

For a migration to be rolled back, it must have a properly implemented down() method that reverses the changes made in the up() method.

Migration Dependencies

Be cautious when rolling back migrations that other migrations depend on. This can break the migration chain.

Best Practices

1. Always implement down() methods: Even if you think you'll never need to rollback

2. Test rollbacks: In development, always test that your down() method works correctly

3. Backup before rollback: Especially in production environments

4. Document destructive operations: Clearly indicate when rollbacks will cause data loss

Notes

• Only the last executed migration can be rolled back with this command

• To rollback multiple migrations, run the command multiple times

• If already at version 0, displays: "We're already on zero! No migrations to go to"

• Automatically runs dbmigrate info after successful rollback

• The migration version is removed from the database tracking table upon successful rollback

• Some operations (like dropping columns with data) cannot be fully reversed

• When migrating to version 0, displays: "Database should now be empty."

Related Commands

• - Run the next migration

• - Reset all migrations

• - View migration status

• - Run a specific migration

Lists installed Wheels plugins from the /plugins folder or shows available plugins from ForgeBox.

Usage

Parameters

Description

The plugins list command displays information about Wheels plugins. By default, it shows plugins installed locally in the /plugins folder. With the --available flag, it queries ForgeBox to show all available cfwheels-plugins packages.

Local Plugin Information

When listing installed plugins, the command displays:

• Plugin name

• Version number

• Description (if available)

Available Plugin Information

When using --available, the command shows all cfwheels-plugins type packages from ForgeBox.

Examples

List installed plugins

Output:

List with no plugins installed

Output:

Export as JSON

Output:

Show available plugins from ForgeBox

Output:

How It Works

1. Local Plugin Detection: Scans the /plugins folder for subdirectories

2. Metadata Extraction: Reads each plugin's box.json file for name, version, slug, and description

3. Dynamic Formatting: Calculates column widths based on content for clean alignment

4. ForgeBox Integration: Uses forgebox show type=cfwheels-plugins for available plugins

Notes

• Only lists plugins from the /plugins folder (not box.json dependencies)

• Only works with cfwheels-plugins type packages

• Plugins without a valid box.json are ignored

• Column widths adjust dynamically for optimal display

• JSON output includes plugin count for programmatic use

• Use wheels plugin info <name> to see detailed information about a specific plugin

Serves generated documentation locally for development and review.

Usage

Parameters

Description

The docs serve command starts a local web server to preview your generated documentation.

Examples

Basic documentation server

Serve on different port

Serve from custom directory

Serve without opening browser

Custom configuration

Server Output

If documentation is not found:

Features

Browser Integration

With --open=true (default), the server automatically opens your default browser to the documentation URL.

Development Workflow

Typical usage:

Custom workflow:

Troubleshooting

Port already in use

Documentation not found

Browser doesn't open

Notes

• Server is intended for development/review only

• For production, deploy static files to web server

• Large documentation sets may take time to generate

• Offline mode caches documentation locally

Reset all database migrations by migrating to version 0.

Synopsis

wheels dbmigrate reset

Alias: wheels db reset

Description

The dbmigrate reset command resets your database by migrating to version 0, effectively rolling back all executed migrations. This is useful during development when you need to start fresh.

Parameters

None.

Examples

Reset all migrations

wheels dbmigrate reset

This will migrate the database to version 0, rolling back all migrations.

Use Cases

Fresh Development Database

Start with a clean slate during development:

# Reset all migrations
wheels dbmigrate reset

# Re-run all migrations
wheels dbmigrate latest

# Seed with test data
wheels db seed

Testing Migration Sequence

Verify that all migrations run correctly from scratch:

# Reset all migrations
wheels dbmigrate reset

# Run migrations one by one to test
wheels dbmigrate up
wheels dbmigrate up
# ... continue as needed

Fixing Migration Order Issues

When migrations have dependency problems:

# Reset all migrations
wheels dbmigrate reset

# Manually fix migration files
# Re-run all migrations
wheels dbmigrate latest

Continuous Integration Setup

Reset database for each test run:

# CI script
wheels dbmigrate reset
wheels dbmigrate latest
wheels test run

Important Warnings

Data Loss

WARNING: This command will result in complete data loss as it rolls back all migrations. Always ensure you have proper backups before running this command, especially in production environments.

Production Usage

Using this command in production is strongly discouraged. If you must use it in production:

1. Take a complete database backup

2. Put the application in maintenance mode

3. Have a rollback plan ready

Migration Dependencies

The reset process rolls back migrations in reverse chronological order. Ensure all your down() methods are properly implemented.

Best Practices

1. Development Only: Primarily use this command in development environments

2. Backup First: Always backup your database before resetting

3. Test Down Methods: Ensure all migrations have working down() methods

4. Document Usage: If used in production, document when and why

Process Flow

1. Displays "Resetting Database Schema"

2. Executes dbmigrate exec version=0

3. Automatically runs dbmigrate info to show the reset status

Notes

• The command will fail if any migration's down() method fails

• Migration files must still exist for rollback to work

• The migration tracking table itself is preserved

• Use wheels dbmigrate info after reset to verify status

Related Commands

• wheels dbmigrate up - Run the next migration

• wheels dbmigrate down - Rollback last migration

• wheels dbmigrate latest - Run all pending migrations

• wheels dbmigrate info - View migration status

• wheels db seed - Seed the database with data

Reload the Wheels application in different modes.

Synopsis

wheels reload [options]
wheels r [options]

Description

The wheels reload command reloads your Wheels application, clearing caches and reinitializing the framework. This is useful during development when you've made changes to configuration, routes, or framework settings. Note: the server must be running for this command to work.

Arguments

Reload Modes

Development Mode

wheels reload password=mypassword

• Enables debugging

• Shows detailed error messages

• Disables caching

• Ideal for active development

Testing Mode

wheels reload mode=testing password=mypassword

• Optimized for running tests

• Consistent environment

• Predictable caching

Maintenance Mode

wheels reload mode=maintenance password=mypassword

• Shows maintenance page to users

• Allows admin access

• Useful for deployments

Production Mode

wheels reload mode=production password=mypassword

• Full caching enabled

• Minimal error information

• Optimized performance

Examples

Basic reload (development mode)

wheels reload password=wheels

Reload in production mode

wheels reload mode=production password=mySecretPassword

Using the alias

wheels r password=wheels

Reload for testing

wheels reload mode=testing password=wheels

Security

• The reload password must match the one configured in your Wheels application

• Password is sent via URL parameter to the running application

• Always use a strong password in production environments

Configuration

Set the reload password in your Wheels settings.cfm:

set(reloadPassword="mySecretPassword");

Notes

• Reload clears all application caches

• Session data may be lost during reload

• Database connections are refreshed

• All singletons are recreated

• The server must be running for this command to work

Common Issues

• Invalid password: Check password in settings.cfm

• Server not running: Start server with box server start

• Connection refused: Ensure server is accessible on expected port

• Timeout: Large applications may take time to reload

See Also

• wheels init - Initialize application configuration=

• wheels info - Display application information

Execute a specific database migration by version number.

Synopsis

wheels dbmigrate exec version=<version>

Alias: wheels db exec

Description

The dbmigrate exec command allows you to migrate to a specific version identified by its version number, regardless of the current migration state. This is useful for moving to any specific point in your migration history.

Parameters

Examples

Execute a specific migration

wheels dbmigrate exec version=20240115123456

Migrate to version 0 (revert all migrations)

wheels dbmigrate exec version=0

Use Cases

Migrating to a Specific Version

Move to any point in migration history:

# Check current status
wheels dbmigrate info

# Migrate to specific version
wheels dbmigrate exec version=20240115123456

Rolling Back to Previous Version

Move to an earlier migration state:

# Check migration history
wheels dbmigrate info

# Go back to specific version
wheels dbmigrate exec version=20240101000000

Reset Database

Clear all migrations:

# Migrate to version 0
wheels dbmigrate exec version=0

# Verify empty state
wheels dbmigrate info

Important Considerations

Migration Order

Executing migrations out of order can cause issues if migrations have dependencies. Always ensure that any required preceding migrations have been run.

Version Tracking

The command updates the migration tracking table to reflect the execution status.

Best Practices

1. Check Dependencies: Ensure required migrations are already applied

2. Test First: Run in development/testing before production

3. Use Sparingly: Prefer normal migration flow with up/latest

4. Document Usage: Record when and why specific executions were done

5. Verify State: Check migration status before and after execution

Version Number Format

Migration versions are typically timestamps in the format:

• YYYYMMDDHHmmss (e.g., 20240115123456)

• Year: 2024

• Month: 01

• Day: 15

• Hour: 12

• Minute: 34

• Second: 56

Notes

• The command will migrate UP or DOWN to reach the specified version

• Version must be a valid migration version or 0 to reset all

• The migration file must exist in the migrations directory

• The command displays the migration progress message

• Both up() and down() methods should be defined in the migration

Related Commands

• wheels dbmigrate up - Run the next migration

• wheels dbmigrate down - Rollback last migration

• wheels dbmigrate latest - Run all pending migrations

• wheels dbmigrate info - View migration status

• wheels dbmigrate create blank - Create a new migration

Removes an installed Wheels CLI plugin.

Synopsis

wheels plugins remove <name> [--force]

CommandBox Parameter Syntax

This command supports multiple parameter formats:

• Positional parameters: wheels plugins remove cfwheels-bcrypt (plugin name)

• Named parameters: name=value (e.g., name=cfwheels-bcrypt)

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

Parameter Mixing Rules:

✅ ALLOWED:

• Positional: wheels plugins remove cfwheels-bcrypt

• Positional + flags: wheels plugins remove cfwheels-bcrypt --force

• All named: name=cfwheels-bcrypt force=true

❌ NOT ALLOWED:

• Positional + named for same param: wheels plugins remove cfwheels-bcrypt name=other

Recommendation: Use positional for plugin name, flags for options: wheels plugins remove cfwheels-bcrypt --force

Parameters

Description

The plugins remove command safely uninstalls a plugin from your Wheels application. It:

• Checks if the plugin is installed

• Prompts for confirmation (unless --force is used)

• Removes plugin from box.json

• Cleans up plugin files

• Updates plugin registry

Examples

Basic plugin removal

wheels plugins remove wheels-vue-cli

Force removal (skip confirmation)

wheels plugins remove wheels-testing --force

Removal Process

1. Installation Check: Verifies the plugin is installed in box.json or plugins folder

2. Confirmation: Prompts user to confirm removal (unless --force is used)

3. Removal: Removes plugin entry from box.json

4. File Cleanup: Deletes plugin files via CommandBox package service

5. Verification: Confirms successful removal

Output

With confirmation prompt (default)

Are you sure you want to remove the plugin 'wheels-vue-cli'? (y/n): y
[*] Removing plugin: wheels-vue-cli...

[OK] Plugin removed successfully
Run 'wheels plugins list' to see remaining plugins

With force flag

[*] Removing plugin: wheels-vue-cli...

[OK] Plugin removed successfully
Run 'wheels plugins list' to see remaining plugins

Plugin not installed

Are you sure you want to remove the plugin 'bcrypt'? (y/n): y
[*] Removing plugin: bcrypt...

[ERROR] Failed to remove plugin: Plugin 'bcrypt' is not installed

Cancellation

Are you sure you want to remove the plugin 'wheels-vue-cli'? (y/n): n
Plugin removal cancelled.

Notes

• The --force flag skips the confirmation prompt

• Use wheels plugins list to verify removal

• The command checks if plugin is actually installed before removal

• Plugin must exist in box.json dependencies, devDependencies, or plugins folder

• Restart your application after removing plugins that affect core functionality

Display database migration status and information.

Synopsis

Alias: wheels db info

Description

The wheels dbmigrate info command shows the current state of database migrations, including which migrations have been run, which are pending, and the current database version.

Parameters

None.

Output

The command displays:

1. Datasource: The database connection being used

2. Database Type: The type of database (MySQL, PostgreSQL, H2, MSSQL(SQL Server), Oracle.)

3. Total Migrations: Count of all migration files found

4. Available Migrations: Number of pending migrations

5. Current Version: The latest migration that has been run

6. Latest Version: The newest migration available

7. Migration List: All migrations with their status (migrated or pending)

Example Output

Migration Files Location

Migrations are stored in /app/migrator/migrations/ and follow the naming convention:

Example:

Understanding Version Numbers

• Version numbers are timestamps in format: YYYYMMDDHHmmss

• Higher numbers are newer migrations

• Migrations run in chronological order

Database Schema Table

Migration status is tracked in c_o_r_e_migrator_versions table:

Use Cases

1. Check before deployment

2. Verify after migration

3. Troubleshoot issues

   • See which migrations have run

   • Identify pending migrations

   • Confirm database version

Troubleshooting

Migration Not Showing

• Check file is in /app/migrator/migrations/

• Verify .cfc extension

• Ensure proper timestamp format

Version Mismatch

• Check c_o_r_e_migrator_versions table

• Verify migration files haven't been renamed

• Look for duplicate timestamps

Connection Issues

• Verify datasource configuration

• Check database credentials

• Ensure database server is running

Integration with CI/CD

Use in deployment scripts:

Best Practices

1. Always check info before running migrations

2. Review pending migrations before deployment

3. Keep migration files in version control

4. Don't modify completed migration files

5. Use info to verify production deployments

See Also

• - Run all pending migrations

• - Run next migration

• - Rollback migration

• - Create new migration

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.)

• Author information

• Description

• Homepage URL

• Repository URL

• Documentation URL

• Issues/Bugs URL

• Keywords

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

   • Reads plugin's local box.json for detailed information

2. Display Local Information: If installed, shows all metadata from the plugin's box.json

3. ForgeBox Fallback: Only queries ForgeBox if the plugin is not installed locally

4. Installation Commands: Shows appropriate commands based on installation status

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")

Generates documentation for your Wheels application from code comments and annotations.

Usage

Parameters

• --output - (Optional) Output directory for docs. Default: docs/api

• --format - (Optional) Documentation format: html, json, markdown. Default: html

• --include - (Optional) Components to include: models, controllers, views, services. Default: models,controllers

• --serve - (Optional) Start local server after generation

• --verbose - (Optional) Verbose output

Description

The docs generate command automatically creates comprehensive documentation from your Wheels application by parsing:

• JavaDoc-style comments in CFCs

• Model relationships and validations

• Controller actions and routes

• Configuration files

• Database schema

• API endpoints

Examples

Generate complete documentation

Generate markdown docs

Generate and serve immediately

Generate specific components with verbose output

Custom output directory

Documentation Sources

Model Documentation

Controller Documentation

Generated Output

HTML Format

Documentation includes:

• Overview: Application structure and architecture

• Models: Properties, methods, relationships, validations

• Controllers: Actions, filters, routes

• API Reference: Endpoints, parameters, responses

• Database Schema: Tables, columns, indexes

• Configuration: Settings and environment variables

Output Example

Documentation Features

Auto-generated Content

• Class hierarchies and inheritance

• Method signatures and parameters

• Property types and defaults

• Relationship diagrams

• Route mappings

• Database ERD

Notes

• Documentation is generated from code comments

• Use consistent JavaDoc format for best results

• Private methods are excluded by default

There is a specific set of standards that Wheels follows when you run it in its default state. This is to save you time. With conventions in place, you can get started coding without worrying about configuring every little detail.

But it is important for you to know these conventions, especially if you're running an operating system and/or DBMS configuration that's picky about things like case sensitivity.

URLs

Wheels uses a very flexible routing system to match your application's URLs to controllers, views, and parameters.

Within this routing system is a default route that handles many scenarios that you'll run across as a developer. The default route is mapped using the pattern [controller]/[action]/[key].

Consider this example URL: http://localhost:8080/users/edit/12

This maps to the Users controller, edit action, and a key of 12. For all intents and purposes, this will load a view for editing a user with a primary key value in the database of 12.

This URL pattern works up the chain and will also handle the following example URLs:

Note that the above conventions are for GET requests and only apply when you have a wildcard() call in /config/routes.cfm (which is the default). See for instructions on overriding this behavior and how to deal with PUT, POST etc.

Naming Conventions for Controllers, Actions, and Views

Controllers, actions, and views are closely linked together by default. And how you name them will influence the URLs that Wheels will generate.

Controllers

First, a controller is a CFC file placed in the controllers folder. It should be named in PascalCase. For example, a site map controller would be stored at /app/controllers/SiteMap.cfc.

Multi-word controllers will be delimited by hyphens in their calling URLs. For example, a URL of /site-map will reference the SiteMap controller.

See for instructions on overriding this behavior.

Actions

Methods within the controllers, known as actions, should be named in camelCase.

Like with controllers, any time a capital letter is used in camelCase, a hyphen will be used as a word delimiter in the corresponding URL. For example, a URL of /site-map/search-engines will reference the searchEngines action in the SiteMap controller.

See for instructions on overriding this behavior.

Views

By default, view files are named after the action names and are stored in folders that correspond to controller names. Both the folder names and view file names should be all lowercase, and there is no word delimiter.

In our /site-map/search-engines URL example, the corresponding view file would be stored at /app/views/sitemap/searchengines.cfm.

For information on overriding this behavior, refer to documentation for the function and read the chapter.

Layouts

A special type of view file called a layout defines markup that should surround the views loaded by the application. The default layout is stored at /app/views/layout.cfm and is automatically used by all views in the application.

Controller-level layouts can also be set automatically by creating a file called layout.cfm and storing it in the given controller's view folder. For example, to create a layout for the users controller, the file would be stored at /app/views/users/layout.cfm.

When a controller-level layout is present, it overrides the default layout stored in the root /app/views folder.

For information on overriding the layout file to be loaded by an action, see the chapter on and documentation for the function.

Naming Conventions for Models and Databases

By default, the names of Wheels models, model properties, database tables, and database fields all relate to each other. Wheels even sets a sensible default for the CFML data source used for database interactions.

Data Sources

By default, the datasource is set to wheels-dev in the /config/settings.cfm file. You can change the value in the set(dataSourceName="wheels-dev") function to whatever you want the name of the datasource to be.

Refer to the chapter for instructions on overriding data source information.

Plural Database Table Names, Singular Model Names

Wheels adopts a Rails-style naming conventions for database tables and model files. Think of a database table as a collection of model objects; therefore, it is named with a plural name. Think of a model object as a representation of a single record from the database table; therefore, it is named with a singular word.

For example, a user model represents a record from the users database table. Wheels also recognizes plural patterns like binary/binaries, mouse/mice, child/children, etc.

Like controller files, models are also CFCs and are named in PascalCase. They are stored in the /app/models folder. So the user model would be stored at /app/models/User.cfc.

For instructions on overriding database naming conventions, refer to documentation for the function and the chapter on .

Everything in the Database is Lowercase

In your database, both table names and column names should be lowercase. The customersegments table could have fields called title, regionid, and incomelevel, for example.

Because of CFML's case-insensitive nature, we recommend that you refer to model names and corresponding properties in camelCase. This makes for easier readability in your application code.

In the customersegments example above, you could refer to the properties in your CFML as title, regionId, and incomeLevel to stick to CFML's Java-style roots. (Built-in CFML functions are often written in camelCase and PascalCase, after all.)

For information on overriding column and property names, refer to documentation for the function and the chapter.

Configuration and Defaults

There are many default values and settings that you can tweak in Wheels when you need to. Some of them are conventions and others are just configurations available for you to change. You can even change argument defaults for built-in Wheels functions to keep your code DRYer.

For more details on what you can configure, read the chapter.

Generate a migration file for dropping a database table.

Synopsis

wheels dbmigrate remove table name=<table_name>

Alias: wheels db remove table

CommandBox Parameter Syntax

This command supports multiple parameter formats:

• Named parameters: name=value (e.g., name=users)

• Flag parameters: --flag=value (e.g., --name=users)

Parameter Mixing Rules:

✅ ALLOWED:

• Named: wheels dbmigrate remove table name=users

• Flag: wheels dbmigrate remove table --name=users

❌ NOT ALLOWED:

• Positional parameters: This command does not support positional parameters

Recommendation: Use named parameters: wheels dbmigrate remove table name=users

Description

The dbmigrate remove table command generates a migration file that drops an existing database table. The generated migration includes a dropTable() call in the up() method.

Parameters

Examples

Basic table removal

wheels dbmigrate remove table name=temp_import_data

Remove user table

wheels dbmigrate remove table name=user

Remove archive table

wheels dbmigrate remove table name=orders_archive_2023

Generated Migration Example

For the command:

wheels dbmigrate remove table name=product_archive

Generates:

component extends="wheels.migrator.Migration" hint="remove product_archive table" {

    function up() {
        transaction {
            dropTable("product_archive");
        }
    }

    function down() {
        transaction {
            // Add code here to recreate the table if needed for rollback
            // createTable(name="product_archive") { ... }
        }
    }

}

Use Cases

Removing Temporary Tables

Clean up temporary or staging tables:

# Remove import staging table
wheels dbmigrate remove table name=temp_customer_import

# Remove data migration table
wheels dbmigrate remove table name=migration_backup_20240115

Refactoring Database Schema

Remove tables during schema refactoring:

# Remove old table after data migration
wheels dbmigrate remove table name=legacy_orders

# Remove deprecated table
wheels dbmigrate remove table name=user_preferences_old

Cleaning Up Failed Features

Remove tables from cancelled features:

# Remove tables from abandoned feature
wheels dbmigrate remove table name=beta_feature_data
wheels dbmigrate remove table name=beta_feature_settings

Archive Table Cleanup

Remove old archive tables:

# Remove yearly archive tables
wheels dbmigrate remove table name=orders_archive_2020
wheels dbmigrate remove table name=orders_archive_2021

Safety Considerations

Data Loss Warning

CRITICAL: Dropping a table permanently deletes all data. Always:

1. Backup the table data before removal

2. Verify data has been migrated if needed

3. Test in development/staging first

4. Have a rollback plan

Dependent Objects

Consider objects that depend on the table:

• Foreign key constraints

• Views

• Stored procedures

• Triggers

• Application code

Handling Dependencies

Be aware of dependent objects when removing tables:

• Foreign key constraints

• Views that reference the table

• Stored procedures using the table

• Application code dependencies

Best Practices

1. Document Removals

Add clear documentation about why the table is being removed:

# Create descriptive migration
wheels dbmigrate remove table name=obsolete_analytics_cache

# Then edit the migration file to add detailed comments about why it's being removed

2. Backup Data First

Before removing tables, create data backups:

# First backup the data
wheels db schema format=sql > backup_before_removal.sql

# Then create removal migration
wheels dbmigrate remove table name=user_preferences

3. Staged Removal

For production systems, consider staged removal:

# Stage 1: Rename table (keep for rollback)
wheels dbmigrate create blank name=rename_orders_to_orders_deprecated

# Stage 2: After verification period, remove
wheels dbmigrate remove table name=orders_deprecated

4. Check Dependencies

Verify no active dependencies before removal:

-- Check foreign keys
SELECT * FROM information_schema.referential_constraints 
WHERE referenced_table_name = 'table_name';

-- Check views
SELECT * FROM information_schema.views 
WHERE table_schema = DATABASE() 
AND view_definition LIKE '%table_name%';

Migration Structure

The generated migration contains:

• An up() method with dropTable()

• An empty down() method for you to implement rollback logic if needed

You should edit the down() method to add table recreation logic if you want the migration to be reversible.

Recovery Strategies

If Removal Was Mistake

1. Don't run the migration in production

2. Use wheels dbmigrate down if already run

3. Restore from backup if down() fails

Preserving Table Structure

Before removal, capture structure:

# Export entire database schema
wheels db schema format=sql --save file=schema_backup.sql

# Then remove table
wheels dbmigrate remove table name=user_preferences

Notes

• The command analyzes table structure before generating migration

• Foreign key constraints must be removed before table removal

• The migration is reversible if table structure is preserved

• Always review generated migration before running

Related Commands

• wheels dbmigrate create table - Create tables

• wheels dbmigrate create blank - Create custom migrations

• wheels dbmigrate up - Run migrations

• wheels dbmigrate down - Rollback migrations

• wheels db schema - Export table schemas

Run all pending database migrations to bring database to latest version.

Synopsis

Alias: wheels db latest

Description

The wheels dbmigrate latest command runs all pending migrations in chronological order, updating your database schema to the latest version. This is the most commonly used migration command.

Parameters

None.

How It Works

1. Retrieves current database version and latest version

2. Executes dbmigrate exec with the latest version

3. Automatically runs dbmigrate info after completion

4. Updates version tracking after successful migration

Example Output

Migration Execution

Each migration file must contain:

Transaction Safety

Migrations run within transactions:

• All changes in a migration succeed or fail together

• Database remains consistent

• Failed migrations can be retried

Common Migration Operations

Create Table

Add Column

Add Index

Modify Column

Best Practices

1. Test migrations locally first

2. Backup before production migrations

3. Use transactions

4. Make migrations reversible

Environment-Specific Migrations

Migrations can check environment:

Checking Migrations

Preview migrations before running:

Performance Considerations

For large tables:

Continuous Integration

Add to CI/CD pipeline:

Rollback Strategy

If issues occur after migration:

1. Use down migrations

2. Restore from backup

3. Fix and retry

   • Fix migration file

   • Run wheels dbmigrate latest

Common Issues

Timeout on Large Tables

Foreign Key Constraints

See Also

• - Check migration status

• - Run single migration

• - Rollback migration

• - Create migration

⚠️ Note: This command depends on configuration values. Please verify your database configuration before executing it.

Drop an existing database.

Synopsis

Description

The wheels db drop command permanently deletes a database. This is a destructive operation that cannot be undone. By default, it requires confirmation unless the --force flag is used.

Options

Examples:

Examples

Basic Usage

Drop database with confirmation:

Force Drop

Drop without confirmation:

Drop Test Database

Safety Features

1. Confirmation Required: By default, you must type "yes" to confirm

2. Production Warning: Extra warning when dropping production databases

3. Clear Messaging: Shows database name and environment before dropping

Database-Specific Behavior

MySQL/MariaDB

• Uses DROP DATABASE IF EXISTS statement

• Connects to information_schema to execute command

• Automatically handles active connections

PostgreSQL

• Terminates existing connections before dropping

• Uses DROP DATABASE IF EXISTS statement

• Connects to postgres system database

SQL Server

• Sets database to single-user mode to close connections

• Uses DROP DATABASE IF EXISTS statement

• Connects to master system database

Oracle

• Drops USER/schema (Oracle's equivalent of a database)

• Uses DROP USER ... CASCADE to remove all objects

• Supports Oracle 12c+ with Container Database (CDB) architecture

• Uses _ORACLE_SCRIPT session variable for non-C## users

• Important: Database names cannot contain hyphens (use underscores)

• Cannot drop system users (SYS, SYSTEM, ADMIN, XDB, etc.)

H2

• Deletes database files (.mv.db, .lock.db, .trace.db)

• Shows which files were deleted

• No server connection required

Warning

This operation is irreversible! Always ensure you have backups before dropping a database.

Best Practices

1. Always backup first:

2. Use --force carefully: Only in scripts where you're certain

3. Double-check environment: Especially important for production

Error Messages

"Database not found"

The database doesn't exist. No action needed.

"Access denied"

The database user doesn't have permission to drop databases. Grant DROP privileges to the user.

"Database in use"

Some databases prevent dropping while connections are active. The command attempts to close connections automatically.

"Invalid Oracle identifier" (Oracle-specific)

Database name contains invalid characters. Oracle usernames can only contain letters, numbers, and underscores.

Fix: Use underscores instead of hyphens:

"ORA-01918: user does not exist" (Oracle-specific)

The Oracle user/schema doesn't exist. No action needed.

"ORA-28014: cannot drop administrative user" (Oracle-specific)

Attempting to drop an Oracle system user. System users like SYS, SYSTEM, ADMIN, XDB cannot be dropped.

Fix: Verify you're targeting the correct database. System users are protected and cannot be removed.

Related Commands

• - Create a new database

• - Drop and recreate database

• - Backup before dropping