Request Handling

Wheels is quite simple when it comes to figuring out how incoming requests map
to code in your application. Let's look at a URL for an e-commerce website and
dissect it a little.
But before we do that, a quick introduction to URLs in Wheels is in order.
A Wheels URL
URLs in Wheels generally look something like this:
http://localhost/index.cfm/shop/products
It's also possible that the URLs will look like this in your application:
http://localhost/index.cfm?controller=shop&action=products
This happens when your web server does not support the cgi.path_info variable.
Regardless of your specific setup, Wheels will try to figure out how to handle
the URLs. If Wheels fails to do this properly (i.e. you know that your web
server supports cgi.path_info, but Wheels insists on creating the URLs with
the query string format), you can override it by setting URLRewriting in
config/settings.cfm to either On, Partial, or Off. The line of code should
look something like this:
set(URLRewriting="Partial");
"Partial URL Rewriting" is what we call that first URL up there with the
/index.cfm/ format.
In the example URLs used above, shop is the name of the controller to call,
and products is the name of the action to call on that controller.
Model-View-Controller Explained
Unless you're familiar with the Model-View-Controller pattern, you're probably
wondering what controllers and actions are.
Put very simply, a controller takes an incoming request and, based on the
parameters in the URL, decides what (if any) data to get from the model (which
in most cases means your database), and decides which view (which in most cases
means a CFML file producing HTML output) to display to the user.
An action is an entire process of executing code in the controller, including
a view file and rendering the result to the browser. As you will see in the
example below, an action usually maps directly to one specific function with the
same name in the controller file.
Creating URLs
Mapping an incoming URL to code is only one side of the equation. You will also
need a way to create these URLs. This is done through a variety of different
functions like linkTo() (for creating links), startFormTag() (for
creating forms), and redirectTo() (for redirecting users), to name a few.
Internally, all of these functions use the same code to create the URL, namely
the URLFor() function. The URLFor() function accepts a controller and
an action argument, which are what you will use most of the time. It has a lot
of other arguments and does some neat stuff (like defaulting to the current
controller when you don't specifically pass one in). So check out the
documentation for the URLFor() function for all the details.
By the way, by using URL rewriting in Apache or IIS, you can completely get rid
of the index.cfm part of the URL so that
http://localhost/index.cfm/shop/products becomes
http://localhost/shop/products. You can read more about this in the
URL Rewriting chapter.
For the remainder of this chapter, we'll type out the URLs in this shorter and
prettier way.
A Wheels Page
Let's look a little closer at what happens when Wheels receives this example
incoming request.
First, it will create an instance of the shop controller
(controllers/Shop.cfc) and call the function inside it named products.
Let's show how the code for the products function could look to make it more
clear what goes on:
Shop.cfc
component extends="Controller" {
​
    function products() {
        renderView(controller="shop", action="products");
    }
​
}
The only thing this does is specify the view page to render using the
renderView() function.
The renderView() function is available to you because the shop controller extends the main Wheels Controllercomponent. Don't forget to include that extends attribute in your cfcomponent call as you build your controllers!
So, how does renderView() work? Well, it accepts the arguments controller and action (among others, such as route), and, based on these, it will try to include a view file. In our case, the view file is stored at views/shop/products.cfm.
You can read the chapter about Rendering Content for more information about the renderView() function.
It's important to note that the renderView() function does not cause any controller actions or functions to be executed. It just specifies what view
files to get content from. Keep this in mind going forward because it's a common assumption that it does. (Especially when you want to include the view page for another action, it's easy to jump to the incorrect conclusion that the code for that action would also get executed.)
Wheels Conventions
Because Wheels favors convention over configuration, we can remove a lot of the
code in the example above, and it will still work because Wheels will just guess
what your intention is. Let's have a quick look at exactly what code can be
removed and why.
The first thing Wheels assumes is that if you call renderView() without
arguments, you want to include the view page for the current controller and
action.
Therefore, the code above can be changed to:
Shop.cfc
component extends="Controller" {
​
    function products() {
        renderView();
    }
​
}
… and it will still work just fine.
Does Wheels assume anything else? Sure it does. You can actually remove the
entire renderView() call because Wheels will assume that you always want to call a view page when the processing in the controller is done. Wheels will call
it for you behind the scenes.
That leaves you with this code:
Shop.cfc
component extends="Controller" {
​
    function products() { 
    }
​
}
That looks rather silly, a products function with no code whatsoever. What do
you think will happen if you just remove that entire function, leaving you with
this code?
Shop.cfc
component extends="Controller" { 
​
}
…If you guessed that Wheels will just assume you don't need any code for the
products action and just want the view rendered directly, then you are correct.
In fact, if you have a completely blank controller like the one above, you can
delete it from the file system altogether!
This is quite useful when you're just adding simple pages to a website and you
don't need the controller and model to be involved at all. For example, you can
create a file named about.cfm in the views/home folder and access it at
http://localhost/home/about without having to create a specific controller
and/or action for it, assuming you're still using wildcard routing.
This also highlights the fact that Wheels is a very easy framework to get
started in because you can basically program just as you normally would by
creating simple pages like this and then gradually "Wheelsifying" your code as
you learn the framework.
The params Struct
Besides making sure the correct code is executed, Wheels also does something
else to simplify request handling for you. It combines the url and form
scopes into one. This is something that most CFML frameworks do as well. In
Wheels, it is done in the params struct.
The params struct is available to you in the controller and view files but
not in the model files. (It's considered a best practice to not mix your request
handling with your business logic.) Besides the form and url scope
variables, the params struct also contains the current controller and action
name for easy reference.
If the same variable exists in both the url and form scopes, the value in
the form scope will take precedence.
To make this concept easier to grasp, imagine a login form on your website that
submits to http://localhost/account/login?sendTo=dashboard with the variables
username and password present in the form. Your params struct would look
like this:
Name
Value
params.controller
account
params.action
login
params.sendTo
dashboard
params.username
joe
params.password
1234
Now instead of accessing the variables as url.sendTo, form.username, etc.,
you can just use the params struct for all of them instead.
This concept becomes even more useful once we start getting into creating forms
specifically meant for accessing object properties. But let's save the details
of all that for the Form Helpers and Showing Errors chapter.
JSON as part of the request body
If you're constructing a JSON API, you're inevitably going to come across how to deal with "incoming" json packets to your routing endpoints. Instead of having to test each request with whether it's valid json etc, CFWheels will automatically map the JSON body in a request to the params struct, as long as it has application/json as it's mime type.
So in the same way that the url and form scopes are merged, so a valid json body would be. The exception to the rule is when a javascript array is the root element, where it's then added to params._json to follow Rails conventions. (For obvious reasons, we can't merge an array into a struct!)
NOTE
The mapping of a json array to params._json was introduced in CFWheels 2.1
Routing
For more advanced URL-to-code mappings, you are encourage to use a concept called routing.
It allows for you to fully customize every URL in your application, including which HTTP verb can be used. You can read more about this in the chapter called Routing.

Working with CFWheels - Previous

Documenting your Code

Next - Handling Requests with Controllers

Rendering Content

Last modified 3mo ago

Export as PDF

Copy link

Edit on GitHub

Outline

A Wheels URL

Model-View-Controller Explained

JSON as part of the request body

Routing