1 Overview

This plugin adapts the Vaadin framework for use in a Grails application.

2 Installation

Download the Plugin

The preferred method for installing plugins is to add a plugin dependency in grails-app/conf/BuildConfig.groovy, i.e.:

plugins {
    // Other plugin dependencies here
    // . . .
    // . . .
    compile ':vaadin:1.6.2.2-SNAPSHOT'
}

This will trigger installation of the plugin when we compile or run our app. But since we need to use scripts in the plugin beforehand, we also have to install the plugin manually the first time. Run the following at the command line:

grails install-plugin vaadin 1.6.2.2-SNAPSHOT

Create the Application

After installing the plugin, you should run the following at the command line to create your Vaadin application:

grails generate-vaadin-app com.somewhere.MyApp

This will install the necessary files and apply configuration changes to your application, to make it ready for Vaadin. See details in the generate-vaadin-app section.

Run the Application

If you now execute the following at the command line, you should see the default Grails home page - however note this is implemented in Vaadin, even though it (should) look identical to the standard home page provided by Grails!

grails run-app

3 Concepts and Usage

3.1 Usage Styles

• Base-Style: Simply exposes the base Vaadin Application, leaving the developer to build the interface programmatically using Java/Groovy classes.
• Grails-Style: Allows the developer to construct an application using Grails-style Controllers and GSP Views, supported by a Vaadin tag library.

This guide assumes the user prefers to utilise the Grails-Style architectural pattern. See a comparison of the styles and further details here.

3.2 Controllers, Views and Fragments

As an example, say we want to create a screen for displaying a list of books. In Grails, we would create a BookController.groovy file containing a list() method, and a book/list.gsp file. This would then be accessible from a browser via http://localhost:8080/myapp/book/list

With the Vaadin plugin, we do something very similar. We create a BookVaadinController.groovy file containing a list() method, and a vaadin/book/list.gsp file. This is then accessible from a browser via http://localhost:8080/myapp/vaadin#book/list. Note the '#' in the URL to denote the fragment!

The context path for a vaadin app defaults to /vaadin. This can be changed in the Configuration

3.3 A Simple Tutorial

We will assume you have already installed Vaadin following the instructions in the Installation section. Now follow these steps:

1. Create the Controller

Create a VaadinController by entering the following at the command line:

grails create-vaadin-controller myapp.Hello

This simply creates an empty groovy class under the grails-app/controllers folder. Note that VaadinController is automatically appended to the class name.

2. Add an Action

In the HelloVaadinController class, add a greetings method as follows:

class HelloVaadinController {
	def greetings() {}
}

3. Create the View

Create file grails-app/views/vaadin/hello/greetings.gsp with the following contents:

<div>
  <v:label>Hello world!</v:label>
</div>

4. Run the App

Finally, run the application using grails run-app and then browse to http://localhost:8080/myapp/vaadin#hello/greetings. You should see the "Hello World!" message displayed.

(Note that you will need to replace 'myapp' in the above URL with the name of your grails project.)

5. Use the Grails Theme

Let's improve the appearance of our new page. Change the text in file grails-app/views/vaadin/hello/greetings.gsp to the following:

<v:layout name="main">
  <v:label location="body">Hello world!</v:label>
</v:layout>

Now refresh your browser page - you should see your "Hello World!" message again, but this time within the familiar Grails theme.

Notice we used the special tag <v:layout name="main"> in the final step. This layout tag looks for a .gsp file with the specified name in grails-app/views/vaadin/layouts. Take a look at main.gsp in this directory in your app!

3.4 Scaffolding a Domain Class

The Vaadin plugin provides the exact equivalent of the standard grails scaffolding scripts, as follows:

For example, if you have a Domain Class called com.somepackage.Author, you should run the following at the command line to scaffold a CRUD interface:

grails generate-vaadin-all com.somepackage.Author

You can then browse the CRUD interface by visiting http://localhost:8080/myapp/vaadin#author.

Some of the benefits of Vaadin should now become apparent! Notice the lazy-loading, infinitely scrollable table on the list screen. Also, for any Date fields in your domain class, notice the Date Picker that gets automatically inserted. If that is not enough, you should definitely visit the Vaadin Sampler page and check out all the other ways you can spruce up your user interface!

3.5 Views and Tags

Sitemesh layout tags are currently not supported. Please use the Vaadin layout tag instead.

In addition, you can embed Vaadin components in GSPs using the tag library provided by this plugin:

3.6 Mixing Vaadin and Grails

The default configuration is for Vaadin to be served from path /vaadin - see the contextRelativePath setting in the Configuration.

If you set contextRelativePath to '/' it will prevent any requests from reaching 'regular' Grails controllers.

3.7 Vaadin Controllers

Grails treats Vaadin controllers like regular controllers. Therefore in general the features available to regular controllers should also be available to Vaadin controllers. See the controllers section of the Grails user guide for further details about controllers.

However, note that Vaadin controllers do not operate within the standard servlet request/response lifecycle. As such, some under-the-hood differences do exist, therefore not all controller functionality may work as expected in Vaadin controllers. Some key differences to be aware of are described in the following sections.

URIs and Fragments

As previously discussed, Vaadin Controllers are accessed in the browser by placing the controller name at the start of the browser fragment, rather than in the URI. So:

// Regular Grails Controller
http://localhost:8080/grailsapp/book/list
// Vaadin Controller
http://localhost:8080/grailsapp/vaadin#book/list

Controller API

Grails methods render, redirect, params, flash are specifically overridden in Vaadin controllers, to provide support for the plugin's page-dispatching mechanism. However, they can be treated like the corresponding regular Grails methods.

Vaadin Controllers can also render Vaadin Components directly, as in the following example:

import com.vaadin.ui.Label
class MyVaadinController {
	def index() {
		render new Label("Hello World!")
	}
}

Controllers can reference vaadinApplication to get the Vaadin Application object for the current session.

Passing Domain Instances

Unlike regular controllers, Vaadin controllers can receive Grails domain instances (and any other Java object) in their params map. By contrast, the params in a standard servlet request can only be strings.

This means that we can pass a domain instance from our controller to our view, which can then pass it to another controller in the params map of a link tag.

However, note that the second controller must merge the domain instance into its persistence session before using it. For example:

class BookController {
  def update {
    // Get the book instance passed in the params
    def book = params.instance
    // Attempt to merge Book instance into current persistence context
    def bookMergedAndValidated = book.merge()
    // Merging failed, possibly due to validation error
    if (!bookMergedAndValidated) {
      render(view: "edit", model: [bookInstance: book])
      return
    }
    // Merging succeeded, now you can save the instance
    bookMergedAndValidated.save(flush:true)
    [bookInstance: bookMergedAndValidated]
  }
}

3.8 Home Page and Error Page

Home Page

The Vaadin plugin includes a controller called HomeVaadinController. The index() method of this controller is called when the user's browser contains an empty fragment, or contains the fragment #home.

This controller simply renders your application's grails-app/views/vaadin/index.gsp view. You can edit this file directly to customise the home page.

For even more flexibility, you could create a HomeVaadinController in your app by running the following command:

grails create-vaadin-controller mypackage.Home

You could then customise this controller by for example redirecting to another controller as the default home page:

package mypackage
class HomeVaadinController {
	def index() {
		redirect controller:"book"
	}
}

Error Page

The Vaadin plugin includes a controller called ErrorVaadinController. The index() method of this controller is called whenever a Vaadin Controller or View throws an error.

This controller simply renders your application's grails-app/views/vaadin/error.gsp view. You can edit this file directly to customise the error page.

For even more flexibility, you could create a ErrorVaadinController in your app by running the following command:

grails create-vaadin-controller mypackage.Error

You could then customise this controller by for example redirecting to another controller as the default error page:

package mypackage
class ErrorVaadinController {
	def index() {
		redirect url:"http://google.com"
	}
}

3.9 Vaadin API

A Vaadin Class must:

• Exist under the grails-app/vaadin directory
• Have vaadin in its package name, or the package name of any of its superclasses.

The injected API is as follows:

Preventing API Injection

This can be easily achieved by moving a class to src/groovy instead of grails-app/vaadin

Accessing Vaadin Application

The following table summarises how to access the VaadinApplication object, in different contexts:

Example: Using VaadinApplicationContextHolder

import org.grails.plugin.vaadin.VaadinApplicationContextHolder
class MyClass {
	def myMethod() {
		// Gets the session's Vaadin Application
		def app = VaadinApplicationContextHolder.vaadinApplication
	}
}

3.10 Embedding Vaadin

The benefit of this approach is that your Vaadin Application is then hosted inside a <div> in a regular Grails view. You can then customize the 'host' view like any other Grails view - e.g use Sitemesh, or include other javascript and CSS resources using the <r:resource> tag. The Vaadin Application then just becomes one section of the page.

3.11 Base-Style vs Grails-Style

Base-Style

Grails-Style

4 Configuration

VaadinConfig

Other Configuration

Note that the Vaadin plugin depends on two external Vaadin addons. Therefore the Vaadin addons Maven repository needs to be included in the repositories closure in your app's grails-app/conf/BuildConfig.groovy. This is automatically added by command generate-vaadin-app.

The Vaadin addons Maven repository is http://maven.vaadin.com/vaadin-addons

5 Known Issues and Limitations

Sitemesh

The Vaadin plugin supports constructing Vaadin interfaces using GSP views. However, the GSP views are rendered using a mock HttpRequest/HttpResponse. The implementation does not currently support Sitemesh layouts. However, you can easily use the layout tag to use another GSP as a layout template.

Vaadin API

Although the Vaadin plugin's support for Controllers is a lot like standard Grails, it is a separate implementation. Therefore some of the methods that you expect to find in Grails Controllers may not be available in VaadinControllers. However, let us know if anything important is missing, and we'll work on getting those added.

6 Roadmap

7 Version History