Tutorial:Introduction to GWT-Ext 2.0

From GWT-Ext

Let's get started with setting up your machine to build GWT applications. We'll cover every step required to build GWT-Ext applications from scratch, so if you're new to GWT-Ext or GWT in general, this is a great place to start. If you're comfortable with GWT applications and would rather use an IDE, please visit Using Eclipse for a brief tutorial on how to use Eclipse and the Cypal Studio plugin for Eclipse to build GWT applications.

Download the required resources

The basic components that you need to start building beautiful, web-based GWT-Ext applications by writing your applications entirely in Java code and harnessing the versatile widgets in the ExtJS library are

1. The Java SE SDK
2. The Google Web Toolkit
3. The ExtJS javascript library
4. The GWT-Ext library

The Java SDK cane be obtained from Sun's Java webpage's downloads section. After completing the installation process, it is recommended that you set the JAVA_HOME system variable on your machine to point to the installation directory of the Java SDK.

Download the GWT

The Google Web Toolkit contains extensive documentation and tutorials which describe the basics of how to build effective GWT applications. We suggest you start at the fundamentals section of the documentation for a quick overview of how GWT applications' code is structured.

Download the latest GWT toolkit library and extract it to a local folder on your machine. We suggest setting up a GWT_HOME system variable and adding it to your system's path to help give quick access to the GWT toolkit commands.

Download the ExtJS library

The ExtJS library is again a well documented JavaScript library with a host of rich widgets and components. Download the latest Library from their site or version 2.0.2 from here. Note that Ext version 2.1 and greater is license under GPL and if that doesn't meet your requirements you can download Ext 2.0.2 which has LGPL as one of its licensing options.

The library comes bundled with the source code, many examples and the complete documentation. These folders are not required for building our applications however, but are quite helpful.

The folders and files that are needed are:

* /adapter
* /resources
* ext-all.js
* ext-all-debug.js
* ext-core.js
* ext-core-debug.js

Download the GWT-Ext library

The latest gwtext.jar library file can be obtained from the SVN repository at the project's Google Code page. A More comprehensive description is avaiable on the Main Page. You should, soon, be able to download the library directly from the download section of this site - watch this space for updates.

The library comes bundled with the gwtext.jar archive, the javadoc files for the library and sample code to help you dive into real world GWT-Ext applications.

Getting Started

We've included a handy all-but-ready-for-you-to-run archive to your right. Download this archive and extract to a folder of your choice: C:\GWT-Demo\ for example. Download the ExtJS library files from the ExtJS downloads page, and place them under the src/com/mycompany/mypackage/public/js folder. Now, all you need to do is specify the location of the Google Web Toolkit installation in the HelloWorld-shell.cmd

@java -cp "%~dp0\src;%~dp0\bin;C:/Program Files/Google Web Toolkit/gwt-user.jar;C:/Program Files/Google Web Toolkit/gwt-dev-windows.jar;./lib/gwtext.jar" com.google.gwt.dev.GWTShell -out "%~dp0\www" %* com.mycompany.mypackage.HelloWorld/HelloWorld.html

and HelloWorld-compile.cmd.

@java -cp "%~dp0\src;%~dp0\bin;C:/Program Files/Google Web Toolkit/gwt-user.jar;C:/Program Files/Google Web Toolkit/gwt-dev-windows.jar;./lib/gwtext.jar" com.google.gwt.dev.GWTCompiler -out "%~dp0\www" %* com.mycompany.mypackage.HelloWorld

The portions of the command highlighted in red need to be changed to point to the correct location of your GWT installation. Once you have these files configured, you can run the HelloWorld application by running the following command:

HelloWorld-shell

This will launch the GWT Development Shell and a Hosted Browser with the content generated in the com.mycompany.mypackage.client.HelloWorld class.

Build from scratch

The process to create the example included follows below. Navigate to the folder you want to create your application in (C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext on my windows based machine). If you've set up the GWT_HOME system variable, you can directly run the following command:

applicationCreator com.mycompany.mypackage.client.HelloWorld

This will generate the following output:

Created directory C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src
Created directory C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src\com\mycompany\mypackage
Created directory C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src\com\mycompany\mypackage\client
Created directory C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src\com\mycompany\mypackage\public
Created file C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src\com\mycompany\mypackage\HelloWorld.gwt.xml
Created file C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src\com\mycompany\mypackage\public\HelloWorld.html
Created file C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\src\com\mycompany\mypackage\client\HelloWorld.java
Created file C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\HelloWorld-shell.cmd
Created file C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext\HelloWorld-compile.cmd

Configuring Your Application

Now that we have the skeleton of the GWT application working, let's customize it for GWT-Ext.

Locate the gwtext.jar archive on your machine and copy it to <root>/Hello GWT-Ext/lib. You will have to create the lib folder. Now, add the path to the jar file in the HelloWorld-shell.cmd and HelloWorld-compile.cmd executable files. You can edit these files in your favorite text editor (We suggest Notepad2 as it's a very rich and light-weight replacement for notepad on Windows).

The existing content of the HelloWorld-shell.cmd file should look something like this:

@java -cp "%~dp0\src;%~dp0\bin;C:/Program Files/Google Web Toolkit/gwt-user.jar;C:/Program Files/Google Web Toolkit/gwt-dev-windows.jar" com.google.gwt.dev.GWTShell -out "%~dp0\www" %* com.mycompany.mypackage.HelloWorld/HelloWorld.html

With the GWT-Ext jar file at lib/gwtext.jar, we need to add a reference this to the compiler's path. This can be done easily at the end of the command which includes the GWT core jar libraries:

@java -cp "%~dp0\src;%~dp0\bin;C:/Program Files/Google Web Toolkit/gwt-user.jar;C:/Program Files/Google Web Toolkit/gwt-dev-windows.jar;./lib/gwtext.jar;" com.google.gwt.dev.GWTShell -out "%~dp0\www" %* com.mycompany.mypackage.HelloWorld/HelloWorld.html

Similarly, the HelloWorld-compile.cmd file can be modified to include the GWT-Ext library archive.

@java -cp "%~dp0\src;%~dp0\bin;C:/Program Files/Google Web Toolkit/gwt-user.jar;C:/Program Files/Google Web Toolkit/gwt-dev-windows.jar;./lib/gwtext.jar;" com.google.gwt.dev.GWTCompiler -out "%~dp0\www" %* com.mycompany.mypackage.HelloWorld

Next, navigate to the location of the HelloWorld.gwt.xml configuration file located in the src/com/mycompany/mypackage folder. Open the file for editing and add the following inherits property under the module tag to include the GWT-Ext library packages to the application:

<module>
	<!-- Inherit the core Web Toolkit stuff.                  -->
	<inherits name='com.google.gwt.user.User' />
	<!-- Inherit the GWTExt Toolkit library configuration.	  -->
	<inherits name='com.gwtext.GwtExt' />
	<!-- Specify the app entry point class.                   -->
	<entry-point class='com.mycompany.mypackage.client.HelloWorld' />
	<stylesheet src="js/ext/resources/css/ext-all.css" />
	<script src="js/ext/adapter/ext/ext-base.js" />
	<script src="js/ext/ext-all.js" />
</module>

The ExtJS library files go under src/com/mycompany/mypackage/public/js/ext. The folders and files listed above in the previous section are all you need to run your GWT-Ext applications.

This should complete the configuration of your application. Now let's move on to writing the code.

The HTML code

The standard HTML markup generated by the GWT applicationCreator.cmd is pretty rudimentary. So let's add our own standards compliant markup. This should get you closer to generating pages which will (hopefully) validate with the W3C validation service. Apart from this, we also need to include the ExtJS library references to the markup.

The final page should look as shown below:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
   <head>
      <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
      <meta http-equiv="Content-Language" content="en-us">
      <meta http-equiv="Content-Author" content="Sankar Gorthi">
      <title>Hello World</title>
   </head>
   <body>
      <iframe id="__gwt_historyFrame" style="width:0;height:0;border:0"></iframe>
      <!-- The GWT js file generated at run time -->
      <script type="text/javascript" src='com.mycompany.mypackage.HelloWorld.nocache.js'></script>
   </body>
</html>

Of note is the reference to the GWT generated JS code:

<script type="text/javascript" src='com.mycompany.mypackage.HelloWorld.nocache.js'></script>

In all your applications, this will be the only line which requires to be changed.

The Java Code

The GWT Application Creator script generates some Java code to demonstrate the Ajax capabilities of GWT. We'll first pare the code down to the bone and add our own.

package com.mycompany.mypackage.client;
 
import com.google.gwt.core.client.EntryPoint;
 
/**
 * @author Sankar
 * 
 */
public class HelloWorld implements EntryPoint {
 
   public void onModuleLoad() {
      // Add your code here
   }
 
}

All GWT modules need atleast one class which implements the EntryPoint interface's methods. A detailed description of the structuring of GWT applications can be found in the GWT documentation. In any case, the EntryPoint interface contains the onModuleLoad() method which must be implemented. If you have worked with the ExtJS library, you'll see that it is quite like the Ext.onReady() method. Or, it could be assumed to be similar to the body.onload() function fired in all browsers when the page is loaded.

In essence, the GWT shell first loads the HTML markup placed in the public package into the browser and sends an AJAX request to the server with the parameters of the client's locale, OS and browser information. GWT then picks the JS files to deploy to the client and sends them in the response. These JS files are generated based upon the code you place in the onModuleLoad() method.

Let's add the most commonly used component in the GWT-Ext library - the Panel to our application. To do so, the Panel class must first be imported into the HelloWorld class.

import com.gwtext.client.widgets.Panel;

Now, a Panel variable can be declared and instantiated in the onModuleLoad() method:

public void onModuleLoad() {
   Panel mainPanel = new Panel();
}

The Panel component is a SubClass of the Component class which is the fundamental building block of the ExtJS and subsequently the GWT-Ext architecture. In the GWT-Ext world, every component is treated like a bean class with setter and getter methods for the various configuration options available. So, let's go ahead and set the properties for our mainPanel component.

public void onModuleLoad() {
   Panel mainPanel = new Panel();
 
   // Setting the Panel's properties
   mainPanel.setTitle("Hello World!");
   mainPanel.setHeight(300);
   mainPanel.setWidth(500);
}

We first set the title property which specifies the text which will be shown in the header of the panel. This property is optional. Next, the height and width of the panel are specified.

This would create an empty panel with a 2px blue border with an aero-style header with the text "Hello World!" in it.

However, this component isn't added to the markup yet. To do so, we need to retrieve the RootPanel using the get() method. The RootPanel is a GWT Panel to which all components must ultimately be added (except for the Viewport component as this is done automatically by the GWT-Ext library). We use the RootPanel's add(Widget widget) method to add our panel to the HelloWorld page. First import the RootPanel from the GWT library:

import com.google.gwt.user.client.ui.RootPanel;

and then add the mainPanel component to the RootPanel:

public void onModuleLoad() {
  Panel mainPanel = new Panel();
 
  mainPanel.setTitle("Hello World!");
  mainPanel.setHeight(300);
  mainPanel.setWidth(500);
 
  RootPanel.get().add(mainPanel);
}

You are now ready to execute the HelloWorld appliction. Open up a command prompt window pointed to the root folder where your application was stored (C:\Users\Sankar\Documents\GWT-Ext\Hello GWT-Ext in this example). Execute the HelloWorld-shell.cmd file:

HelloWorld-shell

This will launch the GWT Development shell at port 8888 of your machine's localhost. This is a simple implementation of a Tomcat Server which is generated by the applicationCreator.

ExtElement: A powerful Element representation

ExtElement is essentially a GWT-Ext representation over a DOM Element and adds many useful methods over GWT's Element class.

Retrieving specific elements in web pages can be achieved by using the Ext core class's get() methods. The method closely follows the traditional Javascript document.getElementById() model, but instead of returning a handle to the DOM node, it returns an ExtElement object which allows you to access the GWT-Ext methods associated with that type.

As the GWT-Ext ExtElement object is mostly a translation of the ExtJS Element object into the GWT model, the properties of the ExtJS Element apply to it as well. A quick look at the ExtJS tutorial on getting started should help.

You could replace the Java code given above with that below to test the ExtElement methods.

package com.mycompany.mypackage.client;
 
import com.google.gwt.core.client.EntryPoint;
import com.gwtext.client.core.Ext;
 
/**
 * @author Sankar
 * 
 */
public class HelloWorld implements EntryPoint {
 
   public void onModuleLoad() {
      Ext.getBody().insertHtmlBeforeEnd("<div id='mydiv'>A simple div</div>");
      Ext.get("mydiv").setStyle("margin", "10px");
      Ext.get("mydiv").setStyle("border", "1px dotted #F9AA44");
      Ext.get("mydiv").setStyle("width", "300px");
      Ext.get("mydiv").setStyle("padding", "5px");
      Ext.get("mydiv").highlight();
   }
}

As can be seen, the Ext core class's getBody() method is used to add a simple Div element into the page. The Ext.get() method is again used to retrieve the element and apply some style properties to it. These are standard CSS properties and are passed as Strings.

Then, the Element.highlight() method is used to highlight the ExtElement on the page. This method is a part of the Fx interface which provides basic animation and visual effects support.

Extracting the ExtElement into a local variable is also available and is a recommended method of handling Elements or Components.

package com.mycompany.mypackage.client;
 
import com.google.gwt.core.client.EntryPoint;
import com.gwtext.client.core.Ext;
import com.gwtext.client.core.ExtElement;
 
/**
 * @author Sankar
 * 
 */
public class HelloWorld implements EntryPoint {
 
   public void onModuleLoad() {
      Ext.getBody().insertHtmlBeforeEnd("<div id='mydiv'>A simple div</div>");
      final ExtElement myDiv = Ext.get("mydiv");
      myDiv.setStyle("margin", "10px");
      myDiv.setStyle("border", "1px dotted #F9AA44");
      myDiv.setStyle("width", "300px");
      myDiv.setStyle("padding", "5px");
      myDiv.highlight();
   }
}

Components: The GWT-Ext coder's building blocks

The Component class extends the GWT Widget class and is the base-class for all GWT-Ext widgets. Most GWT-Ext applications involve instantiating sub-classes of the Component class and adding them to the GWT RootPanel.

The most common Subclass of Component that you will be using in your applications is the Panel component which, in turn, extends the BoxComponent class. The BoxComponent class is the base class for all visual Components in GWT-Ext.

The Panel Component

Let's add a simple Panel to the application and explore its properties.

public void onModuleLoad() {
	Panel myPanel = new Panel();
	myPanel.setWidth(300);
	myPanel.setHeight(200);
	myPanel.setFrame(false); //Optional
	myPanel.setTitle("Panel Example");
 
	RootPanel.get().add(myPanel);
}

A simple Panel with a title

myPanel.setHeader(false);

The Header is also the container for the top Toolbar Component of the Panel. The Panel also provides a Tool area in the top right corner of the Panel's Header to render simple tools like the collapse tool. To see this, set the Panel to be Collapsible and to keep it amusing, let's set the Animate Collapse option to true.

public void onModuleLoad() {
	Panel myPanel = new Panel();
	myPanel.setWidth(300);
	myPanel.setHeight(200);
	myPanel.setFrame(false); //Optional
	myPanel.setTitle("Panel Example");
	myPanel.setCollapsible(true);
	myPanel.setAnimCollapse(true);
 
	RootPanel.get().add(myPanel);
}

The Panel automatically adds a collapse button to the Tools area.

It is equally simple to add your own set of tools to the Tools area using the addTool() function of the Panel.

public void onModuleLoad() {
	Panel myPanel = new Panel();
	myPanel.setWidth(300);
	myPanel.setHeight(200);
	myPanel.setFrame(false); // Optional
	myPanel.setTitle("Panel Example");
	myPanel.setCollapsible(true);
	myPanel.setAnimCollapse(true);
 
	myPanel.addTool(new Tool(Tool.GEAR, new Function() {
		public void execute() {
			MessageBox.alert("Click!", "You selected the Gear tool");
		}
	}, "Gear"));
 
	RootPanel.get().add(myPanel);
}

Clicking on the Gear tool will pop up an alert window letting you know that the click event of the Tool was triggered.

As you can see, however, the Gear tool was added to the right of the collapse tool. This is because the tools are added after the collapse property of the Panel is set. So, let's add the Gear and Collapse tools ourselves and a Pin tool to demonstrate that the order in which the Tools are added can be changed.

public void onModuleLoad() {
	final Panel myPanel = new Panel();
	myPanel.setWidth(300);
	myPanel.setHeight(200);
	myPanel.setFrame(false); // Optional
	myPanel.setTitle("Panel Example");
	myPanel.addTool(new Tool(Tool.GEAR, new Function() {
		public void execute() {
			MessageBox.alert("Gear Tool", "This Panel is "
					+ (myPanel.isCollapsed() ? "" : "not") + " collapsed");
		}
	}, "Gear"));
	myPanel.addTool(new Tool(Tool.PIN, new Function() {
		public void execute() {
			if (myPanel.isFrame())
				myPanel.setFrame(false);
			else
				myPanel.setFrame(true);
		}
	}, "Pin"));
	myPanel.addTool(new Tool(Tool.TOGGLE, new Function() {
		public void execute() {
			if (myPanel.isCollapsed()) {
				myPanel.expand(true);
			} else {
				myPanel.collapse(true);
			}
		}
	}, "Collapse"));
 
	RootPanel.get().add(myPanel);
}

We first make the myPanel object final so that it can be accessed from within the Tool function handlers. Add the tools in any order.

The Toggle Tool is a convenient tool which automatically toggles the image when clicked. We set the Collapse Tool's function handler to collapse/expand the Panel when clicked.

The Gear tool is now used to show an alert which tells us the collapse status of the Panel.

The Pin tool contains an error which will be thrown at Run-time. This will demonstrate how GWT-Ext handles JavaScript errors that it encounters. Every Component has properties which cannot be modified after it has been rendered. Trying to modify them will cause an exception to be thrown. These exceptions are caught by the GWT-Ext exception handler and an alert is shown with a brief description. Also, if the application is being run in hosted mode, the exception is logged to the GWT console.

The Exception is described in detail in the GWT Development Shell