Creating a Widget with Google Web Toolkit and opentaps

This tutorial shows you how to create a widget with the Google Web Toolkit (GWT) for opentaps. In opentaps, we have already implemented common user interface components, such as screenlets, form fields, auto completion, and lists, based on GWT Ext, which is an open source library that extends the standard GWT. This tutorial will show you how to build a widget using these opentaps GWT components and wire them to the user-facing forms and back end business logic.

Our Example

For this tutorial, we will be replacing an existing "screenlet" with a GWT widget. The screenlet we will be replacing is "New Case" under the CRMSFA > Cases tab:

Currently, this screen lead is a small HTML form which posts to the server to create a case in the CRM system. We will be replacing it with a GWT widget so that our user can create new cases without each time waiting for the server to refresh the entire screen.

Setting up the Files

The first step is to set up your files. In opentaps, the commonly used GWT base classes, components, and widgets are located in hot-deploy/opentaps-common/src/common/org/opentaps/gwt Each application then has its own GWT widgets, located in directories such as hot-deploy/crmsfa/src/org/opentaps/gwt/crmsfa, and these widgets are built when that application is built. Inside of this directory, you will find subdirectories for the accounts, contacts, leads, orders, and partners widgets.

Because there are currently no cases widgets, the first thing we would need to create is the subdirectory for cases: a new hot-deploy/crmsfa/src/org/opentaps/gwt/crmsfa/cases. Here, we put the cases.gwt.xml file, which is a configuration file for GWT:

<module>
  <source path="client"/>
  <inherits name='org.opentaps.gwt.common.common'/>
  <entry-point class='org.opentaps.gwt.crmsfa.cases.client.Entry'/>
</module>

This file tells GWT that we will be inheriting from org.opentaps.gwt.common.common, and it identifies the Java class which is the entry point for the widgets related to cases. Happily, this is the only XML configuration file we would need for our GWT widget. The rest of the widget is written in Java.

The next thing is you need to add the cases widget to the build path for your application. You can do this by editing hot-deploy/crmsfa/build.xml and adding cases to the list of gwt modules:

 <property name="gwt.module.list" value="contacts,accounts,leads,partners,orders,cases"/>

Now we are ready to get started with our widget.

Creating the Widget

The first step is to create the entry point for all the cases widgets, by creating a file called hot-deploy/crmsfa/src/org/opentaps/gwt/crmsfa/cases/client/Entry.java. This file is used to load up GWT:

import org.opentaps.gwt.common.client.BaseEntry;

public class Entry extends BaseEntry {

    private static final String QUICK_CREATE_CASE_ID = "quickNewCase";
    private QuickNewCaseForm quickNewCaseForm = null;

    public void onModuleLoad() {
        if (RootPanel.get(QUICK_CREATE_CASE_ID) != null) {
                loadQuickNewCase();
        }
    }

    private void loadQuickNewCase() {
        quickNewCaseForm = new QuickNewCaseForm();
        RootPanel.get(QUICK_CREATE_CASE_ID).add(quickNewCaseForm);
    }
}

What this class does is define a div id of quickNewCase:

private static final String QUICK_CREATE_CASE_ID = "quickNewCase";

Then, the onModuleLoad, which is run every time this widget is activated, will check if the RootPanel, or the web page, has this tag:

public void onModuleLoad() {
   	if (RootPanel.get(QUICK_CREATE_CASE_ID) != null) {

If it does, then it will call loadQuickNewCase, which instantiates and loads the quick new case form on to the RootPanel, or web page:

  quickNewCaseForm = new QuickNewCaseForm();
  RootPanel.get(QUICK_CREATE_CASE_ID).add(quickNewCaseForm);
   

Now create QuickNewCaseForm and QuickNewCaseConfiguration. QuickNewCaseForm extends ScreenletFormPanel and is the form. For example, it has a TextField for subjectInput and so forth. QuickNewCaseConfiguration is used to hold the literal values on the QuickNewCaseForm, such as the names of the fields. They could be strings in QuickNewCaseForm as well. UI labels are available through UtilUi.MSG: for example, UtilUi.MSG.crmCreateCase() is CrmCreateCase

Putting it on the Screen

Finally, load the GWT widget on the opentaps screen by adding it to the list of GWT scripts for your screen. This is done by modifying the screens XML definition in hot-deploy/crmsfa/widget/crmsfa/screens/cases/CasesScreens.xml and adding our GWT widget to the main decorator, which causes it to show up for all the case screens:

   <screen name="main-section-decorator">
       <section>
           <actions>
               <set field="gwtScripts[]" value="crmsfagwt/org.opentaps.gwt.crmsfa.cases.cases" global="true"/>
               <set field="sectionName" value="cases" global="true"/>

Link Entry.java to opentaps page by modifying hot-deploy/crmsfa/webapp/crmsfa/cases/screenlets/quickCreateCase.ftl and adding:

<@gwtWidget id="quickNewCase"/>

Linking it to the Services

To hook it up to the back end, use the gwt service event handler in the controller, like this:

     <request-map uri="gwtQuickNewCase">
       <security https="true" auth="true"/>
       <event type="gwtservice" invoke="crmsfa.createCase"/>
       <response name="success" type="none"/>
       <response name="error" type="none"/>
   </request-map>