{"__v":1,"_id":"55097b214c7c3f2300aabf0f","category":{"__v":8,"_id":"550974cc368a56170041475d","project":"55070e814bb83b2500ec9404","version":"550974cb368a561700414757","pages":["55097b214c7c3f2300aabf0f","55097b272dd6a11900e6e7bb","55097b2edd77250d00736a09","55097b352dd6a11900e6e7c2","55097b3e2dd6a11900e6e7c6","55097b4e4c7c3f2300aabf12","55097b712dd6a11900e6e7c8","55097b8bad1f0523008ecbdc"],"reference":false,"createdAt":"2015-03-18T11:08:31.853Z","from_sync":false,"order":5,"slug":"displaying-views-to-users","title":"Displaying Views to Users"},"project":"55070e814bb83b2500ec9404","user":"55070d24d30b3f190011b941","version":{"__v":1,"_id":"550974cb368a561700414757","forked_from":"55070e814bb83b2500ec9407","project":"55070e814bb83b2500ec9404","createdAt":"2015-03-18T12:51:23.709Z","releaseDate":"2015-03-18T12:51:23.709Z","categories":["550974cc368a561700414758","550974cc368a561700414759","550974cc368a56170041475a","550974cc368a56170041475b","550974cc368a56170041475c","550974cc368a56170041475d","550974cc368a56170041475e"],"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.4.0","version":"1.4"},"updates":[],"createdAt":"2015-03-18T13:18:25.767Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"order":0,"body":"We've talked previously about how the controller is responsible for deciding which view files to render to the user. Read the [Rendering Content](doc:rendering-content) chapter if you need to refresh your memory about that topic.\n\nIn this chapter, we'll explain exactly *where* to place these files and *what* to put in them.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Where to Place the Files\"\n}\n[/block]\nIn 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](doc: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.\n\nSome rules can be spotted here:\n\n* All view files live in the `views` folder.\n* Each controller gets a subfolder named after it in the `views` folder.\n* The view file to include is just a regular `.cfm` file named after the action.\n\nFor creating standard pages, your work process will likely consist of the following steps:\n\n1. Create the controller action (a function in the controller CFC file).\n2. Create the corresponding view file for it (a `.cfm` file in the controller's view folder).\n\nThere can be some exceptions to this process though, so let's go through some possible scenarios.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Controller Actions Without Associated View Files\"\n}\n[/block]\nNot 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()](doc:redirectto) function.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Rendering the View File for Another Action\"\n}\n[/block]\nSometimes 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.\n\nIn this case, you can use the [renderPage()](doc: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).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sharing a View File Between Actions\"\n}\n[/block]\nSometimes it's useful to have a view file that can be called from several controller actions. For these cases, you'll typically call [renderPage()](doc:renderpage) with the `template` argument.\n\nWhen using the `template` argument, there are specific rules that Wheels will follow in order to locate the file you want to include:\n\n* 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.\n* 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.\n* 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.\n\nAlso 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What Goes in the Files?\"\n}\n[/block]\nThis 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?)\n\nIn 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](doc:layouts) , Partials, and Helpers.\n\nWhen 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.\n\nIn 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.\n\nThe 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Cleaning Up Output\"\n}\n[/block]\nA 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.\n\nFor example, if the view is to display the `title` column from a query object called `posts`, it should escape HTML special characters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<ul>\\n    <cfoutput query=\\\"posts\\\">\\n        <li>#HtmlEditFormat(posts.title)#</li>\\n    </cfoutput>\\n</ul>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","excerpt":"Where to place your view files and what to put in them.","slug":"pages","type":"basic","title":"Pages"}

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](doc: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. [block:api-header] { "type": "basic", "title": "Where to Place the Files" } [/block] 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](doc: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. [block:api-header] { "type": "basic", "title": "Controller Actions Without Associated View Files" } [/block] 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()](doc:redirectto) function. [block:api-header] { "type": "basic", "title": "Rendering the View File for Another Action" } [/block] 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()](doc: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). [block:api-header] { "type": "basic", "title": "Sharing a View File Between Actions" } [/block] 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()](doc: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. [block:api-header] { "type": "basic", "title": "What Goes in the Files?" } [/block] 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](doc: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. [block:api-header] { "type": "basic", "title": "Cleaning Up Output" } [/block] 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: [block:code] { "codes": [ { "code": "<ul>\n <cfoutput query=\"posts\">\n <li>#HtmlEditFormat(posts.title)#</li>\n </cfoutput>\n</ul>", "language": "text" } ] } [/block]