In order to run the sample application, you need to install GWT on your developer machine. If you already have GWT installed, you can skip this section; just make sure that you have the correct version installed. This book is targeted at GWT version 1.5, so make sure you have at least this version. Furthermore, you'll need a Java SDK of at least version 1.5. You can download the Java SDK from http://java.sun.com.

The first thing you have to do is download the binary distribution from Google. Google has put the toolkit distribution on their developer community site at http://code.google.com. Google uses this site to host their APIs and libraries, but you can host your project there as well. The project site for the toolkit can be found at http://code.google.com/webtoolkit. Besides the distribution, you'll find the reference API, sample applications, blogs, articles, and a lot of third-party libraries that provide additional functionality for GWT. When you click the download link, the site suggests the latest GWT release for your operating system. Fortunately, there's little difference in developing GWT applications on the different platforms. We'll use the Windows platform as an example, as it's still the most commonly used platform. However, developing on other platforms should be quite similar.

It has proved necessary to maintain separate distribution kits for the three major platforms (Windows, Mac, and Linux), because the hosted mode environment uses a different browser depending on the platform to visualize the application. On the Windows platform, GWT uses Internet Explorer, whereas on Linux it comes with a packaged version of Mozilla Firefox. It's important to know that the compiled and deployable application, which consists of JavaScript and HTML, will work on all platforms and browsers. And more important, this is done without you having to worry about the differences during development.

After downloading the distribution pack, you should unpack the archive into a convenient place. For easy reference, you can add an environment variable (GWT_HOME) pointing to this place. Because GWT comes with a set of command-line scripts, we also advise you to add the installation directory to your PATH environment variable so the scripts can be called from any location without an explicit reference to the installation directory.

Figure 3-1. The content of the GWT Windows binary distribution package

Figure 3-1 shows the content of the binary distribution for the Windows platform. The package consists of the following sets of files:

Now that you have GWT installed on your system and have a basic understanding of what's inside, you're ready to start your first project. The guys at Google created a convention for the structure of GWT projects. It remains popular for authors of toolkits such as GWT to use the principle of convention over configuration, eliminating large and complex configuration files but without losing the flexibility to configure the toolkit any way you like. Before we tell you how to configure GWT to fit any structure, let's look at the structure Google proposes. We'll show what their convention looks like by creating the first part of our sample application.

You start with a directory for the project (gwtasks). Inside this directory, only one subdirectory is needed. That's where the sources are placed, so it should be no surprise that it's called src. Here you can create a package structure just as with any other Java application. Figure 3-2 shows the directory structure for your project. In the package structure, you can see three files with the same name, but different extensions. Each of these files is essential to GWT. Together they define the GWT module for the application.

As you can see, the Java file is placed inside a client folder. Every class in the client package will be compiled into JavaScript by the GWT compiler. The class inside GWTasks.java extends the GWT class EntryPoint and represents the start of our application. In this respect, it's just like the main method for a Java application.

Figure 3-2. Directory structure of a basic GWT application

The HTML file is placed inside a folder called public. This is where all resources that should be made available to the client, such as images and style sheets, will go. The HTML file is our visual starting point. It contains a basic HTML structure in which we'll place our user interface and a JavaScript include tag pointing to our GWT module.

The third file contains the configuration of our GWT module. Here, we can enable and configure specific GWT features we want to use. For now, two things get configured here: we specify that we want the GWT user interface components and we specify which class will be our entry point.

Fortunately, we won't have to create this directory structure ourselves. GWT comes with a set of easy-to-use scripts. Two of these scripts are particularly convenient for starting a new GWT module.

Application Creator Script

The application creator script creates a project structure as described in the previous section. Calling it without any arguments will display the argument options. Note that because we added the GWT installation directory to our PATH environment variable, we don't have to refer to the installation directory. Instead, we can call the script directly.

>applicationCreator
Missing required argument 'className'
Google Web Toolkit 1.5.0
ApplicationCreator [-eclipse projectName] [-out dir] [-overwrite] [-ignore] 

 [-addToClassPath classPathEntry] [-addModule module] className

where
  -eclipse         Creates a debug launch config for the named eclipse project
  -out             The directory to write output files into (defaults to current)
  -overwrite       Overwrite any existing files
  -ignore          Ignore any existing files; do not overwrite
  -addToClassPath  Adds extra elements to the class path.
  -addModule       Adds extra GWT modules to be inherited.
and
  className        The fully-qualified name of the application class to create

Only one argument is mandatory: the fully qualified class name of the GWT application. As we've seen in Figure 3-2 the package name of the class should end with client. This is part of the GWT convention, and is enforced by the applicationCreator script. The optional argument eclipse allows you to specify an Eclipse launcher configuration to start the application in hosted mode from within Eclipse. This is particularly useful when debugging the GWT module. With the optional out argument, you can specify the folder in which the application should be created. If this is omitted, the application gets created in the current folder. The options ignore and overwrite allow you to specify whether existing files can be overwritten or should be ignored—that is, not re-created. These options are used when you want to regenerate some of the files. For example, you would use the ignore option if you messed up the .gwt.xml file and want the original file back. Just delete the .gwt.xml file and call applicationCreator again. If you just want to start again, you can use the overwrite option. The files you've created will remain untouched, but the script will overwrite any of the files it generates. In particular, this means it will overwrite the .java, .gwt.xml, and .html files. Finally, the options addToClassPath and addModule enable you to configure your project environment. The first allows you to extend your classpath by passing an additional library. The latter is used to enable the use of other GWT modules. More on this feature can be found in Chapter 6.

Besides creating the project structure and the three basic GWT-files, the application creator script creates two convenient scripts in the root of the project: one to compile the project and another to run the project in hosted mode. Both scripts call a Java application with the required GWT libraries on the classpath.

Let's start creating the sample application by making a call to this script. We want it to create an Eclipse launcher called gwtasks and put everything in a folder with the same name. Our module name should be GWTasks, and it should be in package com.apress.gwt.client.

> applicationCreator -eclipse gwtasks -out gwtasks com.apress.gwt.client.GWTasks
Created directory gwtasks/src
Created directory gwtasks/src/com/apress/gwt
Created directory gwtasks/src/com/apress/gwt/client
Created directory gwtasks/src/com/apress/gwt/public
Created file gwtasks/src/com/apress/gwt/GWTasks.gwt.xml
Created file gwtasks/src/com/apress/gwt/public/GWTasks.html
Created file gwtasks/src/com/apress/gwt/public/GWTasks.css
Created file gwtasks/src/com/apress/gwt/client/GWTasks.java
Created file gwtasks/GWTasks.launch
Created file gwtasks/GWTasks-shell
Created file gwtasks/GWTasks-compile

Now that we have our application, we can start it. Step inside the newly created project folder and make a call to the GWTasks-shell script. This will launch the hosted mode browser and point it at our freshly created application, which should look like Figure 3-3. Go ahead and have a look around the web site. As you can see, it already contains some sample functionality.

Figure 3-3. Running the sample application in hosted mode

>projectCreator
Please specify either -ant or -eclipse.
Google Web Toolkit 1.5.0
ProjectCreator [-ant projectName] [-eclipse projectName] [-out dir] 

[-overwrite] [-ignore] [-addToClassPath classPathEntry]
where
  -ant             Generate an Ant buildfile to compile source (.ant.xml will be 

appended)
  -eclipse         Generate an eclipse project
  -out             The directory to write output files into (defaults to current)
  -overwrite       Overwrite any existing files
  -ignore          Ignore any existing files; do not overwrite
  -addToClassPath  Adds extra elements to the class path.

gwtasks> projectCreator -ant gwtasks -eclipse gwtasks
Created directory test
Created file gwtasks.ant.xml
Created file .project
Created file .classpath

Now that we have our project set up, we can open it inside our IDE. In Appendix A, you can read more detailed information on how to use either Eclipse or IntelliJ Idea for GWT development. Let's start building our sample application with a simple component. You need a logon screen to register for the application. It will be quite simple, showing two input fields with a description and a button to perform the login action.

<html>
    <head>
        <script language='javascript' src='com.apress.gwt.GWTasks.nocache.js'>
        </script>
    </head>
    <body>
        <table align=center>
            <tr>
                <td id="slot1"></td>
            </tr>
        </table>
    </body>
</html>

public void onModuleLoad() {
    final TextBox username = new TextBox();
    final PasswordTextBox password = new PasswordTextBox();
    final Button button = new Button("Logon");
    final VerticalPanel panel = new VerticalPanel();
    panel.add(new Label("username"));
    panel.add(username);
    panel.add(new Label("password"));
    panel.add(password);
    panel.add(button);
    RootPanel.get("slot1").add(panel);
}

We have now written enough code to compile and run. Although it contains no functionality whatsoever, it does include some visual components. You can see the resulting output by starting the application in hosted mode, either by calling the GWTasks-hosted script in the root of our project or, if you're using Eclipse, by using the Eclipse launcher. The result should look something like Figure 3-4.

Figure 3-4. The logon screen in hosted mode

Another way to check the result is to compile the code into JavaScript by calling the GWTasks-compile script and open the result in your favorite web browser. The script creates a folder called www containing the web site. As the application doesn't contain any server-side code yet, the generated files can be hosted by any web server. It's completely platform-independent and contains only HTML and JavaScript.

Of course, there's no point in leaving the application like this. We want to introduce some functionality as well. Let's extend our panel by creating a welcome message when the user logs on with a known password. For this, we need to create an action that will be triggered when the button is clicked. We can add an EventListener to the Button and program the actions that need to be performed when the Button is clicked. Add the code from Listing 3-3 to the onModuleLoad method underneath the line that creates the Button. This code adds behavior to the click event. The onClick method is called whenever the Button gets clicked. We're using an anonymous inner class to define the logic that needs to be executed. Note that we can reference both the username and the password variable because we declared them as final in Listing 3-2.

...
button.addClickListener(new ClickListener() {
    public void onClick(Widget sender) {
        if("secret".equals(password.getText())) {
            Window.alert("Welcome " + username.getText());
        } else {
           Window.alert("Invalid authentication");
        }
    }
});
...

The call to the Window.alert method gets translated to the JavaScript alert method. It triggers a pop-up dialog box containing the text as a warning. You normally don't want to use this in your application except for debugging, but for the application in its current state, it will suffice.

If you still have the hosted mode running, all you need do to see and test the result is click the Refresh button in your browser window. This is one of the great advantages of GWT: it enables you to develop the front end without needing to recompile the entire application continuously. This results in a short development cycle. Depending on the input in the text boxes, the application now shows us either Figure 3-5 or Figure 3-6.

Figure 3-5. Using the logon screen with valid credentials

Figure 3-6. Using the logon screen with invalid credentials

If you would style every element inside your HTML page separately, you would have a hard time achieving a consistent style throughout your application. Fortunately, you can define your styles in a central place and bind these styles to the HTML elements. Each style can be bound either by creating a style for a specific tag or by defining a style and binding it to tags using the class attribute. These style definitions can either be defined in the head section of your HTML page or be included from a Cascading Style Sheet (CSS) file.

Every GWT component has its own style classifications associated with it. That way you can easily create a stylesheet for your GWT application without needing to assign style names to every component you create. This helps to make sure that your code remains clean. Of course, you may add or replace the style names with names of your choice. The GWT Javadoc contains a section about the CSS style rules that apply to each component by default. The GWT Javadoc is included in the binary package and available online at http://google-web-toolkit-doc-1-5.googlecode.com/svn/javadoc/1.5/index.html. For example, the TextBox class by default has the style name .gwt-TextBox assigned to it. Furthermore, the style name .gwt-TextBox-readonly is defined to style the text box when the readonly flag is set.

Now that we know that every component already has a style name associated with it, we can start creating a stylesheet. There are two ways to link a stylesheet to the application. The most commonly known way is to link it inside the HTML file like this:

<html>
        <head>
                <link rel="stylesheet" href="gwtasks.css"/>
        </head>
        ...

Of course, there's also the option of specifying the styles inside the HTML directly, but best practice is to put the styles in a separate file.

GWT also provides a way to link the stylesheet more tightly to the Java code. Inside the module descriptor, you can specify stylesheets that are specific for your module by adding the following code somewhere inside GWTasks.gwt.xml:

<module>
       ...
        <stylesheet src="GWTasks.css"/>
        ...
</module>

The results are the same, as GWT dynamically writes every stylesheet in the descriptor into the resulting HTML page. The major benefit of this procedure arises when you're going to use the GWT module inside another application. In that case, you don't want to be forced to find out which stylesheets need to be included into your application just because you're using another module.

Now that we're referring to a stylesheet, we had better create one. The GWTasks.css file is created in the same directory as the .html file, so we need to open the stylesheet from the public folder. Inside the stylesheet, we can define formats for HTML elements and style classes. For now, we only want to style the GWT components we've used so far. By defining the following style, all the labels will have a font size of 9 pixels:

.gwt-Label {
        font-size: 9px;
}

Both text boxes and the button can be styled with the same style definition. Here we also want the font size to be 9, but we also want to define a fixed width and height for the objects:

.gwt-Button, .gwt-TextBox, .gwt-PasswordTextBox {
        font-size: 9px;
        height: 19px;
        width: 75px;
}

Hitting the Refresh button in the hosted-mode browser immediately shows the result of our new style. Figure 3-7 shows our final logon screen.

Figure 3-7. The styled logon panel

While we have a relatively simple application, the code is easy to understand. But as soon as we start extending the application to a reasonable size, we want to be able to debug it. Fortunately, every GWT application can be debugged with the standard Java debug tools, because in hosted mode, the Java code is interpreted inside a normal Java Virtual Machine (JVM) instead of being compiled to JavaScript. If you're developing inside an IDE, starting the hosted mode in debug mode and connecting your debugger to the process is as easy as clicking a button. In Eclipse, you can use the launcher that was created by the application creator script. If you start the hosted mode through the GWT scripts, you need to manually change the script and add two parameters to the Java call. To enable the debugger, you have to add -Xdebug. This option enables the debug mode inside the JVM. Furthermore, you have to specify how you're going to connect to the JVM. Therefore, you have to add the option -Xrunjdwp as well. This is used to specify a number of options, including the port number on which the debugger can connect to the JVM. The complete script should look like Listing 3-4.

java  -Xdebug 

-Xrunjdwp:transport=dt_socket,address=127.0.0.1:52996,suspend=y,server=n 

-cp "$APPDIR/src:$APPDIR/bin:$GWT_HOME/gwt-user.jar:$GWT_HOME/gwt-dev-linux.jar" 

com.google.gwt.dev.GWTShell -out "$APPDIR/www" "$@" 

 com.apress.gwt.GWTasks/GWTasks.html

After starting your application in hosted mode, the debugger can connect to the JVM on port 52996.

Now you've seen the fundamentals of GWT. We started this chapter by configuring our development environment. You've seen where to get the GWT distribution and should have an understanding of what it contains. Your development environment is set up and ready to start creating your GWT applications.

Using the command-line scripts from the distribution package, you can create a basic application, run it, and debug it. You've also seen how you can adjust the basic application and have begun creating the sample application. Using a limited set of GWT classes, you've created a basic logon screen and styled it using a stylesheet.

Chapter 4 will give a more thorough introduction on the widgets GWT provides. Using these widgets will enable you to build more enhanced and interactive interfaces.