Creating a module

grails create-gwt-module <module>

The above command will generate a module file and a corresponding client class under your project's src/java directory. If the name of the module includes a package (recommended), then the files are created in the appropriate directory path. For example:

grails create-gwt-module org.example.MyApp

will create the files

• src/java/org/example/MyApp.gwt.xml, and
• src/java/org/example/client/MyApp.java

Creating a host page

Once you have a module, you need to create an HTML page that will host the user interface elements defined by it. Again, this is as simple as running another Grails command:

grails create-gwt-page <page> <module>

The first argument specifies the page to create, and the second specifies which GWT module the page should host. The page is given as a relative path to a file, which can for example have an "html" or "gsp" extension. If the path consists of a single directory and a GSP file name, then it is treated as a controller view. Otherwise it is treated as a normal web page.

// This will create the view file: grails-app/views/main/index.gsp
grails create-gwt-page main/index.gsp org.example.MyApp

// This will create the file: web-app/dir/main.html
grails create-gwt-page dir/main.html MyModule

// This will create the file: web-app/index.gsp
grails create-gwt-page index.gsp org.example.AnotherModule

With the first method, the script will offer to create the relevant controller if it does not already exist.

Trying it out

GWT has something called hosted mode that allows you to test and debug your web interface from a custom browser. This is also available from the plugin. Just run this command:

grails run-gwt-client

This will launch the custom browser and point it at your running web application (it would be a good idea to run grails run-app in one console, and this in another). If your web app is not running on the local machine, or it is not running on the default port (8080), you can pass a parameter to the script to point the custom browser at a different URL:

// Non-local host on port 8080.
grails run-gwt-client myServer

// 'localhost' with a non-default port.
grails run-gwt-client 9090

// Combined.
grails run-gwt-client myServer:9090

Server-side RPC

Almost any non-trivial GWT application will require the use of its RPC support at some stage. GWT normally requires you to write a servlet for each service interface that you define, but the plugin simplifies this step by allowing you to implement the server-side RPC with normal Grails services. Any service can be configured for GWT by adding an expose property, as is done with the Remoting plugin and others:

class MyService {
    static expose = [ 'gwt:example.client' ]

    List listUsers() {
        ...
    }
    ...
}

The format of the GWT expose entry is basically: gwt:<package> where <package> is the java package in which the associated RPC interfaces will be created. This will normally match a particular module's entry point package.

You should now run the application (grails run-app) so that the plugin generates the required RPC interfaces. The plugin will also update these interfaces as you make changes to your service unless you modify the interfaces yourself. As soon as you make changes to them, the plugin will stop synchronising them with the corresponding Grails service. This allows you to maintain full control of the interface definitions, although you lose the convenience of automatic synchronisation.

• src/java/example/client/MyService.java, and
• src/java/example/client/MyServiceAsync.java

Note If you modify either file yourself, then the plugin will no longer update them automatically. This is to ensure that any changes that you make are preserved, such as adding '@gwt.typeArgs' javadoc annotations.

When accessing the service from your client GWT code, use the URL described in this example:

MyServiceAsync myService = (MyServiceAsync) GWT.create(MyService.class);

ServiceDefTarget endpoint = (ServiceDefTarget) myService;

// Note the URL where the RPC service is located!
String moduleRelativeURL = GWT.getModuleBaseURL() + "rpc";
endpoint.setServiceEntryPoint(moduleRelativeURL);

// Call a method on the service!
List users = myService.listUsers()
...

import org.codehaus.groovy.grails.plugins.gwt.annotation.CollectionTypeArg
import org.codehaus.groovy.grails.plugins.gwt.annotation.MapTypeArg

class MyService {
    static expose = [ 'gwt:example.client' ]

    // The return list contains objects of type java.lang.String.
    @CollectionTypeArg(String)
    List listUsers() {
        ...
    }

    // The 'arg' parameter is a map whose keys are java.lang.Integers,
    // and values are java.lang.Strings.
    void processMap(@MapTypeArg(key=Integer, value=String) Map arg) {
        ...
    }
    ...
}

Compiling the GWT modules

The plugin will automatically compile your GWT modules the first time that you perform a normal Grails compile, for example via grails compile or grails run-app. Once a module has been compiled, however, it will not be compiled again in development mode. This is fine if you are using GWT's hosted mode to test your application, but any changes will not be picked up when using a standard browser. So, if you want to test the latest changes in development with a normal browser, you can manually compile the GWT modules with this command:

grails compile-gwt-modules

Creating a WAR

This is as simple as running the normal Grails command:

grails war

The plugin will ensure that the GWT modules are re-compiled before everything is packaged up in the WAR file. Once that's done, you can deploy your web application to any servlet container as normal.