Google Web Toolkit - Getting Started Guide

Google Web Toolkit
Search Google Code:

# Google Web Toolkit Getting Started Guide

## Table of Contents

## Installing Google Web Toolkit

1. Install the Java SDK.
   If you don't have a recent version of the Java SDK installed, download and install Sun Java Standard Edition SDK.
2. Download Google Web Toolkit.
   Download the Google Web Toolkit package for your operating system.
3. Unzip the Google Web Toolkit package.
   On Windows, extract the files from `gwt-windows-@GWT_VERSION@.zip` with a program like WinZip. On Mac and Linux, you can unpack the package with a command like

       tar xvzf gwt-mac-@GWT_VERSION@.tar.gz

4. Done! Start using Google Web Toolkit.
   GWT doesn't have an installer application. All the files you need to run and use GWT are located in the extracted directory. The main application you'll need to use GWT is `applicationCreator`, which is described below. It may be easiest to start out by building one of the sample applications shipped with GWT.

## Building a Sample Application

All the sample applications are in the `samples/` directory in your GWT package. Each sample has a script you can run to start it in hosted mode and a script you can use to compile it into JavaScript and HTML to run it web mode.

### Running in Hosted Mode

To run the Mail sample in hosted mode, navigate to the `samples/Mail/` directory and run the `Mail-shell` script. This will open the GWT browser with the Mail application running inside:

Since you're running in hosted mode, the application is running in the Java Virtual Machine (JVM). This is typically the mode you'll use to debug your applications.

### Running in Web Mode

To run the application in web mode, compile the application by running the `Mail-compile` script. The GWT compiler will generate a number of JavaScript and HTML files from the Mail Java source code in the `www/` subdirectory. To see the application, open the file `www/com.google.gwt.sample.mail.Mail/Mail.html` in your favorite web browser.

Since you've compiled the project, you're now running pure JavaScript and HTML that should work in IE, Firefox, or Safari. If you were to deploy the Mail example project in production, you would distribute the files in your `www/com.google.com.google.gwt.sample.mail.Mail/` directory to your web servers.

### Make a Few Changes

The source code for Mail sample is in the `src/` subdirectory. Try closing your browser windows, and open the file `src/com/google/gwt/sample/mail/client/Shortcuts.java` in a text editor. Line 55 of the file adds a new "Tasks" section to the main StackPanel on the left side of the application:

    add(images, new Tasks(), images.tasksgroup(), "Tasks");

Change the string from `"Tasks"` to `"To-Do List"`:

    add(images, new Tasks(), images.tasksgroup(), "To-Do List");

Now, save the file and simply click "Refresh" in the hosted mode application to see your recent change (if you previously closed hosted mode, go ahead and re-run the `Mail-shell` script). The second item in the main StackPanel should now say "To-Do List" instead of "Tasks":

## Creating an Application from Scratch (without Eclipse)

GWT ships with a command line utility called `applicationCreator` that automatically generates all the files you'll need in order to start a GWT project. It can also generate Eclipse project files and launch config files for easy hosted mode debugging, as described below.

Based on the recommended GWT project structure, your main GWT application class should be in a subpackage `client`. You can create a new application called MyApplication with the command:

    applicationCreator com.mycompany.client.MyApplication

The `applicationCreator` script will generate a number of files in `src/com/mycompany/`, including some basic "Hello, world" functionality in the class `src/com/mycompany/client/MyApplication.java`. The script also generates a hosted mode launch script called `MyApplication-shell` and a compilation script called `MyApplication-compile`, just like the sample application above.

To run your newly created application in hosted mode, run the `MyApplication-shell` script:

Try editing the files `src/com/mycompany/client/MyApplication.java` and `src/com/mycompany/public/MyApplication.html` to see how it changes your application.

## Creating an Application from Scratch (with Eclipse)

GWT includes a command line utility called `applicationCreator` that automatically generates all the files you'll need in order to start a GWT project. It can also generate Eclipse project files and launch config files for easy hosted mode debugging. To generate an Eclipse project for a new application, first use the `projectCreator` script to generate a shell Eclipse project for your application:

    projectCreator -eclipse MyProject

Then generate your GWT application as described above, but with an additional `-eclipse` flag specifying the name of your Eclipse project:

    applicationCreator -eclipse MyProject com.mycompany.client.MyApplication

When you're done with these scripts, in addition to the `MyApplication-shell` and `MyApplication-compile` scripts, you should see `.project`, `.classpath`, and `MyApplication.launch` files in your current directory.

To open your project in Eclipse, launch Eclipse and click the File -> Import menu. Choose "Existing Projects into Workspace" in the first screen of the wizard, and enter the directory in which you genetrated the `.project` file in the next screen of the wizard. When you are complete, you should see your GWT project loaded into your Eclipse workspace:

Just click the green "Run" button at the top of the window to start your project in hosted mode.