-
Notifications
You must be signed in to change notification settings - Fork 6
Controllers
Controllers are responsible for handling requests, fetching data from the model, and optionally rendering views.
Controllers are located inside your application's /app/controllers/ directory. In order for a component to be considered a controller, the file must be named using a "Controller" suffix. For example, a user controller would be located at /app/controllers/UserController.cfc. All public methods on a controller are considered actions.
The params scope contains all of your request's parameters, including all url and form variables, and any computed values created by the current request's route.
The flash scope is a temporary persistent scope.
Any data that is put into the flash scope is automatically persisted until the next request, where it is available inside the requestContext or using the flashKeyExists and getFlash helpers.
The flash scope is very useful for displaying validation messages to the end user. For example, to notify the user that a record was updated successfully.
Action helpers are custom functions that are available to your controllers that expose common controller-related methods without having to extend a base controller.
You can expose any function on a singleton bean or a helper as an action helper by adding an @actionHelper {name} annotation to the function.
When you first create an application using ColdMVC, you'll already have access to a standard set of action helpers. The most prominent action helper is the redirect() method that allows you to redirect the browser after you perform an action.
- assertAjax
- assertAllowed
- assertGet
- assertLoggedIn
- assertModelExists
- assertNotLoggedIn
- assertParamExists
- assertPost
- createForm
- createPaginator
- createSorter
- escape
- flashKeyExists
- getAction
- getContent
- getController
- getFlash
- getFormat
- getLayout
- getModule
- getParam
- getParams
- getRequestContext
- getUser
- getUserID
- getView
- hasContent
- hasParam
- isAjax
- isAllowed
- isDevelopment
- isGet
- isLoggedIn
- isMobile
- isPost
- isSecure
- redirect
- renderPartial
- returnRedirect
- setAction
- setContent
- setController
- setFormat
- setLayout
- setModule
- setParam
- setUserID
- setView
ColdMVC will implicitly invoke certain methods on your request's controller if they are defined.
Before the request's action is invoked, ColdMVC will invoke the controller's pre and pre{Action} methods if they exist.
Next, ColdMVC will invoke the action for the request, followed by the post{Action} and post methods if they exist.
For example, if the current request is /product/list, ColdMVC will invoke ProductController.pre(), ProductController.preList(), ProductController.list(), ProductController.postList(), and finally ProductController.post().
ColdMVC provides your application with several interception points throughout the lifecyle of a request.
This is possible thanks to centralized event dispatching from ColdMVC's EventDispatcher component.
In a typical ColdMVC request, the following events will be dispatched:
- preRequest
- requestStart
- preAction
- postAction
- preLayout
- postLayout
- request
Any controller within the application can listen for these events by applying an @events annotation to the desired listener method.
The @events annotation is a comma-separated list of events, providing quite a bit of flexibility in intercepting.
For example, if you wanted a SecurityController to verify that the current user is logged in at the beginning of each request, here's how you could listen for the requestStart event:
component {
/**
* @events requestStart
*/
function verifyLoggedIn() {
if (!$.user.isLoggedIn()) {
redirect({controller="security", action="logout"});
}
}
}
All of the request's events are displayed in the ColdMVC debug output, along with any registered listeners for each event.
Requests can respond to different request formats, including html, json, xml, and pdf.
By default, all requests can respond to html and pdf formats. You can allow for more formats by using the @formats annotation. Possible values include html, pdf, json, and xml.
By default, all requests are rendered using an html format.
You can render a request in a different format by either specifying a format parameter in the URL (http://myapp.com/product/show/1?format=pdf) or by adding a format extension in the URL (http://myapp.com/product/show/1.pdf).
Ajax requests are fundamentally the same as normal web requests in ColdMVC: the request is matched to a route and handled by a controller, which gathers data from the model and optionally renders a view.
However, there are a few things to know when working with Ajax.
There is no debug information appended to your request during an Ajax request. This is to prevent the Ajax request from returning too much data or breaking the response format.
If you would like your Ajax request to return something other than HTML, like a JSON or XML string, you can have the response automatically serialized into the proper format by adding a format parameter to your Ajax request.
$('#results').load('#linkTo({controller="index", action="search"})#', {
format: 'json',
q: $('#q').val()
});
There is not a layout associated with Ajax requests by default. This is because most of the time your Ajax requests will return a small snippet of HTML, or possiblly a JSON or XML string.
If you would like to wrap your Ajax views inside a layout during Ajax requests, you would add an @ajaxLayout annotation to your controller's actions.
/**
* @ajaxLayout modal
* /
function search() {
params.results = _Book.findAllByTitleLike(params.q);
}
You will also need to allow your action to respond to the format by adding a @formats annotation to the action on your controller. By default, all actions only respond to a html and pdf formats.
/**
* @formats json
* /
function results() {
params.results = _Book.findAllByTitleLike(params.q);
}