public interface DomIntegration
First, a warning: when you use HTML and the DOM directly, all of Smart GWT's guarantees of cross-browser consistent behavior no longer apply. When you use Smart GWT's API, Smart GWT is automatically compensating for many, many browser bugs - not just trivial things like different property names or missing utility methods, but problems where browsers fail to fire certain events, report sizes wrong only in certain modes with certain styling, or bugs that only occur with specific timing.
Before deciding to do direct HTML coding, consider whether you really want to expose yourself to all of these possible issues. If you can achieve the same look and feel and behavior through Smart GWT's APIs, that's usually best.
The DOM structures used by Smart GWT necessarily differ by browser in order to work around each browser's specific bugs. This DOM structure is intentionally undocumented because it is subject to change without notice - in may be necessary to modify the DOM structure to work around the bugs in each new browser release.
  Instead of trying to modify the Smart GWT-generated DOM, you should always add new
  elements.  For a new standalone component that will be based on direct use of HTML, you
 usually do this by subclassing Canvas and overriding Canvas.getInnerHTML() and returning
  an HTML string representing the components you want to create.
  
  You can use a similar approach anywhere HTML is allowed in a widget property: formatting APIs
  for StaticTextItem, DetailViewer, TileGrid, and other DataBoundComponents, as well as places
 such as Tab.title or Button.title.
  
Most third-party JavaScript components have the ability to generate their HTML content into a DOM element specified by ID, or to replace such an element with new HTML. This is true of Google Maps, CKEditor and many other libraries.
 To use this form of integration, implement a Canvas.getInnerHTML() function that returns
  a DOM element with a known ID, then have the third-party library target that DOM element once
  the Canvas is drawn.  For example, CKEDITOR.replace() takes the ID of a <textarea>
  element, and the following code would create a <textarea> and have the CKEditor replace
  it with a CKEditor widget: 
  
  
  
  public class CKEditor extends Canvas {
  
      private static native void replace(String id) /*-{
          $wnd.CKEDITOR.replace(id);
      }-*/;
  
      public CKEditor() {
          setRedrawOnResize(false);
      }
  
      @Override
      public String getInnerHTML() {
          return "<textarea id='" + getID() + "_ckEditor' style='width:100%;height:100%'></textarea>";
      }
  
      @Override
      protected void onDraw() {
          CKEditor.replace(getID() + "_ckEditor");
      }
  }
  
  
  
  This same approach can be used when you want to insert third-party generated HTML into just a
  specific part of a Smart GWT widget.  For example, you might want to insert 
 JQuery
 'sparklines', which are
  essentially miniature charts, into cells of a ListGrid.  You could use
 a cell formatter to
 write out <div> elements with
  known IDs into the cells, then target them with JQuery.
  
  If a third party component is being embedded into a Smart GWT widget, developers should
 consider which overflow setting is most
 appropriate to use. 
  Oftentimes you'll want your embedded component to size to the available space. In this case
  you should use overflow:"hidden". However if the embedded component
  will render at a specific size, and you want to have the component size to fit it, 
  overflow:"visible" may be appropriate.
  
  Developers embedding third party text editing components into Smart GWT widgets
 should typically set Canvas.canSelectText to true on the Smart GWT
  widget. This prevents the Smart GWT event management system potentially interfering with
  selection and copy/paste behavior as the user interacts with the embedded editor (observed
  in some browsers, including some versions of Internet Explorer).
  
  When implementing canvas.getInnerHTML(), your getInnerHTML() function will be
  called every time the component redraw()s, and the new HTML will replace the old.
  
  Also by default, your component will redraw() if it is resized.  In the example above with
 CKEditor, we wouldn't want this because it would wipe out the CKEditor widget every time it was
 resized, so we set Canvas.redrawOnResize to false.  In other circumstances you may want
  to redraw on every resize in order to generate new HTML.
  
  If you do not redraw HTML on resize, you either have to write the HTML in a way that makes it
 flow into available space (width/height 100% may be enough here) or you need to manually
 resize the DOM element when the resized event fires.  
  
  In the latter case, you should adjust the size of the DOM element to match the
  inner width and 
 inner height of the containing
 Canvas.  The "inner" dimensions
  are the dimensions after border and margins have been subtracted, so this will work even if a
 border is added to your Canvas subclass via CSS or Canvas.setBorder().
  
 Once you have set Canvas.redrawOnResize to false you may still see redraws from other
  sources.  Generally this would be from code in your application which calls
 Canvas.redraw() or Canvas.markForRedraw() unnecessarily.  To
 troubleshoot, you
  can enable the "redraws" log category in the Developer Console - this will log the source of
  any redraws in the system.
  
ListGrid.refreshCell(),
  automatic cell refresh due to data changing, cells being shown or hidden due to
 incremental rendering, etc.
 Developers will need to
  consider how best to handle the lifecycle of the DOM elements they create
  Another consideration specific to ListGrids is that fact that in some circumstances the
  HTML returned by a cell formatter may be rendered outside the grid body. An example
 of this is the drag tracker HTML generated when ListGrid.dragTrackerMode is
 set to "record". The inactive cell formatter 
  may be provided to emit alternative HTML for rendering these 'inactive' versions of
  the cell content (allowing developers to, for example, exclude explicit element IDs).
  
  Third-party components that utilize iframes, browser plugins or other special elements will
  "swallow" events such that Smart GWT never receives them.  This is a problem whenever a
  drag interaction goes over the component, including drag resizing of the component itself.
 To avoid this issue, set Canvas.useDragMask for any component that contains an iframe
  or browser plugin, or that appears to be swallowing events during drag.  The telltale sign
  is that when the mouse goes over the plugin, the visual effect of the drag (differs by
 Canvas.dragAppearance) stops
 updating or stutters.
  
 Consider which Canvas.overflow setting
 to use for your custom component:
  
overflow:"hidden" is the most common.  In the context of third-party
  components, it means the component is prepared to render itself at any requested size (above
  a minimum). 
  overflow:"visible" means you want Smart GWT to attempt to automatically
  determine a minimum size based on the HTML content generated by the custom component
  overflow:"auto" is similar to overflow:"hidden", but means
  your custom component needs Smart GWT to create scrollbars whenever its HTML content does
  not fit in the allocated space.
  overflow:"visible" or overflow:"auto", if you make on-the-fly
  modifications to the HTML you returned from getInnerHTML(), there is no
  cross-browser-reliable way for the Canvas to detect this and auto-size again.  Instead, call
 Canvas.adjustForContent() to
 trigger auto-sizing again.
  
zIndex values control what component is rendered "on top" when multiple components appear in the same area of the page.
To work around various browser issues, Smart GWT components use a very high range of zIndex values. If a component creates pop-up widgets such as hovers or floating toolbars via direct HTML/DOM usage, these pop-up widgets will appear behind all Smart GWT components unless they set a very high zIndex.
  For your own custom HTML/DOM components, the simplest strategy is to create pop-up widgets
  based on Smart GWT components, even if they are triggered by interacting with
  hand-created HTML.  For example, even if you've written some kind of advanced SVG-based data
  visualization component, you can still implement pop-up configuration dialogs based on the
 Smart GWT Window class; there's no reason to implement such
 dialogs directly in
  low-level HTML/DOM code.
  
  If a third-party widget is creating pop-ups you don't directly control, you may be able to
  configure the third-party widget to use a certain zIndex range, or you may be able to
  directly reach into the widget's DOM and modify zIndexes that way.  You can use
 Canvas.getZIndex() to discover the zIndex
 of any Smart GWT widget you need to
  appear above, then set a higher value.
  
Finally, as a last resort and completely unsupported approach, you can modify the zIndex range used by Smart GWT by executing the following JavaScript code via JSNI, in your onModuleLoad() function :
       private native void adjustZIndexRange() /*-{
           $wnd.isc.Canvas.addClassProperties({
               // default zIndex for the next item to be drawn
               _nextZIndex:200000,
     
               // zIndex of the next item to be sent to the back
               _SMALL_Z_INDEX:199950,
     
               // zIndex of the next item to be brought to the front
               _BIG_Z_INDEX:800000
           });
       }-*/;
       
       public void onModuleLoad() {
           adjustZIndexRange();
           .......
       }     
  
  
  
There are several other issues, listed below, for which there really is no general strategy for solving the issue, although some general pointers are provided.
Because of problems like these, it's a very very bad idea to freely intermix components from multiple component libraries. While mixing components may appear to be an appealing strategy and you may experience apparent success with early attempts, the issues below will ultimately prevent you from completing an application of sufficient quality for enterprise use.
In the following discussion, "third-party widgets" should be understood to include widgets that you write using direct DOM/HTML techniques.
Accessibility).TabIndexManager class can be used to integrate
 arbitrary HTML elements into
  the page level tab sequence, by both providing a numeric tab-index to assign to the
  element, and allowing the developer to implement programmatic callback to shift focus
  to the element (which will then be called automatically by the framework where appropriate).
 See TabOrderOverview for more on this. In some cases it may
 also be necessary to 
  add manual keyDown or keyPress event handlers to handle focus moving from Smart GWT
  components to third-party widgets and back.EventHandler.targetIsMasked() to
 make third-party widgets respect Smart GWT
 modality, or may require calls to Canvas.showClickMask() to cause Smart GWT
  components to consider themselves inactive when a third-party widget opens a pop-up that is
  intended to be modal.  Multi-layered modality, such as a modal window that in turn pops a
  modal dialog, is yet more complex.
 
  Skinning
 Overview)