Last updated by 2 years ago

Page: Quick Start, Version:41

Quick Start

The following makes it simple to start a grails project. There's also a screencast that follows these steps for creating a small app.

There is a Portuguese Version on this Quick Start guide.

Create a Grails project

Once you have installed Grails you can use the built-in target for creating new projects: 

grails create-app my-project
The project structure below: 
%PROJECT_HOME%
    + grails-app
       + conf                 ---> location of configuration artifacts 
           + hibernate              ---> optional hibernate config
           + spring                 ---> optional spring config
       + controllers          ---> location of controller artifacts
       + domain               ---> location of domain classes
       + i18n                 ---> location of message bundles for i18n
       + services             ---> location of services
       + taglib               ---> location of tag libraries
       + util                 ---> location of special utility classes 
       + views                ---> location of views
           + layouts              ---> location of layouts
   + lib
   + scripts                  ---> scripts
   + src
       + groovy               ---> optional; location for Groovy source files
                                   (of types other than those in grails-app/*)
       + java                 ---> optional; location for Java source files
   + test                     ---> generated test classes
   + web-app
       + WEB-INF

Configure a Data Source (Optional)

The "create-app" target created a Grails data source artifact for you in the "<..>/grails-app/conf" directory called DataSource.groovy with closures for each of the standard environments: development, test, and production. All the examples that follow operate on the development environment. For more information on environments see http://grails.org/doc/latest/guide/3.%20Configuration.html#3.2%20Environments.

By default, each data source is configured with an in-memory HSQLDB database (great for testing, but probably not that useful for live deployment) so this step is optional:

dataSource {
  pooled = false
  driverClassName = "org.hsqldb.jdbcDriver"
  username = "sa"
  password = ""
}
// environment specific settings
environments {
  development {
    dataSource {
      dbCreate = "create-drop" // one of 'create', 'create-drop','update'
      url = "jdbc:hsqldb:mem:devDB"
//    loggingSql = true
    }
  }
  test {
    dataSource {
      dbCreate = "update"
      url = "jdbc:hsqldb:mem:testDb"
    }
  }
  production {
    dataSource {
      dbCreate = "update"
      url = "jdbc:hsqldb:file:prodDb;shutdown=true"
    }
  }
}

Configuring the data source is a simple matter of changing the values for the desired database and driver and placing the driver jar file in the <..>/lib directory. Properties set in the dataSource node are inherited by the children.

See this post on how to connect to an HSQL Database using DBVisualizer (this is useful to see the schema grails automatically generates).

Create a Domain Class

Make sure you are in the root directory of your project by typing

cd my-project
grails create-domain-class book // Either "Book" or "book" is ok

The target will create Book.groovy in GRAILS_HOME/grails-app/domain/my/project. You can edit it with your favorite text editor or IDE.

Note: When naming your domain classes, stay away from names that are keywords in the database server you are using for persistence (for example, on MySQL, "Group" is a keyword; Alternatives could be something like "UserGroup").

A domain class is a persistent artifact and all properties are by default persisted to the database (Go to the section on GORM (Grails Object Relational Mapping) for more info):

class Book {
    String title
    String author
}

At this point you may want to create some test data. An easy way to do this is to build and save the domain objects in the "init" closure of the Grails application bootstrap class found in "<..>/grails-app/conf/BootStrap.groovy"

import my.project.Book
class BootStrap {
    def init = { servletContext ->
        // Create some test data
        new Book(author:"Stephen King",title:"The Shining").save()
        new Book(author:"James Patterson",title:"Along Came a Spider").save()
    }
    def destroy = {
    }
}

Create a controller

Controllers are central to Grails applications they handle web requests and URLs of the request map to a controller class and a closure within the class.

grails create-controller my.project.Book // Note the capital B

The target will create BookController.groovy in GRAILS_HOME/grails-app/controllers/my/project. You can edit it with your favorite text editor or IDE.

Open up this controller and change it as follows to use dynamic Scaffolding which dynamically generates your application at runtime:

class BookController {
     def scaffold = Book // Note the capital "B"
}

You will need to remove or comment out the "def index = { } " as this overrides the scaffolded action.

Alternatively, you could also have run "grails generate-all", which creates all the scaffolding for you, and left the generated controller alone, instead of replacing it with the default scaffolding. It might be worth learning from.

Start Grails

To start your Grails app run the following target

grails run-app

This will startup an instance of the Jetty servlet engine running on port 8080. To access the list of books open up a browser and type:

http://localhost:8080/my-project/book/list

Or, as the "list" closure is the default action for the BookController you can type: 

http://localhost:8080/my-project/book
http://www.wa-liability-insurance.com/ Liability insurance Washington
If response times are slow during developing try increasing your maximum heap size by setting the JAVA_OPTS environment variable to something like: '-Xmx512m' - this will set the maximum heap size to 512Mb when running Grails and should result in a noticeable improvement in response times.

What's Next