Testing Your Install

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.

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 the root of 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>

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.

CFML: app/views/say/goodbye.cfm

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

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

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's built in model provides your application with some simple and powerful functionality for interacting with databases. To get started, you will make some simple configurations, call some functions within your controllers, and that's it. Best yet, you will rarely ever need to write SQL code to get those redundant CRUD tasks out of the way.

Our Sample Application: User Management

We'll learn by building part of a sample user management application. This tutorial will teach you the basics of setting up a resource that interacts with the Wheels ORM.

Setting up the Data Source

By default, Wheels will connect to a data source wheels.dev. To change this default behavior, open the file at app/config/settings.cfm. In a fresh install of Wheels, you'll see the follwing code:

<cfscript>
	/*
		Use this file to configure your application.
		You can also use the environment specific files (e.g. app/config/production/settings.cfm) to override settings set here.
		Don't forget to issue a reload request (e.g. reload=true) after making changes.
		See https://guides.wheels.dev/2.5.0/v/3.0.0-snapshot/working-with-wheels/configuration-and-defaults for more info.
	*/

	/*
		You can change the "wheels.dev" value from the two functions below to set your datasource.
		You can change the the value for the "dataSourceName" to set a default datasource to be used throughout your application.
		You can also change the value for the "coreTestDataSourceName" to set your testing datasource.
	*/
	set(coreTestDataSourceName="wheels.dev");
	set(dataSourceName="wheels.dev");
    // set(dataSourceUserName="");
    // set(dataSourcePassword="");

	/*
		If you comment out the following line, Wheels will try to determine the URL rewrite capabilities automatically.
		The "URLRewriting" setting can bet set to "on", "partial" or "off".
		To run with "partial" rewriting, the "cgi.path_info" variable needs to be supported by the web server.
		To run with rewriting set to "on", you need to apply the necessary rewrite rules on the web server first.
	*/
	set(URLRewriting="On");

	// Reload your application with ?reload=true&password=wheels.dev
	set(reloadPassword="wheels.dev");

	// CLI-Appends-Here
</cfscript>

These lines provide Wheels with the necessary information about the data source, URL rewriting, and reload password for your application, and include the appropriate values. This may include values for dataSourceName, dataSourceUserName, and dataSourcePassword. More on URL rewriting and reload password later.

set(dataSourceName="back2thefuture");
// set(dataSourceUserName="marty");
// set(dataSourcePassword="mcfly");

Our Sample Data Structure

Wheels supports MySQL, SQL Server, PostgreSQL, and H2. It doesn't matter which DBMS you use for this tutorial; we will all be writing the same CFML code to interact with the database. Wheels does everything behind the scenes that needs to be done to work with each DBMS.

That said, here's a quick look at a table that you'll need in your database, named users:

Note a couple things about this users table:

1. The table name is plural.

2. The table has an auto-incrementing primary key named id.

Fortunately, there are ways of going outside of these conventions when you really need it. But let's learn the conventional way first. Sometimes you need to learn the rules before you can know how to break them.

Creating Routes for the users Resource

Next, open the file at app/config/routes.cfm. You will see contents similar to this:

mapper()
    .wildcard()
    .root(method = "get")
.end();

We are going to create a section of our application for listing, creating, updating, and deleting user records. In Wheels routing, this requires a plural resource, which we'll name users.

Because a users resource is more specific than the "generic" routes provided by Wheels, we'll list it first in the chain of mapper method calls:

mapper()
    .resources("users")
    .wildcard()
    .root(method = "get")
.end();

This will create URL endpoints for creating, reading, updating, and deleting user records:

• Name is referenced in your code to tell Wheels where to point forms and links.

• Method is the HTTP verb that Wheels listens for to match up the request.

• URL Path is the URL that Wheels listens for to match up the request.

Creating Users

First, let's create a simple form for adding a new user to the users table. To do this, we will use Wheels's form helper functions. Wheels includes a whole range of functions that simplifies all of the tasks that you need to display forms and communicate errors to the user.

Creating the Form

Now create a new file in app/views/users called new.cfm. This will contain the view code for our simple form.

Next, add these lines of code to the new file:

<cfoutput>

<h1>New User</h1>

#startFormTag(route="users")#
    <div>
        #textField(objectName="user", property="username", label="Username")#
    </div>

    <div>
        #textField(objectName="user", property="email", label="Email")#
    </div>

    <div>
        #passwordField(
            objectName="user",
            property="passwd",
            label="Password"
        )#
    </div>

    <div>#submitTag()#</div>
#endFormTag()#

</cfoutput>

Form Helpers

What we've done here is use form helpers to generate all of the form fields necessary for creating a new user in our database. It may feel a little strange using functions to generate form elements, but it will soon become clear why we're doing this. Trust us on this one… you'll love it!

Supplying the Form with Data

All of the form helper calls in our view specify an objectName argument with a reference to a variable named user. That means that we need to supply our view code with an object called user. Because the controller is responsible for providing the views with data, we'll set it there.

Create a new ColdFusion component at app/controllers/Users.cfc.

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

    function new() {
        user = model("user").new();
    }
}

Wheels will automatically know that we're talking about the users database table when we instantiate a user model. The convention: database tables are plural and their corresponding Wheels models are singular.

Why is our model name singular instead of plural? When we're talking about a single record in the users database, we represent that with an individual model object. So the users table contains many user objects. It just works better in conversation.

The Generated Form

Now when we run the URL at http://localhost/users/new, we'll see the form with the fields that we defined.

The HTML generated by your application will look something like this:

<h1>New User</h1>

<form action="/users" method="post">
    <div>
        <label for="user-username">
            Username
            <input id="user-username" type="text" value="" name="user&#x5b;username&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-email">
            Email
            <input id="user-email" type="text" value="" name="user&#x5b;email&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-passwd">
            Password
            <input id="user-passwd" type="password" value="" name="user&#x5b;passwd&#x5d;">
        </label>
    </div>

    <div><input value="Save&#x20;changes" type="submit"></div>
</form>

So far we have a fairly well-formed, accessible form, without writing a bunch of repetitive markup.

Handling the Form Submission

Next, we'll code the create action in the controller to handle the form submission and save the new user to the database.

function create() {
    user = model("user").create(params.user);

    redirectTo(
        route="users",
        success="User created successfully."
    );
}

Because we used the objectName argument in the fields of our form, we can access the user data as a struct in the params struct.

There are more things that we can do in the create action to handle validation, but let's keep it simple in this tutorial.

Listing Users

First, let's get the data that the listing needs. Create an action named index in the users controller like so:

function index() {
    users = model("user").findAll(order="username");
}

In the view at app/views/users/index.cfm, it's as simple as looping through the query and outputting the data

<cfoutput>

<h1>Users</h1>

<p>#linkTo(text="New User", route="newUser")#</p>

<table>
    <thead>
        <tr>
            <th>Username</th>
            <th>Email</th>
            <th colspan="2"></th>
        </tr>
    </thead>
    <tbody>
        <cfloop query="users">
            <tr>
                <td>
                    #EncodeForHtml(users.username)#
                </td>
                <td>
                    #EncodeForHtml(users.email)#
                </td>
                <td>
                    #linkTo(
                        text="Edit",
                        route="editUser",
                        key=users.id,
                        title="Edit #users.username#"
                    )#
                </td>
                <td>
                    #buttonTo(
                        text="Delete",
                        route="user",
                        key=users.id,
                        method="delete",
                        title="Delete #users.username#"
                    )#
                </td>
            </tr>
        </cfloop>
    </tbody>
</table>

</cfoutput>

Editing Users

We'll now show another cool aspect of form helpers by creating a screen for editing users.

Coding the Edit Form

You probably noticed in the code listed above that we'll have an action for editing a single users record. We used the linkTo() form helper function to add an "Edit" button to the form. This action expects a key as well.

Because in the linkTo() form helper function we specified the parameter key, Wheels adds this parameter into the URL when generating the route.

Wheels will automatically add the provided 'key' from the URL to the params struct in the controllers edit() function.

Given the provided key, we'll have the action load the appropriate user object to pass on to the view:

function edit() {
    user = model("user").findByKey(params.key);
}

The view at app/views/users/edit.cfm looks almost exactly the same as the view for creating a user:

<cfoutput>

<h1>Edit User #EncodeForHtml(user.username)#</h1>

#startFormTag(route="user", key=user.key(), method="patch")#
    <div>
        #textField(objectName="user", property="username", label="Username")#
    </div>

    <div>
        #textField(objectName="user", property="email", label="Email")#
    </div>

    <div>
        #passwordField(
            objectName="user",
            property="passwd",
            label="Password"
        )#
    </div>

    <div>#submitTag()#</div>
#endFormTag()#

</cfoutput>

But an interesting thing happens. Because the form fields are bound to the user object via the form helpers' objectName arguments, the form will automatically provide default values based on the object's properties.

With the user model populated, we'll end up seeing code similar to this:

<h1>Edit User Homer Simpson</h1>

<form action="/users/1" method="post">
    <input type="hidden" name="_method" value="patch">

    <div>
        <input type="hidden" name="user&#x5b;id&#x5d;" value="15">
    </div>

    <div>
        <label for="user-username">
            Name
            <input
                id="user-username"
                type="text"
                value="Homer Simpson"
                name="user&#x5b;username&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-email">
            Email
            <input
                id="user-email"
                type="text"
                value="homerj@nuclearpower.com"
                name="user&#x5b;email&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-passwd">
            Password
            <input
                id="user-passwd"
                type="password"
                value="donuts.mmm"
                name="user&#x5b;passwd&#x5d;">
        </label>
    </div>

    <div><input value="Save&#x20;changes" type="submit"></div>
</form>

Pretty cool, huh?

Opportunities for Refactoring

There's a lot of repetition in the new and edit forms. You'd imagine that we could factor out most of this code into a single view file. To keep this tutorial from becoming a book, we'll just continue on knowing that this could be better.

Handing the Edit Form Submission

Now we'll create the update action. This will be similar to the create action, except it will be updating the user object:

function update() {
    user = model("user").findByKey(params.key);
    user.update(params.user);

    redirectTo(
        route="editUser",
        key=user.id,
        success="User updated successfully."
    );
}

Deleting Users

Notice in our listing above that we have a delete action. Here's what it would look like:

function delete() {
    user = model("user").findByKey(params.key);
    user.delete();

    redirectTo(
        route="users",
        success="User deleted successfully."
    );
}

Database Says Hello

We've shown you quite a few of the basics in getting a simple user database up and running. We hope that this has whet your appetite to see some of the power packed into the Wheels framework. There's plenty more.

Be sure to read on to some of the related chapters listed below to learn more about working with Wheels's ORM.

Starting a local development server

With CommandBox, we don't need to have Lucee or Adobe ColdFusion installed locally. With a simple command, we can make CommandBox go and get the CFML engine we've requested, and quickly create a server running on Undertow. Make sure you're in the root of your website, and then run:

The server will then start on a random port on 127.0.0.1 based the configuration from the server.json file that is in the root of your application that comes with wheels. We can add various options to server.json to customize our server. Your default server.json will look something like this:

{
    "name":"wheels",
    "web":{
        "host":"localhost",
        "webroot":"public",
        "rewrites":{
            "enable":true,
            "config":"public/urlrewrite.xml"
        }
    },
    "app":{
        "cfengine":"lucee"
    }
}

In this server.json file, the server name is set to wheels, meaning I can now start the server from any directory by simply calling start myApp. We don't have any port specified, but you can specify any port you want. Lastly, we have URL rewriting enabled and pointed the URL rewrite configuration file to public/urlrewrite.xml, which is included starting from Wheels 2.x.

Using custom host names

Controlling local servers

Obviously, anything you start, you might want to stop. Servers can be stopped either via right/ctrl clicking on the icon in the taskbar, or by the stop command. To stop a server running in the current directory issue the following:

You can also stop a server from anywhere by using its name:

If you want to see what server configurations exist on your system and their current status, simply do server list

myapp (stopped)
 http://127.0.0.1:60000
 Webroot: /Users/wheels/Documents/myapp

myAPI (stopped)
 http://127.0.0.1:60010
 Webroot: /Users/wheels/Documents/myAPI

megasite (stopped)
 http://127.0.0.1:61280
 CF Engine: lucee 4.5.4+017
 Webroot: /Users/wheels/Documents/megasite

awesomesite (stopped)
 http://127.0.0.1:60015
 CF Engine: lucee 4.5.4+017
 Webroot: /Users/wheels/Documents/awesomeo

To remove a server configuration from the list, you can use server forget myapp. Note the status of the servers on the list are somewhat unreliable, as it only remembers the last known state of the server: so if you start a server and then turn off your local machine, it may still remember it as running when you turn your local machine back on, which is why we recommend the use of force: true in the server.json file.

Specifying different CF engines

By default, CommandBox will run Lucee (version 6.x at time of writing). You may wish to specify an exact version of Lucee, or use Adobe ColdFusion. We can do this via either setting the appropriate cfengine setting in server.json, or at runtime with the cfengine= argument.

Or via server.json

{
    "name":"myApp",
    "force":true,
    "web":{
        "http":{
            "host":"localhost",
            "port":60000
        },
        "rewrites":{
            "enable":true,
            "config":"urlrewrite.xml"
        }
    },
    "app":{
        "cfengine":"adobe@2018"
    },
}

You can of course run multiple servers, so if you need to test your app on Lucee 5.x, Lucee 6.x and Adobe 2018, you can just start three servers with different cfengine= arguments!

By default, the Lucee server that CommandBox starts includes all the essential Lucee extensions you need, but if need to minimize the size of the Lucee instance you launch, then you can use Lucee-Light by specifying cfengine=lucee-light in your server.json file. Wheels can run just fine on lucee-light (which is after all, Lucee, minus all the extensions) but at a minimum, requires the following extensions to be installed as dependencies in your box.json. Please note you may have to add any drivers you need for your database to this list as well.

"dependencies":{
    "lucee-image":"lex:https://ext.lucee.org/lucee.image.extension-1.0.0.35.lex",
    "lucee-zip": "lex:https://ext.lucee.org/compress-extension-1.0.0.2.lex",
    "lucee-esapi": "lex:https://ext.lucee.org/esapi-extension-2.1.0.18.lex"
}

Once added to your box.json file, while the server is running, just do box install, which will install the dependencies, and load them into the running server within 60 seconds.

Alternatively you can download the extensions and add them manually to your server root's deploy folder (i.e \WEB-INF\lucee-server\deploy)

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

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.

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

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);
    }
}

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.

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

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:

Operating Systems

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

Web Servers

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+

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.

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.

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.

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

3. Setup the Database (Optional)

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

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!

Wheels 2.x

Wheels 1.x

CRUD series

"Building a Social Network"

Chris Peters adds data validation to the user registration form

Other

Generally speaking, upgrading Wheels is as easy as replacing the wheels folder, especially for those small maintenance releases: however, there are usually exceptions in minor point releases (i.e, 1.1 to 1.3 required replacing other files outside the wheels folder). The notes below detail those changes.

Upgrading to 3.0.0

Compatibility Changes

Adobe Coldfusion 2016 and below are no longer compatible with Wheels going forward. Consequently, these versions have been removed from the Wheels Internal Test Suites.

Code changes

• After installing Wheels 3.x, you'll have to run box install to intall testbox and wirebox in your application as they are not shipped with Wheels but are rather listed in box.json file as dependencies to be installed.

• Added Mappings for the app, vendor, wheels, wirebox, testbox and tests directories.

• root.cfm and rewrite.cfm have been removed. All the requests are now being redirected only through public/index.cfm.

Changes to the wheels folder

• Replace the wheels folder with the new one from the 3.0.0 download.

• Move the wheels folder inside the vendor folder.

Changes outside the wheels folder

• Moved the config, controllers, events, global, lib, migrator, models, plugins, snippets and views directories inside the app directory.

• Moved the files, images, javascripts, miscellaneous, stylesheets directories and Application.cfc, index.cfm and urlrewrite.xml files into the public folder.

Upgrading to 2.3.x

Replace the wheels folder with the new one from the 2.3.0 download.

Upgrading to 2.2.x

Replace the wheels folder with the new one from the 2.2.0 download.

Upgrading to 2.1.x

Replace the wheels folder with the new one from the 2.1.0 download.

Code changes

• Rename any instances of findLast() to findLastOne()

Changes outside the wheels folder

• Create /events/onabort.cfm to support the onAbort method

Upgrading to 2.0.x

As always, the first step is to replace the wheels folder with the new one from the 2.0 download.

Other major changes required to upgrade your application are listed in the following sections.

Supported CFML Engines

Wheels 2.0 requires one of these CFML engines:

• Lucee 4.5.5.006 + / 5.2.1.9+

• Adobe ColdFusion 10.0.23 / 11.0.12+ / 2016.0.4+

We've updated our minimum requirements to match officially supported versions from the vendors. (For example, Adobe discontinued support for ColdFusion 10 in May 2017, which causes it to be exposed to security exploits in the future. We've included it in 2.0 but it may be discontinued in a future version)

Changes outside the wheels folder

• The events/functions.cfm file has been moved to global/functions.cfm.

• The models/Model.cfc file should extend wheels.Model instead of Wheels (models/Wheels.cfc can be deleted).

• The controllers/Controller.cfc file should extend wheels.Controller instead of Wheels(controllers/Wheels.cfc can be deleted).

• The init function of controllers and models must be renamed to config.

• The global setting modelRequireInit has been renamed to modelRequireConfig.

• The global setting cacheControllerInitialization has been renamed to cacheControllerConfig.

• The global setting cacheModelInitialization has been renamed to cacheModelConfig.

• The global setting clearServerCache has been renamed to clearTemplateCache.

• The updateProperties() method has been removed, use update() instead.

• The renderPage function has been renamed to renderView

• includePartial() now requires the partial and query arguments to be set (if using a query)

Routing

By default, this is limited to GET requests for security reasons.

Cross-Site Request Forgery (CSRF) Protection

It is strongly recommended that you enable Wheels 2.0's built-in CSRF protection.

For many applications, you need to follow these steps:

4. Update your route definitions to enforce HTTP verbs on actions that manipulate data (get, post, patch, delete, etc.)

5. Make sure that forms within the application are POSTing data to the actions that require post, patch, and delete verbs.

Database Migrations

If you have previously been using the dbmigrate plugin, you can now use the inbuilt version within the Wheels 2 core.

Database Migration files in /db/migrate/ should now be moved to /migrator/migrations and extend wheels.migrator.Migration, not plugins.dbmigrate.Migration which can be changed with a simple find and replace. Note: Oracle is not currently supported for Migrator.

Upgrading to 1.4.x

1. Replace the wheels folder with the new one from the 1.4 download.

2. Replace URL rewriting rule files – i.e, .htaccess, web.config, IsapiRewrite.ini

In addition, if you're upgrading from an earlier version of Wheels, we recommend reviewing the instructions from earlier reference guides below.

Upgrading to 1.3.x

If you are upgrading from Wheels 1.1.0 or newer, follow these steps:

1. Replace the wheels folder with the new one from the 1.3 download.

2. Replace the root root.cfm file with the new one from the 1.3 download.

3. Remove the <cfheader> calls from the following files:

   • events/onerror.cfm

   • events/onmaintenance.cfm

   • events/onmissingtemplate.cfm

In addition, if you're upgrading from an earlier version of Wheels, we recommend reviewing the instructions from earlier reference guides below.

Note: To accompany the newest 1.1.x releases, we've highlighted the changes that are affected by each release in this cycle.

Upgrading to 1.1.x

If you are upgrading from Wheels 1.0 or newer, the easiest way to upgrade is to replace the wheels folder with the new one from the 1.1 download. If you are upgrading from an earlier version, we recommend reviewing the steps outlined in Upgrading to Wheels 1.0.

Note: To accompany the newest 1.1.x releases, we've highlighted the changes that are affected by each release in this cycle.

Plugin Compatibility

Be sure to review your plugins and their compatibility with your newly-updated version of Wheels. Some plugins may stop working, throw errors, or cause unexpected behavior in your application.

Supported System Changes

• 1.1: The minimum Adobe ColdFusion version required is now 8.0.1.

• 1.1: The minimum Railo version required is now 3.1.2.020.

• 1.1: The H2 database engine is now supported.

File System Changes

• 1.1: The .htaccess file has been changed. Be sure to copy over the new one from the new version 1.1 download and copy any addition changes that you may have also made to the original version.

Database Structure Changes

• 1.1: By default, Wheels 1.1 will wrap database queries in transactions. This requires that your database engine supports transactions. For MySQL in particular, you can convert your MyISAM tables to InnoDB to be compatible with this new functionality. Otherwise, to turn off automatic transactions, place a call to set(transactionMode="none").

• 1.1: Binary data types are now supported.

CFML Code Changes

Model Code

• 1.1: Validations will be applied to some model properties automatically. This may cause unintended behavior with your validations. To turn this setting off, call set(automaticValidations=false) in config/settings.cfm.

• 1.1: The class argument in hasOne(), hasMany(), and belongsTo() has been deprecated. Use the modelName argument instead.

• 1.1: afterFind() callbacks no longer require special logic to handle the setting of properties in objects and queries. (The "query way" works for both cases now.) Because arguments will always be passed in to the method, you can't rely on StructIsEmpty() to determine if you're dealing with an object or not. In the rare cases that you need to know, you can now call isInstance() or isClass() instead.

• 1.1: On create, a model will now set the updatedAt auto-timestamp to the same value as the createdAt timestamp. To override this behavior, call set(setUpdatedAtOnCreate=false) in config/settings.cfm.

View Code

• 1.1: Object form helpers (e.g. textField() and radioButton()) now automatically display a label based on the property name. If you left the label argument blank while using an earlier version of Wheels, some labels may start appearing automatically, leaving you with unintended results. To stop a label from appearing, use label=false instead.

• 1.1: The contentForLayout() helper to be used in your layout files has been deprecated. Use the includeContent() helper instead.

• 1.1: In production mode, query strings will automatically be added to the end of all asset URLs (which includes JavaScript includes, stylesheet links, and images). To turn off this setting, call set(assetQueryString=false) in config/settings.cfm.

• 1.1: stylesheetLinkTag() and javaScriptIncludeTag() now accept external URLs for the source/sources argument. If you manually typed out these tags in previous releases, you can now use these helpers instead.

• 1.1: flashMessages(), errorMessageOn(), and errorMessagesFor() now create camelCased class attributes instead (for example error-messages is now errorMessages). The same goes for the class attribute on the tag that wraps form elements with errors: it is now fieldWithErrors.

Controller Code

• 1.1.1: The if argument in all validation functions is now deprecated. Use the condition argument instead.

Upgrading to 1.0.x

Our listing of steps to take while upgrading your Wheels application from earlier versions to 1.0.x.

Upgrading from an earlier version of 1.x? Then the upgrade path is simple. All you need to do is replace the wheels folder with the new wheels folder from the download.

The easiest way to upgrade is to setup an empty website, deploy a fresh copy of Wheels 1.0, and then transfer your application code to it. When transferring, please make note of the following changes and make the appropriate changes to your code.

Note: To accompany the newest 1.0 release, we've highlighted the changes that are affected by that release.

Supported System Changes

• 1.0: URL rewriting with IIS 7 is now supported.

• 1.0: URL rewriting in a sub folder on Apache is now supported.

• ColdFusion 9 is now supported.

• Oracle 10g or later is now supported.

• PostgreSQL is now supported.

• Railo 3.1 is now supported.

File System Changes

• 1.0: There is now an app.cfm file in the config folder. Use it to set variables that you'd normally set in Application.cfc (i.e., this.name, this.sessionManagement, this.customTagPaths, etc.)

• 1.0: There is now a web.config file in the root.

• 1.0: There is now a Wheels.cfc file in the models folder.

• 1.0: The Wheels.cfc file in the controllers folder has been updated.

• 1.0: The IsapiRewrite4.ini and .htaccess files in the root have both been updated.

• The controller folder has been changed to controllers.

• The model folder has been changed to models.

• The view folder has been changed to views.

• Rename all of your CFCs in models and controllers to UpperCamelCase. So controller.cfc will become Controller.cfc, adminUser.cfc will become AdminUser.cfc, and so on.

• All images must now be stored in the images folder, files in the files folder, JavaScript files in the javascripts folder, and CSS files in the stylesheets folder off of the root.

Database Structure Changes

• deletedOn, updatedOn, and createdOn are no longer available as auto-generated fields. Please change the names to deletedAt, updatedAt, and createdAt instead to get similar functionality, and make sure that they are of type datetime, timestamp, or equivalent.

CFML Code Changes

Config Code

• 1.0: The action of the default route (home) has changed to wheels. The way configuration settings are done has changed quite a bit. To change a Wheels application setting, use the new set() function with the name of the Wheels property to change. (For example, <cfset set(dataSourceName="mydatasource")>.) To see a list of available Wheels settings, refer to the Configuration and Defaults chapter. Model Code

• 1.0: The extends attribute in models/Model.cfc should now be Wheels.

• findById() is now called findByKey(). Additionally, its id argument is now named key instead. For composite keys, this argument will accept a comma-delimited list.

• When using a model's findByKey() or findOne() functions, the found property is no longer available. Instead, the functions return false if the record was not found.

• A model's errorsOn() function now always returns an array, even if there are no errors on the field. When there are errors for the field, the array elements will contain a struct with name, fieldName, and message elements.

• The way callbacks are created has changed. There is now a method for each callback event ( beforeValidation(), beforeValidationOnCreate(), etc.) that should be called from your model's init() method. These methods take a single argument: the method within your model that should be invoked during the callback event. See the chapter on Object Callbacks for an example.

View Code

• 1.0: The contents of the views/wheels folder have been changed.

• The wrapLabel argument in form helpers is now replaced with labelPlacement. Valid values for labelPlacement are before, after, and around.

• The first argument for includePartial() has changed from name to partial. If you're referring to it through a named argument, you'll need to replace all instances with partial.

• The variable that keeps a counter of the current record when using includePartial() with a query has been renamed from currentRow to current.

• There is now an included wheels view folder in views. Be sure to copy that into your existing Wheels application if you're upgrading.

• The location of the default layout has changed. It is now stored at /views/layout.cfm. Now controller-specific layouts are stored in their respective view folder as layout.cfm. For example, a custom layout for www.domain.com/about would be stored at /views/about/layout.cfm.

• In linkTo(), the id argument is now called key. It now accepts a comma-delimited list in the case of composite keys.

• The linkTo() function also accepts an object for the key argument, in which case it will automatically extract the keys from it for use in the hyperlink.

• The linkTo() function can be used only for controller-, action-, and route-driven links now. * The url argument has been removed, so now all static links should be coded using a standard "a" tag.

Controller Code

URL/Routing

• The default route for Wheels has changed from [controller]/[action]/[id] to [controller]/[action]/[key]. This is to support composite keys. The params.id value will now only be available as params.key.

• You can now pass along composite keys in the URL. Delimit multiple keys with a comma. (If you want to use this feature, then you can't have a comma in the key value itself).

Welcome to the comprehensive documentation for the Wheels CLI - a powerful command-line interface for the Wheels framework.

What is Wheels CLI?

Wheels CLI is a CommandBox module that provides a comprehensive set of tools for developing Wheels applications. It offers:

• Code Generation - Quickly scaffold models, controllers, views, and complete CRUD operations

• Database Migrations - Manage database schema changes with version control

• Testing Tools - Run tests, generate coverage reports, and use watch mode

• Development Tools - File watching, automatic reloading, and development servers

• Code Analysis - Security scanning, performance analysis, and code quality checks

• Plugin Management - Install and manage Wheels plugins

• Environment Management - Switch between development, testing, and production

Documentation Structure

Complete reference for all CLI commands organized by category:

• Core Commands - Essential commands like init, reload, watch

Get up and running with Wheels CLI in minutes. Learn how to:

• Install Wheels CLI

• Create your first application

• Generate CRUD scaffolding

• Run tests and migrations

📖 Guides

Development Guides

Best Practices

📋 Reference

Key Features

🛠️ Code Generation

Generate complete applications or individual components:

# Create new application
wheels new blog

# Generate complete CRUD scaffolding
wheels scaffold post --properties="title:string,content:text,published:boolean"

# Generate individual components
wheels generate model user
wheels generate controller users --rest
wheels generate view users index

🗄️ Database Migrations

Manage database schema changes:

# Create migration
wheels dbmigrate create table posts

# Run migrations
wheels dbmigrate latest

# Check status
wheels dbmigrate info

🧪 Testing

Comprehensive testing support:

# Run all tests
wheels test run

# Watch mode
wheels test run --watch

# Generate coverage
wheels test coverage

👀 Development Tools

Enhance your development workflow:

# Watch for file changes
wheels watch

# Reload application
wheels reload development

# Analyze code
wheels analyze code
wheels security scan

Getting Started

1. Install CommandBox (if not already installed):

   Copy

   # macOS/Linux
   curl -fsSl https://downloads.ortussolutions.com/debs/gpg | sudo apt-key add -
   or
     brew install commandbox
   
   # Windows
   choco install commandbox

2. Install Wheels CLI:

   Copy

   box install wheels-cli

3. Create Your First App:

   Copy

   wheels new myapp
   cd myapp
   box server start

4. Explore Commands:

   Copy

   wheels --help
   wheels generate --help
   wheels dbmigrate --help

Version Compatibility

Community & Support

Contributing

• Reporting issues

• Suggesting features

• Submitting pull requests

• Creating custom commands

Recent Updates

Version 3.0.0

• 🆕 Modernized service architecture

• 🆕 Enhanced testing capabilities with watch mode

• 🆕 Security scanning and performance optimization

• 🆕 Plugin and environment management

• 🆕 Improved code generation with more options

• 🔧 Better error handling and user feedback

• 📚 Comprehensive documentation

Quick Links

License

Complete reference for all Wheels CLI commands organized by category.

Quick Reference

Most Common Commands

Core Commands

Essential commands for managing your Wheels application.

Code Generation

Commands for generating application code and resources.

Generator Options

Common options across generators:

• --force - Overwrite existing files

• --help - Show command help

Database Commands

Commands for managing database schema and migrations.

Migration Management

Migration Creation

Database Operations

Testing Commands

Commands for running and managing tests.

Test Options

• --watch - Auto-run on changes

• --reporter - Output format (simple, json, junit)

• --bundles - Specific test bundles

• --labels - Filter by labels

Configuration Commands

Commands for managing application configuration.

Environment Management

Commands for managing development environments.

Plugin Management

Commands for managing Wheels plugins.

Plugin Options

• --global - Install/list globally

• --dev - Development dependency

Code Analysis

Commands for analyzing code quality and patterns.

Security Commands

Commands for security scanning and hardening.

Security Options

• --fix - Auto-fix issues

• --path - Specific path to scan

Performance Commands

Commands for optimizing application performance.

Documentation Commands

Commands for generating and serving documentation.

Documentation Options

• --format - Output format (html, markdown)

• --output - Output directory

• --port - Server port

CI/CD Commands

Commands for continuous integration and deployment workflows.

Docker Commands

Commands for Docker container management and deployment.

Deployment Commands

Commands for managing application deployments.

Deployment Options

• --environment - Target environment

• --force - Force deployment

• --dry-run - Preview changes without deploying

Command Patterns

Getting Help

Every command supports --help:

wheels [command] --help
wheels generate controller --help
wheels dbmigrate create table --help

Command Aliases

Many commands have shorter aliases:

wheels g controller users  # Same as: wheels generate controller users
wheels g model user       # Same as: wheels generate model user
wheels new myapp         # Same as: wheels generate app myapp

Common Workflows

Creating a new feature:

wheels scaffold product --properties="name:string,price:decimal"
wheels dbmigrate latest
wheels test run

Starting development:

wheels watch              # Terminal 1
box server start         # Terminal 2
wheels test run --watch  # Terminal 3

Deployment preparation:

wheels test run
wheels security scan
wheels optimize performance
wheels dbmigrate info

Environment Variables

Exit Codes

Command Status Notes

Some commands in the Wheels CLI are currently in various states of development or maintenance:

Broken Commands

• wheels docs - Base documentation command is currently broken

• wheels generate api-resource - API resource generation is currently broken

Disabled Commands

The following commands exist in the codebase but are currently disabled:

• Some CI and Docker commands have disabled variants in the codebase

These commands may be re-enabled in future versions of Wheels.

See Also

Reload the Wheels application in different modes.

Synopsis

wheels reload [mode] [password]

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.

Arguments

Options

Reload Modes

Development Mode

wheels reload development

• Enables debugging

• Shows detailed error messages

• Disables caching

• Ideal for active development

Testing Mode

wheels reload testing

• Optimized for running tests

• Consistent environment

• Predictable caching

Maintenance Mode

wheels reload maintenance

• Shows maintenance page to users

• Allows admin access

• Useful for deployments

Production Mode

wheels reload production

• Full caching enabled

• Minimal error information

• Optimized performance

Examples

Basic reload (development mode)

wheels reload

Reload in production mode

wheels reload production

Reload with custom password

wheels reload development mySecretPassword

Reload for testing

wheels reload testing

Security

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

• Default password from .wheels-cli.json is used if not specified

• Password is sent securely to the application

Configuration

Set the default reload password in .wheels-cli.json:

{
  "reload": "mySecretPassword"
}

Or 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

Common Issues

• Invalid password: Check password in settings

• Timeout: Large applications may take time to reload

• Memory issues: Monitor JVM heap during reload

See Also

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 sets up the necessary configuration files and creates a .wheels-cli.json file in your project root.

Arguments

Options

Examples

Initialize current directory

Initialize with custom name

Initialize specific directory

Initialize with custom reload password

Initialize without creating folders

What It Does

1. Creates .wheels-cli.json configuration file

2. Sets up application name and version

3. Configures reload password

4. Optionally creates standard Wheels directory structure:

   • /config

   • /controllers

   • /models

   • /views

   • /tests

   • /plugins

Configuration File

The generated .wheels-cli.json contains:

Notes

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

• The reload password is used for the wheels reload command

• If folders already exist, they won't be overwritten

See Also

Display CLI and Wheels framework version information.

Synopsis

Description

The wheels info command displays detailed information about your Wheels CLI installation, the current Wheels application, and the environment.

Options

Output

The command displays:

1. CLI Information

   • Wheels CLI version

   • CommandBox version

   • Installation path

2. Application Information (if in a Wheels app directory)

   • Application name

   • Wheels framework version

   • Reload password status

   • Configuration file location

3. Environment Information

   • CFML engine and version

   • Operating system

   • Java version

Example Output

Use Cases

• Verify CLI installation

• Check Wheels framework version

• Troubleshoot environment issues

• Confirm application configuration

Notes

• Run from within a Wheels application directory for full information

• Application information only appears when .wheels-cli.json exists

• Sensitive information like passwords are masked

See Also

Remove generated code and files.

Synopsis

Description

The wheels destroy command reverses the actions of generator commands, removing files and code that were previously generated. It's useful for cleaning up mistakes or removing features.

Arguments

Resource Types

• controller - Remove a controller and its views

• model - Remove a model

• view - Remove a specific view

• scaffold - Remove entire scaffolding

• migration - Remove a migration file

• test - Remove test files

Options

Examples

Remove a controller

Removes:

• /controllers/Users.cfc

• /views/users/ directory and all views

Remove a model

Removes:

• /models/User.cfc

• Related test files

Remove scaffolding

Removes:

• /models/Product.cfc

• /controllers/Products.cfc

• /views/products/ directory

• All CRUD views

• Test files

Remove a specific view

Removes:

• /views/users/edit.cfm

Remove a migration

Removes:

• Migration file from /db/migrate/

Dry run to preview

Shows what would be removed without deleting

Force removal without confirmation

Confirmation

By default, the command asks for confirmation:

Safety Features

1. Confirmation Required: Always asks unless --force is used

2. Dry Run Mode: Preview changes with --dry-run

3. No Database Changes: Only removes files, not database tables

4. Git Awareness: Warns if files have uncommitted changes

What's NOT Removed

• Database tables or columns

• Routes (must be manually removed)

• References in other files

• Git history

Best Practices

1. Always use --dry-run first

2. Commit changes before destroying

3. Check for file dependencies

4. Update routes manually

5. Remove database tables separately

Common Workflows

Undo a scaffold

Clean up a mistake

Notes

• Cannot be undone - files are permanently deleted

• Does not remove custom code added to generated files

• Works only with files created by generators

See Also

Manage application dependencies.

Synopsis

Description

The wheels deps command helps manage your Wheels application's dependencies, including CFML modules, Wheels plugins, and JavaScript packages.

Options

Features

1. Dependency Analysis

   • Scans box.json for CFML dependencies

   • Checks package.json for Node.js dependencies

   • Identifies Wheels plugins

2. Version Checking

   • Compares installed vs required versions

   • Identifies outdated packages

   • Shows available updates

3. Dependency Installation

   • Installs missing dependencies

   • Updates outdated packages

   • Resolves version conflicts

Output Example

Dependency Sources

CFML Dependencies (box.json)

Wheels Plugins

Located in /plugins directory or installed via ForgeBox.

Node Dependencies (package.json)

Commands Executed

Behind the scenes, wheels deps runs:

Use Cases

• Check dependency status before deployment

• Ensure all team members have same dependencies

• Update dependencies safely

• Troubleshoot missing functionality

Best Practices

1. Run after pulling new code

2. Check before deployments

3. Update dependencies incrementally

4. Test after updates

Notes

• Requires box.json for CFML dependencies

• Optional package.json for Node dependencies

• Some plugins may require manual configuration

See Also

Watch for file changes and automatically reload the application.

Synopsis

Description

The wheels watch command monitors your application files for changes and automatically triggers actions like reloading the application or running tests. This provides a smooth development workflow with instant feedback.

Arguments

Options

Examples

Basic file watching

Watches current directory for .cfc, .cfm, and .json changes

Watch specific directory