Chapter 9. Advanced Web Application Topics

9.1. Debug and Production Mode

IT Mill Toolkit applications can be run in two modes: debug mode and production mode. The debug mode, which is on by default, enables a number of built-in debug features for the developers. The features include:

  • Debug Window for accessing debug functionalities
  • Display debug information in the Debug Window and server console.
  • Analyze layouting button that analyzes the layout for possible problems.

Starting from IT Mill Toolkit version 5.3.0, all applications are by default run in the debug mode. The production mode can be enabled (and debug mode thereby disabled) by adding a productionMode=true parameter to the servlet context in the web.xml deployment descriptor:

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

Enabling the production mode disables the debug features, thereby preventing users from easily inspecting the inner workings of the application from the browser.

9.1.1. Debug Mode

Running an application in the debug mode enables the client-side Debug Window in the browser. You can open the Debug Window by adding "?debug" to the application URL, e.g., http://localhost:8080/myapp/?debug. The Debug Window, shown in Figure 9.1, “Debug Window”, consists of buttons controlling the debugging features and a scrollable log of debug messages.

Figure 9.1. Debug Window

Debug Window

Clear console
Clears the log in the Debug Window.
Restart app
Restarts the application.
Force layout
Causes all currently visible layouts to recalculate their appearance. Layout components in IT Mill Toolkit 5.3.0 and later calculate the space required by all child components, so the layout appearance must be recalculated whenever the size of a child component is changed. In normal applications, this is done automatically, but when you do themeing or alter the CSS with Firebug, you may need to force all layouts to recalculate themselves, taking into account the recently made changes.
Analyze layouts
This is described in the following section.

If you use the Firebug plugin in Mozilla Firefox, the log messages will also be printed to the Firebug console. In such a case, you may want to enable client-side debugging without showing the Debug Window with "?debug=quiet" in the URL. In the quiet debug mode, log messages will only be printed to the Firebug console.

9.1.2. Analyzing Layouts

The Analyze layouts button analyzes the currently visible layouts and makes a report of possible layout related problems. All detected layout problems are displayed in the log and also printed to the console.

The most common layout problem is caused by placing a component that has a relative size inside a container (layout) that has undefined size, e.g., adding a 100% wide Panel inside a HorizontalLayout with no width specification. In such a case, the error will look as shown below:

IT Mill Toolkit DEBUG
- Window/1a8bd74 "My window" (width: MAIN WINDOW)
  - HorizontalLayout/1cf243b (width: UNDEFINED)
    - Panel/12e43f1 "My panel" (width: RELATIVE, 100.0 %)
Layout problem detected: Component with relative width inside a HorizontalLayout with no width defined
Relative sizes were replaced by undefined sizes, components may not render as expected.
			

This particular error tells that the Panel "My panel" is 100% wide while the width of the containing HorizontalLayout is undefined. The components will be rendered as if the the width of the contained Panel was undefined, which might not be what the developer wanted. There are two possible fixes for this case: if the Panel should fill the main window horizontally, set a width for the HorizontalLayout (e.g. 100% wide), or set the width of the Panel to "undefined" to render the it as it is currently rendered but avoiding the warning message.

The same error is shown in the Debug Window in a slightly different form and with an additional feature (see Figure 9.2, “Debug Window Showing the Result of Analyze layouts.”). Checking the Emphasize component in UI box will turn the background of the component that caused a warning red, making it easy for the developer to figure out which component each warning relates to. The messages will also be displayed hierarchically, as a warning from a containing component often causes more warnings from its child components. A good rule of thumb is to work on the upper-level problems first and only after that worry about the warnings from the children.

Figure 9.2. Debug Window Showing the Result of Analyze layouts.

Debug Window Showing the Result of Analyze layouts.

9.1.3. Custom Layouts

CustomLayout components can not be analyzed in the same way as other layouts. For custom layouts, the Analyze layouts button analyzes all contained relative-sized components and checks if any relative dimension is calculated to zero so that the component will be invisible. The error log will display a warning for each of these invisible components. It would not be meaningful to emphasize the component itself as it is not visible, so when you select such an error, the parent layout of the component is emphasized if possible.

9.1.4. Debug Functions for Component Developers

You can take advantage of the debug mode when developing client-side components. The static function ApplicationConnection.getConsole() will return a reference to a Console object which contains logging methods such as log(String msg) and error(String msg). These functions will print messages to the Debug Window and Firebug console in the same way as other debugging functionalities of IT Mill Toolkit do. No messages will be printed if the Debug Window is not open or if the application is running in production mode.