The Smart GWT FAQ

[Isomorphic]

Basic Resources

• Smart QuickStart Guide (START HERE)
• Smart GWT Showcase (samples)
• Smart GWT Pro/EE Showcase (samples)
• Smart GWT JavaDoc
• Installation instructions
• Conceptual overviews in JavaDoc (Note: read QuickStart first)
• Download SDK

Setup Guides

• Pro/EE: Starter Eclipse project files and other setup instructions included in the
  evaluation package, under the samples/ directory. Download here
• Smart GWT with Maven
• NetBeans with GWT4NB (user contributed)

Tools

• How do I use the Developer Console?
• How do I use the automatic DataSource support for SQL, Hibernate or Java Beans?
• How do I use Google's GWT Designer with Smart GWT?
• How do I launch Visual Builder?
• How do I use screens created in Visual Builder with Smart GWT?

SmartGWT.mobile

• When should I use SmartGWT.mobile vs Smart GWT?
• What's the license for SmartGWT.mobile?
• Why a separate mobile-only framework when Smart GWT already supports mobile?
• Where's the source code for SmartGWT.mobile?
• Will there be a JavaScript version of SmartGWT.mobile?

Troubleshooting / Common Issues

• What's the first thing to do when I run into issues?
• Having an issue in Chrome..
• Strange rendering behavior with browser zoom
• I saved data and my grid/tree/picker didn't update. Why?
• What DOCTYPE should I use?
• I get a JavaScript error in Element.getOffsetLeft()
• I'm seeing visual glitches like unnecessary scrollbars, gaps in headers or misplaced elements.
• I installed a new version but I'm still getting an error that my evaluation is expired
• I installed a new version that is supposed to have a fix or new feature, but it's still not working
• (SGWT Pro or better) I can't load my DataSource, DataSource.get() returns null
• (SGWT Pro or better) I bought a license but I'm getting a warning that my evaluation has expired
• (SGWT Pro or better) I'm getting a warning dialog about not having the SC Server
• (SGWT Pro or better) I seem to have missing resources and/or tools don't work
• (SGWT Pro or better) I have odd errors that seem to imply duplicate .jars or old .jars are around
• Why is my application slow?

Legacy issues

• A String is serialized as though it were an array of letters (GWT pre-2.5)
• Having an issue with GWT 2.3..
• Images aren't loading at all (GWT pre-2.0)
• Internet Explorer 6 has started performing badly and constantly loading resources from the network. What's going on?

Getting Support

• What are my options for support?
• I think I found a bug in Smart GWT. What do I do?
• Should I create issues in the Smart GWT issue tracker on GitHub?
• I'm seeing a JavaScript error. What do I do?
• I need a feature or enhancement added to Smart GWT.

Server Architecture Planning / MVC

• Should I use GWT-RPC?
• I already have some REST services for my Java backend, or I could easily generate some.
  Should I use those for my Smart GWT UI?
• If I'm not using SQL / Hibernate, is there anything in Smart GWT Pro that applies to my
  project?
• What MVC pattern should I use with Smart GWT: Struts, Spring, something else?
• What should I use if I don't have a Java backend?

Client Coding

• Can I mix Smart GWT and GWT widgets?
• How do I make a Smart GWT widget fill a basic HTML container or GWT container?

Tools

• How do I use the Developer console?
  
  In your gwt.xml file, inherit the module com.smartgwt.tools.SmartGwtTools. You can then open the
  Developer Console by creating a bookmark with the URL "javascript:isc.showConsole()" and navigating
  to the bookmark. (NOTE: typing this into the URL bar will also work in most browsers, but not in Firefox 6+).
  
  To make it possible to open the Developer Console by simply pressing Ctrl-D, add the following to
  your EntryPoint class:
  
  

  	if (!GWT.isScript()) {
  	  KeyIdentifier debugKey = new KeyIdentifier();
  	  debugKey.setCtrlKey(true);
  	  debugKey.setKeyName("D");
  	  Page.registerKey(debugKey, new KeyCallback() {
  	      public void execute(String keyName) {
  	          SC.showConsole();
  	      }
  	  });
  	}

  A brief tour of the Developer Console:
  
  1. Results Tab: diagnostic messages output by Smart GWT, including warnings about invalid usage.
  The "Logging Preferences" menu allows you to enable diagnostics on a category-by-category basis
  in order to troubleshoot specific problems (similar to Java's Log4j). If you need to enable a category
  not shown in the list, click "More..", then "Add".
  
  2. Watch Tab: a tree of your application's components and their parent/child hierarchy. Note this
  is a logical tree of components, not a DOM tree. Each element in this tree may represent hundreds
  of DOM elements, and if you check the "undrawn" checkbox, the tree will include components that
  have been created but not yet drawn. Click on any component to find out where it is. If you
  assign global IDs to components via setID(), they will appear with that ID here.
  
  3. RPC Tab: shows data requests issued by Smart GWT components - check Track RPCs to enable.
  For any data-related requests, this tab is far more useful than browser built-ins like Firebug's "Net"
  pane because it shows Smart GWT-specific data like what component issued the request and what
  logical type of request it was (eg a DataSource "update" request), as well as showing you a highly
  readable representation of the request object itself instead of the encoded HTTP request captured
  by Firebug.
  
  4. WSDL Tab: interactive tool for testing WSDL web services.
• How do I use the automatic DataSource support for SQL, Hibernate or Java Beans?
  
  If you are trying to connect to a SQL database and you have no pre-existing, large amount of
  code designed around Hibernate, we recommend the SQLDataSource connector. First install
  the JDBC driver for your target database of choice, then launch the Admin Console to configure
  JDBC settings.
  
  To use the Admin Console, in your gwt.xml file, ensure that you have the same imports required
  for Visual Builder (see previous FAQ), then call SC.openDataSourceConsole().
  
  

  	 IButton adminButton = new IButton("Admin Console");
  	 adminButton.addClickHandler(new ClickHandler() {
  	      public void onClick(ClickEvent event) {
  	          com.smartgwt.client.util.SC.openDataSourceConsole();
  	      }
  	  });
  	 adminButton.draw();

  Having opened the Admin Console, available JNDI connections will be discovered and shown automatically.
  If you aren't using JNDI, use the GUI to enter and test JDBC settings. Both ConnectionManager and
  JDBC DataSource settings are supported. Once you've got a working connection, set it as the default
  connection using the "Set as Default" button.
  
  These will be written to server.properties in your deployment directory - use
  the "Download server.properties" button to download the settings and merge them to the
  server.properties file in your Eclipse (or other IDE) project.
  
  To use Hibernate instead, see this topic, or for JPA, this topic.
  
  To use generic Java Beans, just add the "schemaBean" attribute to your .ds.xml file - see the Server Framework
  chapter of the QuickStart Guide.
  
  If you have a large number of SQL tables, Hibernate, JPA or other Java Beans, we
  recommend the Batch DataSource Generator. The Batch DataSource Generator allows you to enter a list of Java
  classnames or SQL table names and have a DataSource descriptor (.ds.xml file) generated for each one.
  
  The Batch DataSource Generator also allows you to customize the process of DataSource generation in order
  to produce better or more complete DataSource descriptors for your beans, so that you can eliminate hand-editing.
  For example, having created a custom Datasource, you can add simple Java code to the generator to use Java
  annotations, naming conventions or Java type information to produce DataSource descriptors in which contain
  definitions for DataSourceField.primaryKey, DataSourceField.editorType, DataSourceField.validators or other parts
  of the DataSource definition which drive the behavior or visual components. You can even add custom properties
  to the generated DataSource definition that only your custom DataSource understands, or that only your custom
  visual components understand.
  
  This allows you to drive all data-related behavior from your Java bean definitions: basics such as the list of
  fields and types, but also sophisticated behaviors such as conditional validation. All with zero duplication.
  
  Open the Batch DataSource Generator with the same steps as indicated above, except the method call is
  SC.openDataSourceGenerator() (NOTE: Smart GWT Enterprise only)
• How do I use GWT Designer with Smart GWT?
  
  
  
  
  We currently do not recommend that developers use GWT Designer because it encourages manual
  layout and manual data binding of individual controls, whereas SmartGWT handles this
  automatically via the data binding system.
  
  
  
  
  For this reason, despite GWT Designer being a visual tool, it actually takes more effort for a
  developer to build a screen in GWT Designer than to use the data binding approaches built into
  Smart GWT. * Using GWT Designer also produces code that is much much larger and much harder to
  modify than a solution based on data binding.
  
  
  
  
  To understand how to use data binding, see the QuickStart Guide, Data Binding chapter. *Also
  see the Server Framework chapter for how UIs can be automatically generated from server-side
  object definitions such as Java Beans or SQL database tables.
  
  
  
  
  If you are considering GWT Designer for creating mockups or prototypes, we recommend using
  Balsamiq mockups instead. *This tool is much better suited for rapidly & collaboratively
  *creating mockups, and can be used by non-developers since it is not Eclipse-based. *
  We also have support for converting Balsamiq mockups into live Smart GWT code,
  in such a way as to maximally take advantage of data binding.
  
  
  
  
  NOTE: GWT Designer is now open source. *If you wish to enhance GWT Designer to be a more
  effective tool which makes use of Smart GWT data binding, fix bugs in the tool, or add support for more
  recent versions of Smart GWT, Google is soliciting contributions.
• How do I launch Visual Builder?
  
  First, be sure to read the note in the next FAQ on what Visual Builder is for. Visual Builder
  is not an IDE and not the correct starting point for a Java developer - start with the QuickStart Guide instead.
  
  To use Visual Builder, either import one of the sample projects provided in the "samples" directory of your
  Pro / Power / EE package, or, if you have a pre-existing project, use these step-by-step
  instructions to add Smart GWT Pro / Power / EE to your project.
  
  Then, in your gwt.xml file, make sure you have the appropriate imports:
  
  

  	  <inherits name="com.smartgwtee.SmartGwtEE"/>
  	  <inherits name="com.smartgwtee.tools.Tools"/>

  After changing the <inherits>, run a GWT compile and restart your server process if it was running.
  
  Then, if your project host .html file is accessible at the URL /myProject/start.html, then Visual Builder
  should be accessible at /myProject/tools/visualBuilder/index.jsp.
  
  If you are unclear on the correct URL, you can alternatively call SC.openVisualBuilder(). For example,
  to create a button in your application that launches Visual Builder:
  
  

  	   IButton vbButton = new IButton("VisualBuilder");
  	   vbButton.addClickHandler(new ClickHandler() {
  	       public void onClick(ClickEvent event) {
  	           com.smartgwt.client.util.SC.openVisualBuilder();
  	       }
  	   });
  	   vbButton.draw();

  To watch a video introduction to using Visual Builder, click here: http://www.smartclient.com/releases/vb_video.htm.
• How do I use screens created in Visual Builder with Smart GWT?
  
  First, recognize that Visual Builder is not intended as an IDE. It is a screen design and
  databinding tool intended to allow designers, analysts and other non-developers to participate
  in the development process, and modify and extend applications without the need to write code.
  
  It can be useful for Java developers to experiment in Visual Builder to learn the capabilities of
  SmartGWT, however, after this initial learning and experimentation phase, the primary purpose
  of using Visual Builder is to save screen designs in a declarative format that Visual Builder
  can re-load for further visual editing.
  
  Specifically, this allows:
  
  1. central deployment of Visual Builder, to serve as a mockup and design repository
  
  2. including Visual Builder in a deployed application or shipping product, to allow runtime
  modification of selected areas of the application by authorized users, allow incorporating
  new data into existing screens, or even allow creation of new screens.
  
  Because Visual Builder allows very deep customization (customized palettes, custom components,
  custom property sheets, custom databinding wizards, custom skins, custom editors, etc) you can
  turn it into whatever kind of tool you want. For example, you can create a WYSIWYG design tool
  that uses standard corporate look and feel (via skinning), offers standard corporate design
  patterns (via custom components), and understands your enterprise's data sources (via adding
  DataSources or DataSource Wizards).
  
  Given this purpose - storing screens in a declarative format to allow further editing with visual tools -
  what you want to do is load the screen from the XML format that Visual Builder uses, then
  attach behaviors to that screen in Java code. This separates the screen layout from the behavior,
  so users can rearrange and redesign the screen (eg add a grid connected to an RSS feed) without
  affecting behavior and without needing to understand Java code.
  
  To do this, copy the XML code generated by Visual Builder (from the "Cobe" tab) and follow the
  instructions in the Component XML overview for how to load
  your screen and attach event handlers and other logic.

SmartGWT.mobile

• When should I use SmartGWT.mobile vs Smart GWT?
  
  As of the automatic mobile adaptation features included in SmartGWT 5.0 and up, we are now only
  recommending SmartGWT-mobile for applications that exclusively target phones, will never have a desktop
  UI, and place a very high value on first-ever download time while having relatively simple functional
  requirements.
  
  You might also consider SmartGWT-mobile if you have multiple mobile interfaces to build for
  different types of users, and some users should have a very low functionality interface that has virtually
  nothing in common with the desktop & full mobile experience.
• What's the license for SmartGWT.mobile?
  
  The same license as for Smart GWT LGPL - the GNU General Public License, version 3.
  
  However, SmartGWT.mobile supports instant integration with the same commercial server
  technology as SmartGWT (and SmartClient), so you can reuse DataSources and business logic
  across your desktop and mobile interfaces.
  
  To use SmartGWT.mobile this way, purchase a Pro or better license to SmartGWT or SmartClient.
  This also gives you a license to use SmartGWT.mobile under the same commercial terms, so you
  can ship a SmartGWT.mobile interface and it will have any LGPL license restrictions.
  
  For details of how to combine the Smart GWT server and a SmartGWT.mobile interface, download
  the SDK and look at the User Guide (user_guide.txt).
• Why a separate mobile-only framework when Smart GWT already supports mobile?
  
  Some mobile applications place a premium on first-ever download time and have very low functional
  requirements. In this use case, there is no feasible way to modify the full version of Smart GWT
  to enable it to deliver a minimalist runtime; attempting to do so would only increase the size of the
  full version of Smart GWT due to the convoluted code structures required to allow stripping out unused
  code on a feature-by-feature basis.
• Where's the source code for SmartGWT.mobile?
  
  The source for SmartGWT.mobile will be hosted here (on GitHub). It's not there yet
  - it will be uploaded when the beta period ends, or sooner.
• Will there be a JavaScript version of SmartGWT.mobile?
  
  For JavaScript developers, we recommend using SmartClient, which has the same automatic mobile adaptation
  features as SmartGWT.
  
  We do not plan a JavaScript version of SmartGWT.mobile. The purpose of building a mobile-
  specific framework on GWT was to enable automatically trimming off unused framework features.
  If this automatic trimming feature isn't critically important to you, you should be using SmartClient
  instead.

Troubleshooting / Common Issues

• What's the first thing to do when I run into issues?
  
  Open your Developer Console. Smart GWT logs many important warning messages and diagnostics to
  the Developer Console. Always, always, always have the Developer Console open when coding or
  testing.
• Having an issue in Google Chrome..
  
  Do not use GWT Development Mode with Google Chrome, it has serious bugs and is far slower than
  Development Mode in other browsers. For this reason, experienced GWT developers do not use it,
  even when working with just GWT and not SmartGWT.
  
  If you do try out Development Mode in Chrome and encounter an issue that doesn't reproduce in
  other browsers, try running a full compile (in Eclipse, right click on your project, Google -> Compile).
  If the issue goes away in compiled mode, it's due to a Chrome/GWT bug and should be ignored.
  
  For the curious, the underlying problem is that GWT introduces an extra property into all Objects
  ("_gwt_ObjectId"). This extra property is necessary as a workaround for this Chrome bug. The
  presence of this extra property has been hacked around for some, but not all GWT libraries.
  Since performance is still very poor even with a hackaround in place, we have no plans to add
  hacks to SmartGWT and will wait for the underlying Chrome issue to be resolved - star this issue
  if you wish to track progress.

• What DOCTYPE should I use?

Generally, use the HTML5 DOCTYPE:

<!DOCTYPE html>

For IE9 and above, this is required, since Microsoft has crippled IE in any other mode (missing features
and unavoidable memory leaks).

Some corporate intranets force IE to use "Compatibility Mode" for all intranet sites, which overrides the
HTML5 DOCTYPE declaration. You can work around this by using the following <meta> tag to force
standards mode to be used for your application:

<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

Any other use of the <meta> tag is invalid. For example, if you discover a bug that results from using meta tags to
cause IE11 to behave like IE9, this is not a valid bug unless the same behavior also occurs in IE9.

For IE8 and lower, it is recommended that DOCTYPE be omitted entirely. This is because IE8 is noticeably slower
in "standards mode" and barely more standards-complaint than the default "quirks mode" anyway.

Hence, if feasible:

1. omit a DOCTYPE entirely for IE8 and earlier

2. use the HTML5 DOCTYPE for all other browsers

If it is impractical in your deployment or you don't care about small differences in IE8 performance, use the
HTML5 DOCTYPE for all browsers.

• I'm seeing visual glitches like unnecessary scrollbars, gaps in headers or misplaced elements.
  
  The most common reason for visual glitches is external CSS in your project that is styling the basic
  browser elements (e.g. TD, TH, etc) which will interfere with pixel-perfect layout facilities provided by
  Smart GWT (or any similar system).
  
  This often happens because you are inheriting one of the GWT default themes - remove this from
  your GWT module file (.gwt.xml).
  
  Alternatively, if you have switched your Smart GWT theme you may be loading two Smart GWT
  themes at once, because when you inherit the com.smartgwt.SmartGwt module you also inherit the
  Enterprise theme. To fix, inherit the "NoTheme" version of the SmartGWT module instead, for example,
  com.smartgwtee.SmartGwtEENoTheme (or com.smartgwt.SmartGwtNoTheme for LGPL).
  
  Make sure you are using the correct DOCTYPE (see previous FAQ).
  
  Make sure you are not using browser zoom - currently, due to several intractable native browser bugs,
  Smart GWT can not guarantee perfect appearance or behavior when using browser zoom.
  
  If you are still seeing glitches, check with Fiddler or Firebug for HTTP 404 errors
  or similar errors indicating misplaced media or a misconfigured server. For misplaced elements in particular, use
  the Watch tab in the Developer Console to understand where exactly your widgets are, and use Firebug to inspect
  the CSS styling applied to those widgets.
  
  If you are posting about visual glitches, always indicate whether you see them in the online showcase
  or only in your own environment, and remember to include:
  • what skin you are using
  • whether you have customized the skin or loaded any other CSS
  • the exact browser version and operating system
  • the exact SmartGWT version and GWT version
• I saved data and my grid/tree/picker didn't update. Why?
  
  Smart GWT features automatic cache synchronization across all components that use a DataSource,
  that is, any DataSource modification operation that completes successfully (for example, an
  "update" operation) automatically propagates to all other components that use the same
  DataSource. This is discussed in more detail in the ResultSet docs.
  
  If you are not seeing automatic cache sync:
  
  1. verify your DataSource has a primaryKey field declared. This is how the different
  components understand that the record that has been updated is the same as the one they have
  cached.
  
  2. make sure the data you are returning on successful "add" and "update" operations is
  correct. The DSResponse object is expected to contain the data-as-saved. The primary
  key value returned on an update must exactly match the value in the cached record. Note
  that field names are case-sensitive so check for mismatched case between the data
  and DataSourceField.name, such as "parentId" vs "parentID".
  
  3. in the Developer Console, use the Logging Preferences menu to enable diagnostics. Set the
  "ResultSet" (for ListGrids, ComboBoxItem or similar components) or "ResultTree" (for TreeGrids,
  PickTreeItems or similar components) diagnostic categories to Debug level. When the cache
  manager components receive your update/add/remove responses, they will log the data received
  and why it was either applied or ignored. If you do not see any logs about updating caches, this
  indicates the grid in question is not using a ResultSet / ResultTree at all, probably because you
  either did not call fetchData() / filterData(), or because you called setData() with a data model
  such as a RecordList or Tree, both of which are not aware of DataSources and will automatically
  update caches.
  
  DO NOT just call invalidateCache() to fix a cache refresh problem. Calling
  invalidateCache() does not scale well in terms of code complexity when many components are
  using the same DataSource (e.g., a ListGrid, a SelectItem with an optionDataSource, and others),
  causes unnecessary server load, and also creates the possibility of other logic having to run
  asynchronously since fetching a new cache takes a server round-trip.
  
  Instead, make an effort to correct your code so that cache sync is automatic.
  
  Finally, sometimes custom server-side logic will update other Records from other DataSources as
  well. For example, in some applications, removing all members from a team might cause the team
  to be deleted. You might be showing the list of teams in your UI and need to update it. In this
  case you can either:
  
  1. drive the logic from the client
  
  Have client-side logic detect the empty team and remove it via DataSource.removeData(). Then cache
  synchronization will happen automatically
  
  2. use dsResponse.addRelatedUpdate (server-side API) / DataSource.updateCaches() (client-side API)
  
  These APIs allow you to broadcast changes made to any DataSource Record to all components that
  might have caches of such Records. Use addRelatedUpdates() from server-side logic (Pro Edition and
  above) or updateCaches() from client-side logic (any edition).
• I get a JavaScript error in Element.getOffsetLeft()
  
  This is caused by invalid mixing of Smart GWT and GWT widgets, because GWT unexpectedly
  wipes out the DOM generated by Smart GWT widgets. See the FAQ about correct mixing of
  Smart GWT and GWT widgets.
  
  If you think your particular use case cannot be achieved without mixing widgets and so should
  be considered valid, post a minimal, standalone test case demonstrating the usage and the
  error it produces (along with all other details appropriate to a forum post - see FAQs on Support).
• Browser Zoom
  
  At this time we cannot fully support browsers rendering with the zoom level set to something other
  than 100%. We have encountered too many native browser issues to make support for this feature feasible.
  
  The actual behaviors observed at customized zoom level vary by browser and include odd rendering artifacts and
  various sizing and size-reporting issues.
  We will re-evaluate the situation regarding browser zoom periodically, and we will support it when it is feasible to do so.
• (SGWT Pro or better) I can't load my DataSource, DataSource.get() returns null
  
  Go through the following checklist:
  • Make sure the DataSourceLoader servlet is actually present in web.xml, that the required
    "Init" servlet is also present and that the <script src=> tag is pointing at the correct URL
    for the DataSourceLoader servlet. The easiest way to check the latter is to use
    Firebug's NET panel.
  • Make sure the DataSource ID you pass to DataSource.get() matches the file name (should
    be dataSourceId.ds.xml) and matches the ID attribute on the <DataSource> tag
    (note: attribute is "ID" not "id"). DataSource IDs are case sensitive, including the
    file name.
  • Check that your server.properties setting for "project.datasources" matches the directory
    where you have placed your .ds.xml file
  • Check the server-side log for errors such as malformed XML. If you see something about
    missing files, you have the wrong <inherits> tags in your .gwt.xml file - if you are using Pro
    or above, use <inherits name="com.smartgwtee.SmartGwtEE"> and remove any inherit
    of com.smartgwt.SmartGWT, which is the LGPL version.
  • Make sure the <script src=> tag pointing to the DataSourceLoader servlet is placed after
    the <script src=> for your GWT application (*.nocache.js).
  • Make sure you do not have basic errors in your .html such as the <script> tag not being closed,
    <script> tags outside of both <body> and <head>, multiple <body> tags or the like.
  • If you are loading a very large number of DataSources, the URL can be too long and be rejected
    before it even reaches SmartGWT Server code. In this case, split the URL into two <script> tags
• (SGWT Pro or better) I bought a license but I'm getting a warning that my evaluation has expired
• (SGWT Pro or better) I'm getting a warning dialog about not having the SC Server
• (SGWT Pro or better) I seem to have missing resources and/or tools don't work
  
  Make sure your imports are correct. With Pro and above you should not be importing
  the "com.smartgwt.SmartGwt" module, import the following modules instead:
  
  

  	  <inherits name="com.smartgwtee.SmartGwtEE"/>
  	  <inherits name="com.smartgwtee.tools.Tools"/>

  NOTE: you should continue to import com.smartgwt.tools.SmartGwtTools (for the
  Developer Console), however, it must be before the SmartGwtEE imports.
  
  Also make sure you have run a GWT compile (do this any time you change your .gwt.xml file), restarted
  your browser, and cleared your browser's cache before opening or reloading any Smart GWT page.
  
  If you are merging SmartGWT Pro or better into an existing Java project, also make sure you have
  included all required servlets, in particular the Init servlet.
  
  NOTE: in versions prior to 4.0, use these imports for Pro:
  
  

  	  <inherits name="com.smartgwtpro.SmartGwtPro"/>
  	  <inherits name="com.smartgwtpro.tools.Tools"/>

  .. or for Power:
  
  

  	  <inherits name="com.smartgwtpower.SmartGwtPower"/>
  	  <inherits name="com.smartgwtpower.tools.Tools"/>

• (SGWT Pro or better) I have odd errors that seem to imply duplicate .jars or old .jars are around
  
  The WizTools classloader-servlet is very useful for troubleshooting such issues.
  
  To install, download classloader-servlet-1.0-SNAPSHOT.jar to WEB-INF/lib/ and add this to your web.xml:
  
  

  	  <listener>
  	      <listener-class>org.wiztools.classloaderservlet.ClassloaderServletListener</listener-class>
  	  </listener>
  	  <servlet>
  	      <servlet-name>ClasspathListingServlet</servlet-name>
  	      <servlet-class>org.wiztools.classloaderservlet.ClasspathListingServlet</servlet-class>
  	  </servlet>
  	  <servlet>
  	      <servlet-name>DisplayClassSourceServlet</servlet-name>
  	      <servlet-class>org.wiztools.classloaderservlet.DisplayClassSourceServlet</servlet-class>
  	  </servlet>
  	  <servlet-mapping>
  	      <servlet-name>ClasspathListingServlet</servlet-name>
  	      <url-pattern>/ctx/list-classpath</url-pattern>
  	  </servlet-mapping>
  	  <servlet-mapping>
  	      <servlet-name>DisplayClassSourceServlet</servlet-name>
  	      <url-pattern>/ctx/class-source</url-pattern>
  	  </servlet-mapping>

  Then redeploy your app - if your app is deployed at http://localhost:8080, then visit:
  
  http://localhost:8080/ctx/list-classpath
  
  http://localhost:8080/ctx/class-source?class=some.class.with.Issues
  
  This will reveal if the class in question has been loaded from multiple copies of the same .jar, including the exact filesystem path to the JAR containing the class.
• I installed a new version but I'm still getting an error that my evaluation is expired
• I installed a new version that is supposed to have a fix or new feature, but it's still not working
  
  First, make sure you have followed the full install instructions. Do not skip steps, do not assume
  that just copying .jar files around is sufficient.
  
  Then, double check that your <inherits> tags are correct. Note in the installation instructions that if you are upgrading
  from LGPL to Pro or better, you need to remove older imports, and also the order of <inherits> tags is important.
  
  If your imports are correct and you still receive this error, run a GWT compile (in Eclipse, right click on your project,
  pick Google -> Compile), then close all browser tabs/windows that have your application open, clear your browser
  cache, and re-open the application.
  
  If you still get the error, you have stale copies of the SmartClient runtime files (ISC_Core.js et al) somewhere
  in your project, or your IDE has failed to refresh the deployment directory. Use the "Net" panel in Firebug to look at
  the JavaScript files actually being delivered to the browser (ISC_Core.js) et al. At the top of the file, the build date
  is shown. Having confirmed you have stale JavaScript files, use a filesystem search to see where they are coming
  from, and wipe them out.
  
  If you discover that your IDE is mysteriously restoring stale files even after you've corrected everything, restarting the
  IDE may fix the problem. For Eclipse / MyEclipse, certain types of staleness can be fixed by switching to a different
  JDK (in the Eclipse Properties, under Java) and then switching back (yes, really, this works). If all else fails, reinstall
  the IDE and rebuild your project from scratch.
• Why is my application slow?
  
  The most common issues are:
  
  1. Firebug or the IE debugger is enabled, or you are testing performance in GWT "development mode".
  
  These tools will slow all applications that use JavaScript, but have a disproportionately large
  effect on Smart GWT. End users won't have these tools enabled when they visit your
  application or site, so to assess real-world performance, turn these tools off.
  
  2. Browser caching disabled or crippled
  
  Your browser may be set to non-default cache settings, and so is requesting media files
  repeatedly. End users won't have these special settings, so to assess real-world performance,
  revert to browser defaults.
  
  See also the known issue with cacheing in Internet Explorer 6.0.
  
  3. Server not advertising cachability of resources
  
  Your server needs to set HTTP Expires headers to indicate that JavaScript files, images and
  other resources are cachable. Google for good tutorials on this.
  
  Note this is automatic when using Smart GWT Pro or better.
  
  4. Missing / incorrectly deployed images
  
  In some cases the browser will wait for images to load before displaying components. If the
  images are failing to load, this can severely affect performance. Sometimes, images will still
  appear even though a failure to load has actually occurred, because the browser will fall back
  to a cached version after waiting for a failed image load.
  
  Use Fiddler, Firebug or another HTTP traffic monitor to verify that there
  are no failing requests for images (HTTP 404 responses).
  
  5. Not using HTTP compression
  
  For the smallest initial download size, use HTTP compression (Content-Encoding: gzip) to
  deliver the JavaScript files included in Smart GWT.
  
  Note this is automatic when using Smart GWT Pro or better, including some very obscure
  workarounds required for specific combinations of IE, specific Windows versions and related
  installed software.
  
  6. Developer tools were enabled for a long coding session, and now the browser is "tired"
  
  Tools such as Firebug and the IE debugger can leak memory at a horrific rate. If you seem to
  be sensing a cumulative slowdown, kill all instances of your browser and restart.
  
  7. Inadvertently creating many thousands of components or loading many megabytes of data
  
  Most remaining performance problems have to do with accidentally doing something 10,000 times
  when you thought you were only doing it once.
  
  Check basics such as the Canvas count shown in the Developer Console, and make sure the
  component tree shown in the Watch tab contains what you expected.
  
  Use the RPC tab in the Developer Console to ensure that you aren't sending hundreds of
  extra requests inadvertently, or delivering vastly more data to the browser than you intended.

Legacy issues

• A String is serialized as though it were an array of letters (GWT pre-2.5)
  
  This is due to a bug in GWT (not SmartGWT) and is triggered by calling toString() on something
  which is already a String. This is fixed as of GWT 2.5.
  
  If forced to use older versions of GWT, you need to rearrange your code to avoid the call to String.toString().
  
  The official issue report for this is here.
• Having an issue with GWT 2.3..
  
  Users on Smart GWT 2.4 and older should make sure they have the GWT 2.3 jars before the Smart GWT
  jars in their classpath. This is not required for Smart GWT 2.5 and later.
• Images aren't loading at all (GWT pre-2.0)
  
  If you're using GWT 1.6 or earlier, you'll need to add the following in your host .html file:
  

  	<script> var isomorphicDir = "[I]MODULE_NAME[/I]/sc/"; </script>

• Internet Explorer 6.0 Cacheing
  
  If the browser cache is disabled, full, or corrupted, application performance will degrade as the
  client-side SmartClient engine, UI skin elements, and your application resources are repeatedly
  accessed from the server. This problem may be indicated by slow loading of repeated images, e.g.
  the node icons in a TreeGrid component.
  
  
  This problem is most likely to occur in Internet Explorer browsers, due to bugs in the browser's
  cache implementation. If you encounter this problem, please take the following steps:
  1. close all instances of Internet Explorer
  2. open your Internet Options control panel
  3. click the Delete Files... button (under Temporary Internet Files)
  4. when the wait cursor clears (this may take 10 minutes or more on some systems), click the Delete Files... button again
  5. reduce your cache size to 200MB or less to avoid this Internet Explorer bug in the future

Support

• What are my options for support?
  
  Isomorphic offers commercial support, training and consulting services, including complete "turnkey" application
  development.
  
  For professional developers, commercial services from Isomorphic pay for themselves very
  quickly in terms of saved time, especially when you receive key advice that steers you away from
  dead-end approaches or unnecessary effort. Furthermore, if you have a deployed application
  that is important to your organization, it's irresponsible not to have a support agreement in place
  to get expert help in a crisis.
  
  If, for whatever reason, you are forced to rely on community support from fellow Smart GWT users,
  for the best chance of getting help, make it clear you're making an effort:
  • when posting about issues, always post basics such as GWT version, Smart GWT version,
    browser version(s) and operating system version(s).
  • always check your Developer Console for warnings or errors, and if there were none, say so explicitly.
  • for any JavaScript error, always post the stack trace that Smart GWT logs in the Developer
    Console. Switch to compiled mode and get the stack trace from Chrome, IE8 (but not IE9+) or Firefox
  • post your actual code so other users can easily correct it. Do not request that someone else
    prepare a sample just for you
  • if you're asking for general advice, make it clear that you have read the overview documents
    included in Smart GWT, have read the FAQ and tried to search the forums. Make your
    question very specific so that it's clear that it's not a repeat of an already answered question
  • Support is staffed by the engineers that actually develop our products. They support hundreds
    of thousands of users of the free product as best they can, in addition to paying customers.
    Facing a constant onslaught of bugs - many bogus, incomplete or unrelated to our products – they are
    very busy! As such, please follow the forum rules and supply all requested information – even if you feel
    it is unnecessary.
  • Support keep their forum communications short and to-the-point as they want to resolve your – and all the
    other issues – as efficiently as possible. Thanks for your understanding and cooperation.
  
  
  Finally, if you wonder why your highly articulate post is being ignored while other forum
  posters get rapid, comprehensive, accurate responses, realize that those users have commercial
  support - non-confidential issues are handled via the forums so everyone benefits from the
  answers.
• I think I found a bug in Smart GWT. What do I do?
  
  Post information that conclusively proves there is a bug in Smart GWT and not a problem
  with your own code, ideally, a single-file standalone test case that is as simple as possible
  and is ready to run on it's own or can be run by pasting it into one of the Showcase examples.
  
  Always post at least:
  • your GWT version & Smart GWT version
  • whether you were in Super Dev Mode, Classic/Legacy Dev Mode, or compiled mode
  • browser version and operating system
  • what you expected to happen, and, if applicable, the Smart GWT documentation
    that led you to believe your approach would work.
  
  
  There are many bogus bug reports, so if the information you post is ambiguous or incomplete,
  there's a high likelihood of being ignored.
• Should I create issues in the Smart GWT issue tracker on GitHub?
  
  Only if explicitly directed to do so by Isomorphic. Always post any possible issue
  on the forums first in order to get a confirmation that it is actually a Smart GWT bug and isn't
  a duplicate report. At that point you will be asked to create an issue or subscribe to an
  existing issue.
  
  If you do not receive a response, most likely you haven't provided enough information. Do not
  create a tracker issue, instead, revisit your post and see what you might have omitted.
• I'm seeing a JavaScript error, what do I do?
  
  You should see a stack trace logged for the error either in your IDE's main error Console, or if not, then
  in the Developer Console.
  
  This may make it obvious what the problem is (look for obviously bad parameters being passed into methods).
  
  The best quality stack traces are available in compiled mode from Chrome, IE8 (but not IE9+) or Firefox.
  
  If it's not self-evident what's causing the error, post the complete stack trace along with all other required
  information.
• I need a feature or enhancement added to Smart GWT.
  
  If you are a professional developer, consider Isomorphic's Feature Sponsorship program,
  which allows you to fund at-cost development of the features you need. For any general-purpose
  functionality you would otherwise build and maintain yourself, feature sponsorship is the
  quickest and least expensive option.
  
  If you have no such resources, consider implementing it yourself. Smart GWT is open source in
  order to facilitate this. Create a clear, clean well-tested implementation and post it
  publicly for the best chance of having it included in future versions of Smart GWT so you don't
  have to maintain it.
  
  Finally, you can post to the Wishlist forum. For the best chance of influencing the product
  roadmap, make a clear and compelling case for the feature - what great interfaces it would
  enable and why there is no viable alternative approach.

Server Architecture Planning / MVC

• Should I use GWT-RPC?
  
  Isomorphic strongly recommends against using GWT-RPC, instead we recommend using SmartGWT Pro
  or above as a first choice, or if required to use SmartGWT LGPL, using RestDataSource.
  
  To understand the benefits of SmartGWT Pro and above, please read the QuickStart Guide,
  Server Framework chapter.
  
  Even if you are not using SmartGWT Pro or above, there are extremely strong reasons to use
  RestDataSource rather than using GWT-RPC, as follows:
  • GWT-RPC services are not re-usable: when you implement a server-side REST API you are implementing
    a reusable web service that any other UI technology or automated process can potentially use as well.
    GWT-RPC is limited to a GWT client only
  • Disables automatic transaction support: the SmartGWT RestDataSource supports "queuing" multiple
    DataSource operations so that they can be submitted as a single HTTP request and therefore handled
    as a transaction. This cannot be done with existing GWT-RPC services at all, and if implementing
    GWT-RPC with no existing services, takes a great deal of extra effort relative to using RestDataSource.
  • Disables SmartGWT Tools: the RPC tab in the SmartGWT Developer Console gives you a clear picture
    of exactly what requests and responses your application is sending, as well as which components sent them.
    These tools don't work with GWT-RPC, because it necessarily takes over the network layer
  • Extra Effort: creating multiple RestDataSources takes no more client-side code than just defining the
    fields of each DataSource. Each GWT-RPC-based DataSource requires hand-written Java code to copy data
    from your DTOs into SmartGWT Records, while RestDataSource creates Records from REST responses
    automatically.
  • Devalues external tools: development tools such as Firebug or Fiddler provide much more useful
    information if the data being sent to the server is human-readable. Testing and performance analysis tools
    such as JMeter are likewise more effective with a human-readable network format.
  • Disables network management tools: REST-based protocols can be analyzed by network monitoring
    tools and used in load balancing by layer 4 switches; GWT-RPC requests are opaque and not compatible with
    such management approaches.
  
  
  If you have a large set of existing GWT-RPC services, this community-created GwtRpcDataSource class
  may serve as a stop-gap solution for temporarily integrating legacy services. But again, for all the
  reasons listed above, we recommend moving away from GWT-RPC as soon as possible.
  
  If you move from GWT-RPC to SmartGWT Pro or above, you will typically also be able to eliminate a great
  deal of boilerplate code, since SmartGWT Pro eliminates the need for "Data Transfer Objects" (DTOs) and
  other scaffolding required by GWT-RPC. For further information on SmartGWT Pro, read the QuickStart
  Guide, Server Framework chapter.
• I already have some REST services for my Java backend, or I could easily generate some.
  Should I use them for my Smart GWT UI?
  
  Probably not, for two main reasons:
  
  1. Most existing REST interfaces and generated REST interfaces are not UI-ready
  
  Consider the requirements on a REST interface to be used by a user interface, and the solution
  represented by Smart GWT's RestDataSource class, which specifies an XML or JSON
  REST protocol to use for server integration:
  • user-ready error messages: when an attempted save is invalid, most existing or
    generated REST interfaces will either directly show the exception text or provide a technical
    description of the error which would be unsuitable for an end user. These error messages are
    also typically not locale-sensitive.
  • complex criteria, sort, paging: existing REST interfaces typically take only simple
    parameters, and tools for generating REST interfaces typically just provide support for
    generating interfaces from a Java method that takes certain simple types. However, UIs such as
    the SmartGWT ListGrid allow a user to define criteria on any field as well as sort by any field or
    multiple fields, and provides the same user interface for any type of record that the user
    interacts with, all of which is highly desirable for end users. RestDataSource provides a
    ready-to-use format supporting all of these options.
  • transactions / batch requests: user interfaces frequently need to perform save
    operations affecting multiple records at once, for example, saving multi-row
    edits in a grid. Existing or generated REST interfaces typically do not handle this
    requirement and would require a separate REST interface to be generated for a multi-record
    transactional save, and custom UI code and server code to be written to handle this case.
    However, RestDataSource provides a protocol that allows multiple logical DataSource operations
    to be combined into one HttpRequest, and Smart GWT's UI components automatically use this
    protocol when acting on multiple records.
  
  
  All these reasons taken together almost always mean that it is better to start from
  RestDataSource and implement server support for that protocol rather than try to use an
  existing REST interface or generate a REST interface that could support equivalent features.
  
  2. If you are considering Pro+, making your own custom REST implementation drops a huge range
  of useful features
  
  Now that you understand that you will need to implement the RestDataSource protocol or
  something of similar complexity, consider that the Pro product provides a robust, highly
  optimized implementation of all of the parsing and serialization required for such a protocol,
  and gives you a clean Java API as a starting point.
  
  Further, Pro+ provides a huge list of features on top of this, all of which are useful even
  if you're already implemented persistence logic - see next question.
• If I'm not using SQL / Hibernate, is there anything in Smart GWT Pro that applies to my
  project?
  
  Yes, the charting module is a major client-side feature that only comes with Pro.
  
  In addition, the vast majority of the server-side features of the Pro product apply regardless
  of whether you're using SQL or Hibernate. See this overview of Pro features that apply with
  custom persistence logic and this overview of the best pattern for plugging other persistence
  frameworks into Smart GWT.
  
  To understand these features in more depth, read the QuickStart Guide, Server Framework
  chapter.
• What server-side MVC pattern should I use with Smart GWT: Struts, Spring, something else?
  
  None of these. Realize that Struts and Spring MVC are server-side MVC patterns that assume the
  server will be generating HTML. Smart GWT and GWT in general use a client-MVC architecture,
  also known as the RIA / SOA architecture, in which all aspects of presentation are controlled
  client-side and the server consists of a set of secure, reusable data services.
  
  Note that with Spring in particular there are many different aspects of Spring and some
  do apply with Smart GWT. For example, it makes sense in some circumstances to use
  "dependency injection" features from Spring and in some server APIs of Smart GWT Pro you will
  see features that allow you to use Spring-based Java bean lookup and creation. It's just the MVC
  aspect of Spring which is inappropriate in a RIA.
  
  To plan your application, carefully study the provided samples and documentation, particularly
  those in the Pro/EE Showcase, to fully understand all of the aspects of MVC that are already
  built into Smart GWT itself. Once you've mastered the architecture, return to Spring/Struts and you will
  see that there's a very limited role for these technologies to play, and often no reason to use them at all.
• What should I use if I don't have a Java back end?
  
  Generally use the RestDataSource, or integrate with WSDL web services. See the deeper discussion here.

Client Coding

• Can I mix Smart GWT and GWT widgets?
  
  Yes, with caveats.
  
  Smart GWT has interoperability support that allows a Smart GWT widget to be added to a GWT
  container and allows a GWT widget to be added to a Smart GWT container, and it's appropriate to
  use this for:
  • incremental migration to Smart GWT, such as introducing singular, sophisticated Smart GWT
    components like the Calendar or CubeGrid to an existing GWT application
  • using sophisticated third-party GWT widgets within Smart GWT, where Smart GWT doesn't have
    corresponding built-in functionality
  
  
  However it does not make sense to freely intermix Smart GWT and GWT (or other)
  components, that is, for example, you should not place GWT widgets within a Smart GWT container
  that is in turn within a GWT container. In general, don't intermix widgets unless the need for
  a feature forces you to.
  
  The reason for this is that there are limits to the maximum degree that two Ajax widget kits
  (including GWT) can interoperate - there are no standards that allow interoperability in the
  areas of management of tab order, zIndex management, pixel-perfect layout, section 508
  accessibility and multi-level modality.
  
  Note that "bugs" reported when intermixing GWT and Smart GWT inappropriately (that is, in
  contradiction to these guidelines) are generally going to be marked WONTFIX, although we will
  revisit this in the future if core GWT begins to support APIs that would allow better
  interoperability.
• How do I make a Smart GWT widget fill a basic HTML container or GWT container?
  
  Because Smart GWT's pixel-perfect layout and auto-sizing support goes beyond the capabilities of
  simple CSS layout, components need to know the actual pixel width they have been allocated by
  their parent element; they cannot "flow into" an HTML element of unspecified size.
  
  The issue here is that GWT's containers do not provide an API similar to Smart GWT's
  Canvas.getInnerWidth(), which in Smart GWT can be used by child components to find out
  the available space to draw themselves in, and hence recursively lay out out their own
  children. Nor do GWT containers fire events when they are resized, or when the available
  width changes for various reasons (e.g. scrollbar(s) introduced, or CSS style changes add
  borders and hence reduce space).
  
  A lot of parent<->child coordination and signaling is required to really create an extensible
  pixel-perfect layout system. Smart GWT/SmartClient has implemented all the necessary hooks to
  allow a third-party widget to be embedded inside a Canvas and participate in a precise layout,
  but GWT is not there yet.
  
  If you absolutely must place a Smart GWT interface inside a GWT container and you want it to
  fill the container, the best approach is to listen for a window-level resize event and run
  your own layout calculations that ultimately call resizeTo() on your topmost Smart GWT
  widget. All Smart GWT widgets nested under that topmost widget will then handle layout normally.
  
  NOTE: Don't waste your time trying to find a way to insert width:100% into Smart GWT's rendered HTML,
  this won't work.