This chapter is from the book
This chapter is from the book
This chapter is from the book
Building and Sharing Modules
Each GWT module is not necessarily a full application, but it can be used as a reusable library for other applications instead. The GWT module structure, also used for applications, gives you the tools necessary to package your module and share it with other applications. In fact, GWT itself is divided into several modules, as you've seen with the user interface, XML, JSON, HTTP, and RPC modules, so you've already used the process of importing other libraries.
Using Modules
GWT modules are distributed as jar files that you can include in your application by adding them to your project's classpath and inheriting their project name in your application's module file. This is the same process that you use to include the GWT library classes in your application. In this case GWT automatically adds the module jar file, gwt-user.jar, to your project's classpath when you generate the project using the GWT createProject script. The createApplication script then generates a module XML file for your application and automatically adds the com.google.gwt.user.User module to it. When we generate the module XML file for the Gadget Desktop application in Chapter 6, we get the following XML:
<module> <inherits name='com.google.gwt.user.User'/> <entry-point class='com.gwtapps.desktop.client.Desktop'/> </module>
This module file tells the GWT compiler how to compile the application to JavaScript. The inherits element tells the compiler that we are using classes from the name module, which will also need to be compiled to JavaScript. We can continue to add modules from gwt-user.jar since the file is are already on the classpath. For new modules in other jar files, we first need to add the jar to the classpath. In Eclipse, you can do this by going to the project's Properties dialog and selecting the Libraries tab from Java Build Path, as shown in Figure 4-46.
)
Figure 4-46 Editing the build path in Eclipse
From here you can add and remove jar files. Notice that gwt-user.jar is already in the list. For the Gadget Desktop application we add the gwt-google-apis library to the project to use the Gears module from it. First, we add the gwt-google-apis jar to this list, and then the application's module XML file inherits the Gears module like this:
<module> <inherits name='com.google.gwt.user.User'/> <inherits name='com.google.gwt.json.JSON'/> <inherits name='com.google.gwt.xml.XML'/> <inherits name='com.google.gwt.gears.Gears'/> <entry-point class='com.gwtapps.desktop.client.Desktop'/> </module>
Notice also that this project imports the JSON and XML modules which are already in the gwt-user.jar file. If you miss this step—adding the inherits tag to your application's module file—you will get an error from the GWT compiler that it can't find the module that you're using.
Creating a Reusable Module
If you've built a GWT application, you've already built a reusable module. The only difference is that your application has specified an entry point and can be turned into a GWT application loaded on its own in the GWT hosted mode browser or web browser. You could reference the application's module file from another application to reuse its components.
You create a module the same way you create an application, using GWT's applicationCreator script. You may want to use the ant flag with this script to build an ant file that will automatically package your module in a jar file for distribution.
The module structure of GWT is hierarchical using inheritance. For example, if you write a module that inherits GWT's User module, then any module or application that uses your module also automatically inherits GWT's User module. This is an important feature, since it allows the users of your module to automatically get all the requirements to run. GWT takes this concept further and lets you also inject resources into modules to ensure CSS or other JavaScript libraries are automatically included.
For example, if you were creating a module of widgets that required default CSS to be included, you could reference this in the module XML like this:
<module> <inherits name='com.google.gwt.user.User'/> <stylesheet src="widgets.css"/> </module>
The widgets file would need to be included in your module's public files, and when other modules inherit your module they would automatically get the widgets.css file without directly including it.
You can similarly include JavaScript in your module using the script tag like this:
<module> <inherits name='com.google.gwt.user.User'/> <!-- Include google maps --> <script src="https://maps.google.com/ maps?file=api&v=2&key=ABQIAAAACeDba0As0X6mwbIbUYWv-RTb- vLQlFZmc2N8bgWI8YDPp5FEVBQUnvmfInJbOoyS2v-qkssc36Z5MA"></script> </module>
This tag is similar to the script tag that you would use in your HTML file to include a JavaScript library, except that this file would be automatically included with every module that includes this module.
As of GWT 1.4 you can use image bundles to include resources with your reusable modules. Image bundles allow you to package several images together into a single image for deployment. If you use an image bundle within your module, applications that use your module will automatically generate the single image. In Chapter 6, images bundles are used to build the Gadget toolbar in the Gadget Desktop application.
Sharing a Compiled Application (Mashups)
Sometimes you'd like to share your compiled JavaScript application for use on other web sites. As of GWT 1.4, other web sites can easily load your application using the cross-site version of the generated JavaScript. The cross-site version has –xs appended to the package name for the JavaScript file name, and you can find it in the www directory after compiling an application. For example, to include the Hangman application developed in Chapter 1, you would use the following script tag:
<script language='javascript' src='http://gwtapps.com/hangman/ com.gwtapps.tutorial.Hangman-xs.nocache.js'></script>
Notice that this line differs from the line found in the original host HTML page for the application; it has the addition of –xs in the filename and is loading the script from the gwtapps.com domain.
Each application that you share may have additional requirements for integration on another site. In the Hangman example, the application looks for an HTML element with the ID hangman, so anyone including this on their site would need to also have the following HTML in the location where they'd like the Hangman application to show up:
<div id="hangman"></div>