(Quick Reference)

16. Scaffolding - Reference Documentation

Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith

Version: 1.4.0.M1

16. Scaffolding

Scaffolding allows you to auto-generate a whole application for a given domain class including:
  • The necessary views
  • Controller actions for create/read/update/delete (CRUD) operations

Enabling Scaffolding

The simplest way to get started with scaffolding is to enable scaffolding via the scaffold property. For the Book domain class, you need to set the scaffold property on a controller to true:

class BookController {
   static scaffold = true
}

The above works because the BookController follows the same naming convention as the Book domain class. If we wanted to scaffold a specific domain class we could reference the class directly in the scaffold property:

class SomeController {
    static scaffold = Author
}

With that done if you run this grails application the necessary actions and views will be auto-generated at runtime. The following actions are dynamically implemented by default by the runtime scaffolding mechanism:

  • list
  • show
  • edit
  • delete
  • create
  • save
  • update

As well as this a CRUD interface will be generated. To access the interface in the above example simply go to http://localhost:8080/app/book

If you prefer to keep your domain model in Java and mapped with Hibernate you can still use scaffolding, simply import the necessary class and set the scaffold property to it.

Dynamic Scaffolding

Note that when using the scaffold property Grails does not use code templates, or code generation to achieve this so you can add your own actions to the scaffolded controller that interact with the scaffolded actions. For example, in the below example, changeAuthor redirects to the show action which doesn't actually exist physically:

class BookController {
    static scaffold = Book

def changeAuthor = { def b = Book.get( params["id"] ) b.author = Author.get( params["author.id"] ) b.save()

// redirect to a scaffolded action redirect(action:show) } }

You can also override the scaffolded actions with your own actions if necessary:

class BookController {
    static scaffold = Book

// overrides scaffolded action to return both authors and books def list = { [ bookInstanceList : Book.list(), bookInstanceTotal: Book.count(), authorInstanceList: Author.list() ] }

def show = { def book = Book.get(params.id) log.error(book) [ bookInstance : book ] } }

All of this is what is known as "dynamic scaffolding" where the CRUD interface is generated dynamically at runtime. Grails also supports "static" scaffolding which will be discussed in the following sections.

By default, the size of text areas in scaffolded views is defined in the CSS, so adding 'rows' and 'cols' attributes will have no effect.

Also, the standard scaffold views expect model variables of the form <propertyName>InstanceList for collections and <propertyName>Instance for single instances. It's tempting to use properties like 'books' and 'book', but those won't work.

Customizing the Generated Views

The views that Grails generates have some form of intelligence in that they adapt to the Validation constraints. For example you can change the order that fields appear in the views simply by re-ordering the constraints in the builder:

def constraints = {
   title()
   releaseDate()
}

You can also get the generator to generate lists instead of text inputs if you use the inList constraint:

def constraints = {
   title()
   category(inList:["Fiction", "Non-fiction", "Biography"])
   releaseDate()
}

Or if you use the range constraint on a number:

def constraints = {
   age(range:18..65)
}

Restricting the size via a constraint also effects how many characters can be entered in the generated view:

def constraints = {
   name(size:0..30)
}

Generating Controllers & Views

The above scaffolding features are useful but in real world situations its likely that you will want to customize the logic and views. Grails allows you to generate a controller and the views used to create the above interface via the command line. To generate a controller type:

grails generate-controller Book

Or to generate the views type:

grails generate-views Book

Or to generate everything type:

grails generate-all Book

If you have a domain class in a package or are generating from a Hibernate mapped class remember to include the fully qualified package name:

grails generate-all com.bookstore.Book

Customizing the Scaffolding templates

The templates used by Grails to generate the controller and views can be customized by installing the templates with the install-templates command.