Introducing IT Mill Toolkit 5

Effortless web application development for Java-programmers.

Release Notes for IT Mill Toolkit Version

Version 5.3.0 is the first stable release of IT Mill Toolkit 5, meaning that there are no known major problems and the API will be kept backward compatible.

Google Web Toolkit Upgraded to Version 1.5

The GWT used in IT Mill Toolkit is upgraded to version 1.5. If you have made your own client side components, you will need to upgrade your GWT library. Many things have changed in GWT 1.5, but upgrading is rather straightforward and, as a bonus, you will get the nice features from Java 1.5. For more details on GWT 1.5, see the GWT web site.

Java 5 Now Required

As GWT now requires Java 5, support for Java 1.4 is discontinued also in IT Mill Toolkit.

IT Mill Toolkit supports the Sun Microsystems JDK and JRE, though others should work as well. When running the demo application, the Jetty web server may produce errors in the console if using certain other Java implementations, especially the GNU JRE.

Debug Mode Enabled by Default

The debug mode is now enabled by default, to allow debugging layout and other problems more easily. The debug mode:

  • Displays debug data to the server console/log.
  • Allows showing the client-side logging window, which you can enable by adding the request parameter "?debug=true" to the application URI.
  • "Analyze layouts" -button in the debug window runs basic checks on usage of relative units. Potentially problematic layouts will be shown in the debug window and in System.out.

You should disable the debug mode when releasing your application for production use. You can do this by including the following setting in your web.xml.

  <context-param>
  	<param-name>productionMode</param-name>
  	<param-value>true</param-value>
  	<description>IT Mill Toolkit production mode</description>
  </context-param>

Layout Changes

The stable IT Mill Toolkit version 5.3 introduces a major rework of layout components since the beta versions 5.2.x and before.

Major changes include:

  • Layouts are stricter than before - usage of debug mode during development is recommended. Use "Analyze layouts" in client side debug window if you encounter problems with relative size.
  • VerticalLayout and HorizontalLayout obsolete OrderedLayout
  • Layout cell alignment has changed
  • ExpandLayout deprecated
  • Default sizes have changed

OrderedLayout deprecated

VerticalLayout and HorizontalLayout replace the old OrderedLayout, which is now deprecated.

Essentially, this makes the creation of these basic layouts a bit tidier as you don't have to give the orientation as an ugly parameter to the constructor. You won't be able to change the orientation with setOrientation() any longer, though such need is rare anyhow.

Layout Cell Alignment Changed

Previously, the alignment of components within layout cells was set with setComponentAlignment() with constants for OrderedLayout (now VerticalLayout and HorizontalLayout) and GridLayout separately, such as OrderedLayout.ALIGNMENT_TOP_LEFT. Now the method takes constants defined in Alignment.

For example, aligning a component "top left" is now:

mylayout.setComponentAlignment(mycomponent, Alignment.TOP_LEFT);

You can also give an Alignment object as a parameter and give horizontal and vertical alignment separately with bitmask parameters.

Handling of relative sizes has changed, ExpandLayout deprecated

ExpandLayout is deprecated. You can now define the relative sizes of components more flexibly with setExpandRatio() method available in VerticalLayout or HorizontalLayout.

See the article on Relative sizes in IT Mill Toolkit for details.

Some components now have default sizes

Previously, almost all components had undefined size by default. Now some containers have 100% width by default. These components are:

  • VerticalLayout
  • Window
  • Panel
  • TabSheet
  • SplitPanel (note that SplitPanel also has 100% height by default)
  • Form
  • FormLayout
  • Label

If the width of a Label is set defined, as is now the default, the label text will wrap appropriately, but if it is set as undefined, the text will never wrap.

Miscellaneous Layout Changes

  • You can now give component alignments inside layouts easily with setComponentAlignment() as a string, such as "top left" or "m,c" (for middle-center). See #2279.
  • Form no longer copies all components from the old layout to the new one when doing setLayout(), instead only fields belonging to the Form are copied.

Custom Tailored Client-Side Components

Due to the layout changes, all child component size changes (outside the updateFromUIDL() function) must be announced. Most commonly, this kind of change occurs when an image gets loaded inside a component. There is a helper method componentSizeUpdated() in the Util class for making the announcement:

            Set<Widget> w = new HashSet<Widget>();
            w.add(this);
            Util.componentSizeUpdated(w);

Themes

Many components have changed significantly due to layout refactoring. Especially the DOM structures of the components have changed, which may break old themes.

Building themes for Toolkit is not the most straightforward process as there is quite a lot of JavaScript magic done while rendering the components, e.g., dimension measuring, etc. If you use unsupported CSS, a component may be rendered in an unexpected way in a browser. A "Theme builder's Handbook" is at the top of our TODO list. In the mean time, it is often safest to override the values defined in the default theme.

Especially, if you encounter problems with margins or spacings, check the manual. Some CSS class names and conventions have changed as well. (Many of the changes are not yet included in the manual.)

If you have or get "broken" component on your screen, the first thing to do is to comment out all your custom theme. If it works, you may have the rework your CSS for that particular component. Below are a few things to check:

  • Do not use custom margins outside a component. In IT Mill Toolkit, no component should have a margin defined. Settings width/height on the server-side would mean offset width/height on client-side, so using custom margins for components using CSS may break some features in the layouts.
  • The same goes for borders and paddings for the main element unless they are used for the main element in the default theme. It is often safer to use borders in the same elements that have borders in the default theme or in inner elements.

The easiest and safest way to build a custom theme is, often, to override the values from the default theme.

Browser support changes since 5.2.x

Safari 2, Firefox 1.5, and versions of Opera prior to version 9.6 are no longer supported. Users of these browsers are strongly encouraged to upgrade to a newer version.

Google Chrome is not yet supported, but it is known to work rather well as it is a close relative to Safari.

The GWT Hosted Mode Browser on Linux uses same Gecko version as FF 1.5 and is currently partially broken. Some layouts do not render properly. We hope to resolve these issues soon with next generation Hosted Mode Browser aka OOPHM or with minor hacks to the client side code.

Miscellaneous Changes and Enhancements

Version 5.3 also contains a large number (more than 200) of small changes, which might not be worth mentioning in the release notes, but below are some of them.

  • A new sub-window theme
  • The HTML structure of TabSheet has changed
  • Better shadow support for overlay elements
  • Row and column icons for Table
  • New component: PopupPanel/PopupView
  • Theme changing on-the-fly
  • Table cellstyle and rowstyle generators
  • New component: MenuBar
  • Security: double-cookie submission pattern
  • Low-level support for bookmarking and history
  • Sub-windows can be centered on screen. Modal windows are centered automatically
  • The Link component now behaves like a normal "weblink"

The release of IT Mill Toolkit includes new features and a large number of fixes to problems compared to the older 5.2.x version. Major enhancements and dozens of bug fixes have been implemented. Only the most significant issues are mentioned here.

For up-to-date status of known problems, see the developer website dev.itmill.com.

Package for the experimental GWT Out-of-Process Hosted Mode

We provide a separate (platform independent) installation package (itmill-toolkit-oophm-.tar.gz) for the experimental Out of Process Hosted Mode (OOPHM) of GWT, which allows debugging client-side code in GWT Hosted Mode with a regular web browser. Using the OOPHM requires installing a browser plugin (available for Mozilla Firefox, IE, and WebKit). See the manual section on OOPHM for more details.

The Linux version of GWT Hosted Mode Browser is no longer compatible with IT Mill Toolkit 5.3.0 (#2299), so the OOPHM is the only option for debugging in hosted mode in Linux.

The compilation of OOPHM widget sets uses a large amount of stack memory, so if the JVM default is too small, you should set it explicitly in compile-widgetset.xml with the following parameter for the Java process (currently included in the example build script): <jvmarg value="-Xss1024k"/>.

As the OOPHM package is experimental, you should use it only for debugging purposes during development. For production use, you should compile your custom widget sets with the regular IT Mill Toolkit package for your platform.

Important known problems in

  • #1155 Uncompressing the installation package fails in Windows if using the default Zip uncompression. Uncompression gives (in Windows Vista) an error message about too long filenames, and a more obscure message in other versions of Windows. Workaround: use 7-Zip or some other good unzip program for Windows.
  • #2299 The Hosted Mode Browser does not work in Linux for debugging client-side GWT code. You need to install the experimental OOPHM package instead (see above) for development. For production, you should use the regular package for Linux.

For other known problems, see open tickets at developer site dev.itmill.com.

Requirements

IT Mill Toolkit is available for the following operating systems:

  • Windows (see the Zip installation notice above)
  • Linux
  • Mac OS X Tiger (mac) or Leopard (leopard)
  • Other UNIX operating systems, such as Sun Solaris, using the installation package for Linux.

IT Mill Toolkit supports Java Servlet API 2.3 and later versions and should work with any Java application servers that conform to the standard. It supports the following application servers:

  • Apache Tomcat, version 4.1 or later
  • BEA WebLogic® Server, version 9.2 or later
  • IBM WebSphere® Application Server, version 6.1 or later
  • JBoss Application Server, version 3.2.8 or later
  • Jetty, version 5 or later
  • Glassfish, version 2 or later

IT Mill Toolkit supports the following browsers for using the applications made with it:

  • Mozilla Firefox releases 2, and 3 (see notice above about Gecco 1.7).
  • Internet Explorer releases 6, 7, and 8.
  • Safari 3
  • Opera 9.6

There may be differences between the exact versions of the supported browsers that may cause incompatibility with applications made with IT Mill Toolkit. Support for Opera has currently some limitations, such as the front page of the Sampler demo.

The following browsers are not supported but have been found to work to a large degree:

  • Safari 2
  • Firefox 1.5
  • iPhone
  • Epiphany, Galeon, and other Gecco-based browsers (see notice about Gecco 1.7 above).
  • Nokia Internet Tablet N800 and N810 (ITOS 2008, Opera-based browser).

Nokia E-series phones with at least 128MB of memory have been known to work with older versions, but not with IT Mill Toolkit 5.2 and later. Konqueror, the default browser in many Linux distributions, is known to not work.

IT Mill Ltd. Interfacing IT