Grails Training - Developed and delivered by the folks who created and actively maintain the Grails framework!.

In this guide you are going to create your first Grails application. You will learn about domain classes, controllers, services, GSPs, and unit & integration tests. This guide is aimed at developers who are new to Grails or would like a refresher course on the framework.

To complete this guide, you will need the following:

To get started do the following:

or

The Grails guides repositories contain two folders:

To complete the guide, go to the initial folder

and follow the instructions in the next sections.

For this guide, you can either create the starting project yourself, or use the initial project included in the guide’s repo to get started. If you choose to use the initial project, you can safely skip this section and continue to [runningTheApp] If you would like to install Grails on your computer, follow one of the options below.

Creating a Grails app is about as simple as could be - once you have installed Grails, simply run the create-app command:

If you don’t specify a package, the app name will be used as the default package for the application (e.g., myapp). You can edit the default package at grails-app/conf/application.yml You can optionally specify a default package for the application:

You can optionally specify a Profile for your Grails app. Profiles are available for many common application types, including rest-api, angular, react, and others, and you can even create your own.

To view of a list of what profiles are available, use the list-profiles command.

To use a profile, specify its name preceded by the -profile flag:

You may optionally specify a package and version (defaults to org.grails.profiles and the current version of the profile)

To get detailed information about a profile use the profile-info command.

Now that you’ve created (or downloaded) your Grails project, it’s time to run it and see what Grails has already given you.

If you have a local installation of Grails, you can run the app using the run-app command from within your project:

Run the App without Grails Installed

Thanks to the Grails Wrapper, as of Grails version 3.2.3 or later, you can run any Grails command without having Grails installed. If you download it from the Grails Application Forge, the Grails Wrapper is included too.

Run the App with Grails

If you have Grails installed in your machine, simply type:

Run the App with Grails Interactive Mode

You can also use Grails' Interactive Mode to run the Grails runtime, from which you can issue any Grails command without waiting for the runtime to spin up for each task.

In this guide we will be preferring the Grails wrapper for most commands.

Run the App with Gradle

Finally, because Grails is built upon Spring Boot and Gradle, you can also use Spring Boot commands like bootRun to interact with your Grails application. These commands are available as Gradle tasks. Just as with Grails itself, there’s no need to install Gradle on your machine. It will be downloaded automatically when using the the Gradle Wrapper (gradlew)

After running any of the above commands, Grails will launch your application using an embedded Tomcat server, and make it available (by default) at http://localhost:8080.

If you’d like to change the port number, simply edit the application.yml file under grails-app/conf/, and add the following line:

You can supply the port number directly in the command invocation:

Currently the app simply displays a default index page with some information about the application. The default index page is located under grails-app/views/index.gsp.

Go ahead and edit that file, and change some thing on the page, as shown below (line 54):

Save your changes and refresh the page in the browser. You should see your change on the home page. Grails will auto-reload changes to views, controllers, domain classes and other artefacts when it detects changes, so you don’t need to restart the app upon every change.

Grails is a Model View Controller (MVC) framework, based upon the Spring Boot project. Typically an MVC application divides the responsibilities of the app into three categories:

Typically an object-oriented MVC framework requires the developer to configure which classes correspond to each of the three categories above. However, Grails goes farther than most frameworks by following a "Convention over Configuration" approach to development. This means that for many artefact types in Grails (controllers, views, etc), you simply create a file in a particular directory in your project, and Grails will automatically wire it into your application without any additional configuration on your part.

When building a MVC application, it is typical to start with the "M" (Model), also known as the "Domain model". In Grails, your domain model is defined with Groovy classes under grails-app/domain. Let’s create a domain class.

Domain classes can be generated by Grails (in which case Grails will helpfully create a unit test automatically), or you can simply create the file yourself.

This will generate two Groovy files, one being our domain class, and the other a unit test. Let’s see what our domain class looks like.

Right now our domain class has no properties, and no constraints. That’s not very interesting, but it’s worth noting that this is all that’s needed to wire up a persistent domain class in our application. By default, Hibernate will be used to configure a datasource (an in-memory H2 database by default) and create tables and associations for all Groovy classes under grails-app/domain. Let’s add some properties to this domain class:

Please see the Grails documentation for a complete list and documentation of how to use domain classes and constraints

If you run the app again, you should see the same page as before. However, you can login to the DB Console and view your new database table.

Browse to http://localhost:8080/dbconsole and login. The default username is sa, without a password. The default JDBC URL is: jdbc:h2:mem:devDb;MVCC=TRUE;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE

Once you’ve logged in to the DB Console, you should see your new VEHICLES table in the left-hand sidebar. Click the + icon to expand the table - you should see a list of columns, including the three String fields we just defined, name, make, and model.

For our Vehicle class, it doesn’t really make sense that make and model are plain Strings, since models should actually be associated with makes. Let’s update our domain model to be more robust.

Create two new domain classes:

Edit these two files with the following content:

Now, update Vehicle.groovy to use the new Make and Model classes instead of String.

Grails (via GORM) will now create three tables in our database, for our three domain classes, and create the necessary associations between the tables. Run the app again and open the DB Console to view the new tables.

Every Grails project includes a BootStrap.groovy file under grails-app/init. This file can be used for any custom logic you want to happen during application startup. One excellent use of the file is to preload some data in our database. Let’s create a few instances of our three domain classes.

Edit grails-app/init/org/grails/guides/BootStrap.groovy, as shown below:

Now restart the application, and browse to the DBConsole, you should be able to expand the three tables and see our newly created data.

By default, Grails configures an in-memory H2 database, which is dropped and recreated every time the app is restarted. This will be sufficient for our purposes in this guide, however, you can easily change this to a local database instance by configuring your own datasource. We’ll use MySQL as an example.

Edit build.gradle

Edit application.yml

Right now we don’t have any controllers or views set up to play with our domain model. We’ll get there shortly, but for now, let’s fire up the Grails Console so we can explore what Grails and GORM have to offer.

If the application is still running, shut it down with either kbd:[Ctrl+C], or (if running Grails in Interactive Mode, the stop-app command).

Launch the Grails Console:

The Grails Console application will launch. This application is based on the Groovy Console, but has the added benefit that our entire Grails application is up and running in the background, so we can access our domain classes and even persist to the database from the Console.

Try playing with our new domain model from the Console. Here’s a simple script to get you started - again, refer to the GORM documentation for more details on querying, persistence, configuration and more.

This section will focus on the basics of creating a controller and defining actions.

Following the convention over configuration principle, Grails will configure any Groovy classes under grails-app/controllers/ as controllers, without any additional configuration. You can create the Groovy class yourself, or use the create-controller command to generate the controller and an associated test spec.

Let’s take a look at our new controller.

Grails has created a controller with a single action. Actions are public methods in a controller, which can respond to requests. Typically, a controller action will receive a request, obtain some data (optionally using parameters or a body of the request, if present), and render the result to the browser (e.g, as a webpage). Controller actions can also redirect requests, forward, call service methods, and return HTTP response codes. See the Grails documentation for more on controller actions.

We don’t have any need for logic in this particular action just yet, but we would like it to render a page. We’ll look at GSP pages in more detail in the [Views] section, but for now, let’s create a very simple GSP page for our HomeController.index action to display.

Create the file index.gsp under the grails-app/views/home directory.

Run the application again and browser to http:localhost:8080/home. You should see your new page.

By convention, Grails will map controller actions to views with the same name, in the grails-app/views/[controller name] directory. You can override this and specify a particular view (or render different content altogether).

We’ll cover views and GSPs in more detail in the next section, but for now, you should note that our index.gsp file is basically an HTML page, with a couple unusual tags. Feel free to modify this new home page however you would like.

Now that we have our new "home" page, it would be nice if it was the app’s landing page instead of the Grails default. To do that, we’ll need to change our UrlMappings.groovy file.

Grails uses the UrlMappings.groovy file to route request to the proper controller and action. They can be as simple as URI strings that redirect to a controller and/or action, or they can include wildcards and constraints and become quite sophisticated.

Let’s look at the default URLMappings.groovy file.

Let’s change the / rule to point to our new HomeController. Edit the line as follows:

By convention, a request to a controller without an action name will go to an index action, if it exists (if not, an error will be thrown). You can change this behavior if you want by specifying a defaultAction property in the controller:

Now that you’ve changed the / rule to point to your new HomeController, if you restart the app and browser to http://localhost:8080, you should be presented with your new home page.

We’d like to have actions to allow us to create new domain class instances and persist them to the database. In addition, we’d like to have the ability to edit existing instances and even delete them. Normally all this functionality would require a lot of coding, but Grails gives us a headstart with scaffolding.

Now that we have a home page, let’s create controllers to manage the domain model we created earlier. Create 3 new controllers for each of the domain classes, Vehicle, Make, and Model.

To use scaffolding, edit the three controllers we just created, and replace the default index action with a scaffolding property as shown in the examples below.

With the scaffold property set, Grails will now generate all necessary CRUD (Create, Read, Update, Delete) actions for the respective domain classes. It will also dynamically generate views with list, create, show and edit pages using our domain properties and associations. This can give you a big leg up when putting together the beginnings of an application.

Restart the app, and browse to http://localhost:8080/vehicle - you should see a list of the Vehicle instances we added to our BootStrap. Try out the new views and create, view, edit and delete some instances. You can also do the same with the Model and Make controllers.

Dynamic scaffolding is powerful and sometimes will provide all the functionality you need (especially for an administrative site where data access is more important than presentation). But it’s quite likely that you will feel the need to customize the generated views and controllers, either to change their appearance or to add custom logic and functionality. Grails anticipates this need and provides a set of generate commands that can generate the controllers and/or views that you just saw, allowing you to modify them to suite your needs.

To generate the views (and continue to use the dynamic scaffolding):

To generate the controller (and continue to use the dynamic GSP views):

To both views and controllers (bypassing all dynamic generation):

The generated controller will be placed under grails-app/controller, and the generated views will be placed under grails-app/views/vehicle.

Let’s generate the controller and views for Vehicle and take a look at the resulting controller.

Open the VehicleController.groovy file at grails-app/controllers/org/grails/guides/.

That’s a lot of code! Generating and modifying a scaffold controller is a good learning exercise, so feel free to experiment and modify this code - you can always revert back to the version in the completed project of this guide.

Let’s modify our HomeController to render some custom content on our home page. Edit grails-app/controllers/org/grails/guides/HomeController.groovy.

We’ve updated our index action to render some custom content to the page, and we’ve created a new action updateName, which takes a String parameter and saves it to the session for later retrieval. However, we need to update our view to 1. display the newly available content, and 2. provide some means of calling updateName and setting the session attribute.

Edit grails-app/views/home/index.gsp:

Run the app and you should see our new message in the <h1> header: "Welcome User!", as well as the current total of Vehicle instances in the database.

Try entering your own name in the form and submitting it - you should see the page reload and your own name will replace "User". Refresh the page a few times. Because we stored the name in the session, it will persist as long as the session is valid.

Views are the third component of the MVC pattern. Views are responsible for presenting data to the user (which might be a browser page, an API endpoint, or some other sort of consumer). In many apps, views are HTML pages designed to be loaded in a browser. However, it is perfectly reasonable for a "view" to be an XML or JSON document, depending on the type of client requesting the view.

Grails' primary view technology is Groovy Server Pages. It follows many of the conventions of JSP and ASP, but naturally it is based upon the Groovy language. GSP pages are essentially HTML documents, but they support a number of special tags (typically prefix with g:) to allow programmatic control over your views. You can even write arbitrary Groovy code in your GSP pages, but this is strongly discouraged - ideally, the GSP page should only contain view-related logic and content; any sort of data manipulation or processing should happen in the controller (or in a service) prior to the view being rendered.

You’ve already worked with GSP views in this guide, but let’s quickly cover the basics.

How does Grails choose which view to render? By convention, Grails looks for views under the grails-app/views directory. It will attempt to resolve views to controller actions by matching the controller name with a directory under the views directory. E.g., HomeController will resolve to grails-app/views/home. Grails will then map actions to GSP pages with the same name. E.g, index will resolve to index.gsp.

You can also render a particular view from your controller action (overriding Grails' conventions) using the render method:

This will attempt to resolve to a anotherView.gsp page under grails-app/views/some/. If you would like to resolve a view that is not under the controller’s own view directory, use a leading / to specifiy an absolute path from grails-app/views:

This will resolve to view.gsp under grails-app/views/another/.

GSP pages have access to a rich set of tags. We’ve seen a few in action already. You can get much more detail on the available GSP tags (including how to define your own custom tags) from the Grails documentation.

Let’s soup up our index.gsp page a bit with some GSP tags.

Edit grails-app/views/home/index.gsp

Let’s take a closer look at <g:if>.

GSP tags can optionally accept attributes, such as test in this example. Different tags require different types of attributes, but typically you will end up passing a Groovy Expression like in this example. Any Groovy code between the ${ and } will be evaluated (on the server) and the result will be substituted on the rendered page.

Other tag attributes might accept plain strings or numbers. E.g, <g:form action="updateName">

A GSP tag can also optionally include a body. In the case of <g:if>, the body will only be rendered if the test expression evaluates to true (following the Groovy Truth convention). Other GSP tags (like <g:form>) simply include the body within the resulting HTML output.

Let’s take a look at one more common GSP tag: <g:link>

<g:link> renders an HTML <a> tag, but it has the advantage in that it allows you to specify your link target following Grails conventions, such as this example (using the controller, action and id attributes). <g:link> is also smart enough to follow our URL mappings, so if we change the URL mapping for vehicle/show, the <g:link> tag will still render the correct URL. There’s many more attributes supported by <g:link> - see the Grails documentation for more.

You may have noticed a few <asset> tags in our GSP pages. These tags are provided by the Asset Pipeline plugin, which is Grails' default tool for managing static assets (images, CSS, JavaScript files, etc). The Asset Pipeline plugin provides a set of custom GSP tags, but unlike the tags we’ve been exploring, it uses the asset prefix (or namespace).

The most common <asset> tags are listed below:

As you can see, the Asset Pipeline follows a convention over configuration approach, following the precedent of Grails. However, Asset Pipeline is a very powerful framework, and includes a rich plugin ecosystem - you can find plugins to render LESS and SASS files, CoffeeScript, Ember, Angular, JSX (React), and more.

Asset Pipeline also supports minification and compression of your assets, and much more.

Let’s use the Asset Pipeline plugin to add jQuery to our page. Grails includes jQuery by default. The version of Grails used in this guide included jQuery 2.2.0 by default:

but let’s instead download the latest version. Download jQuery from https://code.jquery.com/jquery-3.1.1.js

Save jquery-3.1.1.js to grails-app/assets/javascripts.

Edit grails-app/views/home/index.gsp, add the following snippet in the head block.

Refresh the page, and open your browser’s developer console. You should see the string jQuery 3.1.1 loaded! in the console logs.

Grails provides a "service layer", which are classes that encapsulate business logic and are wired (using dependency injection) into the application context, so that any controller can inject and use them. Services are the preferred vehicle for most application logic, not controllers.

If this seems confusing, think of it this way: controllers are intended to respond to the request and return a response. Services can be reused across many controllers (as well as in domain classes and from other services). Services are more versatile and can help you keep your controllers clean and prevent duplication of business logic. It is often easier to write unit tests against service methods than against controller actions, as well.

Again by convention, Grails will configure any Groovy classes within the grails-app/services directory as services. Services will be "wired" as Spring beans in the Grails application context, which means you can refer to them simply by name from any other Spring bean (including controllers and domain classes).

Let’s add a feature to generate an estimated value for Vehicle, based on the make, model and year. We’ll put this logic in a service and call it from our application code.

Create a new service using the create-service Grails command:

Edit grails-app/services/org/grails/guides/ValueEstimateService.groovy

Grails has provided a serviceMethod stub as an example. Delete it and replace it with the following content:

Obviously this method of estimating a vehicle’s value is pretty contrived! In reality you would likely call a third-party webservice to get a valuation, or perhaps run a query against your own database. However, the point of this example is to show the sort of "business logic" that can be placed in services, rather than being calculated within a controller or view.

Now, let’s use our new service.

Edit grails-app/controllers/org/grails/guides/VehicleController.groovy (the scaffolded controller we generated earlier), and add the property shown below:

Now (still editing VehicleController.groovy), modify the show action as seen below:

We’ve added a new property to the model, called estimatedValue. The value of this property is the result of calling our service method, getEstimate, to which we pass the vehicle property we are about to render.

Now, on the show page, we can access the estimatedValue property and display it on the page. Edit grails-app/views/vehicle/show.gsp as shown below:

Restart the application and browse to the show page for a Vehicle, such as http://localhost:8080/vehicle/show/1. You should see the "Estimated Value" on the page

Testing is a vital part of web application development. Grails provides support for three types of testing: unit tests, integration tests, and functional tests. Unit tests are usually the simplest kind, focusing on a specific piece of code without depending on other parts of your app. Integration tests require the Grails environment to be up and running, and are used to test features that depend on database or network resources. Functional tests require the app to be running, and are designed to exercise the application almost as a user would, by making HTTP requests against it. These tend to be the most complex tests to write.

The testing framework used by Grails is Spock. Spock provides an expressive syntax for writing test cases, based on the Groovy language, and so is a great fit for Grails. It includes a JUnit runner, which means IDE support is effectively universal (any IDE that can run JUnit tests can run Spock tests).

Grails tests are stored (by convention) in the src/test/groovy directory (unit tests) and src/integration-test/groovy directory (integration/functional tests).

You can run your Grails tests using the test-app command:

If you want to run only unit tests or integration/functional tests, you can pass in a command line flag to choose one or the other.

You can also run a specific test by passing the test class as an argument:

Writing tests is a very broad topic and worthy of its own guide. In practice, the simplest (and often most useful) tests are unit tests, so let’s write a simple unit test to exercise our ValueEstimateService.

Grails automatically creates a test spec for services created with the create-service command. Open src/test/groovy/org/grails/guides/ValueEstimateServiceSpec.

Currently our test spec has one test, "test something", which asserts that true == false. Grails is helpfully encouraging you to do the right thing by kicking things off with a failing test.

Try running the test, just to confirm it fails:

Now that we’ve confirmed our test is failing, let’s edit this test case to exercise our getEstimate method. Edit src/test/groovy/org/grails/guides/ValueEstimateServiceSpec.

We’ve kept things pretty simple in this test, since we don’t have very complex logic to test, but also so you can focus on the basic formula of the Spock test case. Spock provides a set of keywords which allow you to lay out your test in a very human-readable form.

Go ahead and rerun this test - if all’s well, it should pass with flying colors.

The final step in developing a Grails application is building the finished project into a deployable package. Typically Java web applications are deployed as WAR files, and Grails makes this easy with the war command:

Once we have our WAR file, we can deploy it in any JEE container, such as Tomcat.

Congratulations! You’ve built your first Grails application.