Grails 2.0

Form controller type

Form controllers receive a command object from the MVC frameworks populated with the parameter values that is optionally validated. They do not need access to HttpServletRequest and HttpServletResponse instances although this should be supported. They return a model and delegate to a view. Controller names should end with "FormController" while the first part of the name is mapped to a URI like plain old controllers.

Also like plain old controllers form controllers can have multiple closure properties that take the command object and returns a model to handle requests. Closure property names are mapped to URI's and the "defaultProperty" property is also supported.

Closure formSubmit = {
    command ->
    // do controller logic
    // create model
    return model
};

This example also takes the request and response parameters:

Closure formSubmit = {
    command, request, response ->
    // do controller logic
    // create model
    return model
};

Form controllers support a form view and success view. When validation of the command object fails the form view is shown, otherwise the success view is shown. The view property names have to map to a closure property name plus "FormView" and "SuccesView".

String formSubmitFormView = "formView"
String formSubmitSuccessView = "successView"

Form controllers can report errors back to the user through an errors object. If errors are added to the errors object the controller will return to the form view, not the succes view.

Closure formSubmit = {
    command, errors ->
    // do controller logic
    // create model
    return model
};

Finally form controller closures can also take four parameters: command object, errors object, request and response:

Closure formSubmit = {
    command, errors, request, response ->
    // do controller logic
    // create model
    return model
};

If validators are configured for a form controller closures will not be executed if the command object fails to validate.

Command object artifact

A command object is populated by MVC frameworks with the values of request parameters when request handling is delegated by controllers. Parameter names map to property names, type conversion happens automagically.

Command object names and class names need to be configured on the controllers that require them.

Coding conventions for command objects

Command class names should start with the name of the controller they are used with and end with "Command". A command class that's to be used with "PersonalDetailsController" should be called "PersonalDetailsCommand". Command objects will be stored in the request scope under the command name beginning with a lower case letter. In the example above the command name would be "personalDetails".

Command objects are required artifacts for form controllers. If no command object is found an exception will be thrown.

Command objects may need to retrieve data from the database or other sources to populate the form. To have these resources injected add corresponding properties to command classes.

CountryService countryService

REST controllers

REST controller class names should end with "RestController". Grails parses the incoming request as XML and passes a groovy.util.Node object as parameter if parsing succeeds. Optionally the request instance can also be passed to closures as a parameter. To render the response REST controllers are expected to return a groovy.util.Node instance which will be returned to the client as XML by Grails. As such REST controllers do not work with views, they work with XML nodes.

class BooksRestController {
    Closure list = {
        rootNode ->
        return new NodeBuilder().errors() {
            error(message:"No books here")
        }
    }
}