Let’s start by creating a directory to place our GWT project in. Create a new directory named StockWatcher under the main GWT directory (e.g., gwt-windows-1.5.3). To actually create our project we’ll use some command-line utilities that ship with GWT. These utilities take care of generating the project subdirectories and files we need to get started.
If you’re using Eclipse, the first utility you’ll run is projectCreator (if you’re not using Eclipse, skip ahead to the section on applicationCreator). The projectCreator utility will generate a shell Eclipse project for our application. Open a command shell and browse to the StockWatcher directory you created. Run the command:
After the projectCreator utility runs, you should see that it has generated a new directory called StockWatcher containing a couple of subdirectories (src and test for storing the project source code and unit tests) and a pair of Eclipse files (.project and .classpath).
Next we’re going to use the applicationCreator utility to generate a minimal but functional GWT project. We’ll need to pass it the fully-qualified name of our application’s main entry point class. Based on the recommended GWT project structure, this class should always be in a subpackage client. For our StockWatcher application we’ll name our main class com.google.gwt.sample.stockwatcher.client.StockWatcher.
The applicationCreator utility can also generate Eclipse launch config files for easy hosted mode debugging. Just specify the -eclipse flag followed by the name of your Eclipse project.
In a command shell, browse to the StockWatcher directory. If you’re using Eclipse, run the command:
$PP_OFF applicationCreator -eclipse StockWatcher -out StockWatcher com.google.gwt.sample.stockwatcher.client.StockWatcher
If you’re using another IDE, omit the -eclipse flag and project name:
$PP_OFF applicationCreator -out StockWatcher com.google.gwt.sample.stockwatcher.client.StockWatcher
Now take a look inside the StockWatcher directory. You’ll see that the applicationCreator has generated two scripts for us named StockWatcher-compile and StockWatcher-shell. These scripts will help us prepare StockWatcher for deployment, or run the application in hosted mode, respectively.
Let’s go ahead and try running our nascent StockWatcher application in hosted mode right now by running the StockWatcher-shell script. When you do, you should see two new windows appear. The first is the Development Shell, which contains a log viewer to display status and error messages. The second is the hosted mode web browser. This is where your GWT application lives while running in hosted mode. You can interact with the application in hosted mode just as you would when it’s eventually deployed.
The applicationCreator can automatically generate launch configurations for debugging our GWT applications in hosted mode with Eclipse. To use them, we’ll need to first import the StockWatcher project into Eclipse.
Now that we have our initial version of StockWatcher up and running, let’s talk about what makes up a GWT project. Going back to the StockWatcher directory we created, note that applicationCreator has created a set of nested directories under the src subdirectory corresponding to the packages containing our GWT application.
<module> <!-- Inherit the core Web Toolkit stuff. --> <inherits name='com.google.gwt.user.User'/> <!-- Inherit the default GWT style sheet. You can change --> <!-- the theme of your GWT application by uncommenting --> <!-- any one of the following lines. --> <inherits name='com.google.gwt.user.theme.standard.Standard'/> <!-- <inherits name="com.google.gwt.user.theme.chrome.Chrome"/> --> <!-- <inherits name="com.google.gwt.user.theme.dark.Dark"/> --> <!-- Other module inherits --> <!-- Specify the app entry point class. --> <entry-point class='com.google.gwt.sample.stockwatcher.client.StockWatcher'/> <!-- Specify the application specific style sheet. --> <stylesheet src='StockWatcher.css' /> </module>
This is a GWT module. The module contains the configuration settings (in the form of an XML file) for a particular GWT application or library. Our newly-created module contains two <inherits> tags, an <entry-point> tag, and a stylesheet tag. The <inherits> tags tells GWT which additional modules your application depends on. This may be one or more of the built-in modules or other GWT modules you developed. We only need to inherit one built-in GWT module to create a GWT application: com.google.gwt.user.User, which contains the core GWT libraries. The default application also inherits com.google.get.user.theme.standard.Standard, which adds default styles to the Widgets used in the application (see Add CSS styling for more info).
The <entry-point> tag tells GWT which Java class is your application’s startup class. This class must implement the EntryPoint interface, which defines one method: onModuleLoad(). The onModuleLoad() method is the place to do any initialization your application needs to perform, such as creating the UI elements and registering event handlers. Our application’s main class is com.google.gwt.sample.stockwatcher.client.StockWatcher.
The <stylesheet> tag tells GWT to include a style sheet names StockWatcher.css, which is located in the public directory of the application.
If you browse to the directory src/com/google/gwt/sample/stockwatcher/client you’ll find the source file for that class in StockWatcher.java. Right now it contains very simple “Hello, World” style functionality, which we’ll soon replace with our StockWatcher code. In general, the client directory will contain all of our client-side source files and any subpackages.
StockWatcher.html is our application’s host page. A host page is the container for a GWT application. It’s a regular HTML file that contains a <script> tag pointing to your application’s startup script. This script is named after the fully-qualified module name, followed by .nocache.js:
We’ll revisit our StockWatcher.html host page as we build the sample. For the time being, though, just keep in mind that it functions as our GWT application’s container and that it must reference our .nocache.js startup script.
Our application also includes a CSS style sheet that contains some basic style definitions used in the application. You can add or remove style definitions just like you would in a traditional web application.
In addition to the style sheet created by application creator, you can use any one of the visual themes that GWT provides. The visual themes add default styles to all of your GWT widgets, giving your application a more polished look. See the tutorial on Adding CSS styling for more information.
One additional fact you should know about host pages is that they don’t have to be new HTML files created from scratch. The flexible architecture of GWT makes it a snap to integrate GWT with existing web pages, including those that use a server-side template framework.
Let’s say, for example, that your existing website was built with PHP. You’d like to add some client-side behavior to one of your pages using GWT. No problem. Just add a <script> tag pointing to the GWT startup script inside your PHP page’s <head> tag:
By adding that one line, this PHP page has become a host page for GWT. You can add GWT widgets and client-side behaviors to it just as you can with static .html host pages. GWT does not need to explicitly support PHP for this to work. In fact, since GWT runs on the client-side (unlike server-side PHP scripts), it is not even aware of the fact that the host page was dynamically generated with PHP. To GWT, it’s just another host page. This means that GWT can seamlessly work with whatever server-side framework you happen to use, be it PHP, Ruby on Rails, or even ASP.NET.