Basic Resources
Setup Guides
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:

    Code:
    	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().

    Code:
    	 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:

    Code:
    	  <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:

    Code:
    	   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.
Generally, use the HTML5 DOCTYPE:

Code:
<!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:

Code:
<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:

    Code:
    	  <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:

    Code:
    	  <inherits name="com.smartgwtpro.SmartGwtPro"/>
	  <inherits name="com.smartgwtpro.tools.Tools"/>
    .. or for Power:

    Code:
    	  <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:

    Code:
    	  <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:
    Code:
    	<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.