You are viewing documentation for v1.0.x. Change

Pages

Where to place your view files and what to put in them.

We've talked previously about how the controller is responsible for deciding which view files to render to the user. Read the Rendering Content chapter if you need to refresh your memory about that topic.

In this chapter, we'll explain exactly where to place these files and what to put in them.

Where to Place the Files

In the simplest case, your controller action (typically a function inside your controller CFC file) will have a view file associated with it. As explained in the Rendering Content chapter, this file will be included automatically at the end of the controller action code. So if you're running the show action in the blog controller, for example, Wheels will include the views/blog/show.cfm file.

Some rules can be spotted here:

  • All view files live in the views folder.
  • Each controller gets a subfolder named after it in the views folder.
  • The view file to include is just a regular .cfm file named after the action.

For creating standard pages, your work process will likely consist of the following steps:

  1. Create the controller action (a function in the controller CFC file).
  2. Create the corresponding view file for it (a .cfm file in the controller's view folder).

There can be some exceptions to this process though, so let's go through some possible scenarios.

Controller Actions Without Associated View Files

Not all controller actions need a corresponding view file. Consider the case where you process a form submission. To make sure it's not possible for the user to refresh the page and cause multiple submissions, you may choose to perform the form processing and then send the user directly to another page using the redirectTo() function.

Rendering the View File for Another Action

Sometimes you want the controller action to render the view file for a different action than the one currently executing. This is especially common when your application processes a form and the user makes an input error. In this case, you'll probably choose to have your application display the same form again for correction.

In this case, you can use the renderPage() function and specify a different action in the action argument (which will include the view page for that action but not run the controller code for it).

Sharing a View File Between Actions

Sometimes it's useful to have a view file that can be called from several controller actions. For these cases, you'll typically call renderPage() with the template argument.

When using the template argument, there are specific rules that Wheels will follow in order to locate the file you want to include:

  • If the template argument starts with the / character, Wheels will start searching from the root of the views folder. Example: renderPage(template="/common/page") will include the views/common/page.cfm file.

  • If it contains the / character elsewhere in the string, the search will start from the controller's view folder. Example: renderPage(template="misc/page") will include the views/blog/misc/page.cfm file if we're currently in the blog controller.

  • In all other cases (i.e. when the template argument does not contain the / character at all), Wheels will just assume the file is in the controller's view folder and try to include it. Example: renderPage(template="something") will include the views/blog/something.cfm file if we're currently in the blog controller.

Also note that both renderPage(template="thepage") and renderPage(template="thepage.cfm") work fine. But most of the time, Wheels developers will tend to leave out the .cfm part.

What Goes in the Files?

This is the output of your application: what the users will see in their browsers. Most often this will consist of HTML, but it can also be JavaScript, CSS, XML, etc. You are of course free to use any CFML tags and functions that you want to in the file as well. (This is a CFML application, right?)

In addition to this normal code that you'll see in most ColdFusion applications—whether they are made for a framework or not—Wheels also gives you some nice constructs to help keep your code clean. The most important ones of these are Layouts, Partials, and Helpers.

When writing your view code, you will have access to the variables you have set up in the controller file. The idea is that the variables you want to access in the view should be set unscoped (or in the variables scope if you prefer to set it explicitly) in the controller so that they are available to the view template.

In addition to the variables you have set yourself, you can also access the params struct. This contains anything passed in through the URL or with a form. If you want to follow MVC rules more closely though, we recommend only accessing the params struct in the controller and then setting new variables for the information you need access to in the view.

The most important thing to remember when creating your view is to be careful not to put too much code in there. Avoid code dealing with the incoming request (this can be moved to the controller) and code containing business logic (consider moving this to a model). If you have view-related code but too much of it, it may be beneficial to break it out into a helper or a partial.

Cleaning Up Output

A view's job is also to clean up and format the values provided by the controller before being displayed. This is especially important when content from a data source is not HTML-escaped.

For example, if the view is to display the title column from a query object called posts, it should escape HTML special characters:

<ul>
<cfoutput query="posts">
<li>#HtmlEditFormat(posts.title)#</li>
</cfoutput>
</ul>
^ Top
Table of Contents

Comments

Read and submit questions, clarifications, and corrections about this chapter.

[Add Comment]

  1. Grant Copley's Gravatar Grant Copley says:

    Hey guys,
    I'm getting an error when I click on the link for the Rendering Content Chapter:

    Error!
    Sorry, that caused an unexpected error.
    Please try again later.

  2. Randy Johnson's Gravatar Randy Johnson says:

    Found my answer on the partials page.  Please disregard

  3. Darren Bennett's Gravatar Darren Bennett says:

    How would I go about nesting views and controllers?

    I have a preferences view an within that a status view so my view folder looks like this

    preferences/status

    inside status I want to have further actions such as add which gives me

    preferences/status/add

    how would I set up the contriller for that I currently have separate controllers for preferences and status which throws and error, similarly having a status method inside the preferences controller works but how do I then further nest actions?

    My ultimate goal is to have hard urls to each page of the app I didn't want my grouping in the nav not be reflected in the url path

    Thanks for any help

  4. Michael's Gravatar Michael says:

    @Darren Bennett

    You'd have an action called "add" in your preferences controller and then use a ROUTE in CFWheels to format the URL like "preferences/status/add"; when really this actually goes to "preferences/add";.

Add Comment