1.3. What's Inside the IT Mill Toolkit Package?

This section gives an overview of the IT Mill Toolkit package and its installation.

1.3.1. Installing

Installing IT Mill Toolkit is very straight-forward:

  1. Download the newest IT Mill Toolkit from the download page at http://www.itmill.com/itmill_toolkit_download.htm. Select the proper download package for your operating system: Windows, Linux, or Mac OS X.

  2. Uncompress the installation package to a directory using an uncompressor program appropriate for the package type (see below) and your operating system.

    • In Windows, use ZIP uncompressor to install the package to your chosen directory.

      Warning

      At least with Windows XP default unzipper or when using WinRAR to uncompress the installation package, uncompression can result in an error such as "The system cannot find the file specified." This is because the uncompressor is unable to handle long file paths where the total length exceeds 256 characters. This occurs, for example, if you try to uncompress the package under Desktop. You should uncompress the package directly under C:\ or some other short path.
    • In Linux, use GNU tar and BZIP2 uncompression with tar jxf itmill-toolkit-linux-5.x.x.tar.bz2 command.

    • In Mac OS X, use tar and Gzip uncompression with tar zxf itmill-toolkit-mac-5.x.x.tar.gz command.

    The files will be, by default, uncompressed under a directory with the name itmill-toolkit-<operatingsystem>-5.x.x.

You can rename the installation directory as you wish, especially if you wish to use the installation as a skeleton for your own project, as described in Section 1.5.4, “Using QuickStart as a Project Skeleton” below.

When using IT Mill Toolkit in a project, you will need to copy or import the JAR packages of the library to the web application, and possibly also to your project directory during development, depending on your development environment. This is the case at least with Eclipse. See Section 1.4, “Getting the Development Environment Up and Running” below for details.

1.3.2. Package Contents

At the top level of the installation directory, you can find the start.bat (Windows) or start.sh (Linux and Mac) script. Execute it from a file manager or command prompt, as instructed in Section 1.3.4, “Running the Demo Applications”. The script launches the IT Mill Toolkit Content Browser web application and a web browser to view its start page.

Figure 1.2. IT Mill Toolkit Package Contents

IT Mill Toolkit Package Contents

The WebContent is a web application directory that contains the material available from the Content Browser. If you do not wish to or can not run the Content Browser, you can open the index.html with a web browser to view the installation package contents and documentation, although the demos will not be usable. The release-notes.html contains information about changes in the latest release and the release history. The license subdirectory contains copying information (COPYING) and licensing guidelines (licensing-guidelines.html).

The IT Mill Toolkit Library itself is located at WebContent/itmill-toolkit-5.x.x.jar. The JAR package contains, in addition to the compiled files, full source code of the libraries.

The WebContent/doc directory contains full documentation for IT Mill Toolkit, including JavaDoc API Reference Documentation and this manual in both HTML and printable PDF format.

The WebContent/WEB-INF directory contains source code for the demo applications in the src subdirectory and required libraries in the lib subdirectory.

The gwt folder contains the full Google Web Toolkit installation package, including runtime libraries for the selected operating system platform, full documentation, and examples. You will need GWT if you intend to compile custom client-side widgets for IT Mill Toolkit. The root directory contains also build-widgetsets.xml, which is an Ant file for compiling GWT widget sets as described in Section 8.7.4, “Compiling GWT Widget Sets”.

In addition, the installation directory contains project files to allow importing the directory as a project in the Eclipse IDE. See Section 1.5, “QuickStart with Eclipse” for details on how to import the installation directory as a QuickStart project in Eclipse.

1.3.3. Starting the Content Browser

The Content Browser is your best friend when using IT Mill Toolkit. It allows you to browse documentation and example source code and run the demo applications. The demo applications demonstrate most of the core features of IT Mill Toolkit. You can find the demo application also from the IT Mill website, at http://toolkit.itmill.com/demo/.

To start the Content Browser, run the start script in IT Mill Toolkit installation directory as instructed below for your specific platform. It launches a stand-alone web server running on the local host at port 8888, and a web browser at address http://localhost:8888/.

The Content Browser will open the default web browser configured in your system. Please make sure that the browser is compatible with IT Mill Toolkit or otherwise the demo applications may not work properly.

If the Content Browser fails to start, make sure that no other service is using port 8888.

Windows

Run the start.bat batch file by double-clicking on the icon.

JRE must be installed

You must have Java Runtime Environment (JRE) installed or the batch file will fail and close immediately.

Starting the web server and the web browser can take a while.

Notice that executing the Content Browser locally may cause a security warning from your firewall software. This is due to the started web service. You have to ignore warnings or temporarily accept connections to port 8888 on your firewall software.

Linux / UNIX

Open a shell window, change to the IT Mill Toolkit installation directory, and run the start.sh shell script. You have to run it with the following command:

$ sh start.sh
-------------------------------------------------
Starting IT Mill Toolkit in Desktop Mode.
Running in http://localhost:8888
-------------------------------------------------

2007-12-04 12:44:55.657::INFO:  Logging to STDERR via org.mortbay.log.StdErrLog
2007-12-04 12:44:55.745::INFO:  jetty-6.1.5
2007-12-04 12:45:03.642::INFO:  NO JSP Support for , did not find org.apache.jasper.servlet.JspServlet
2007-12-04 12:45:03.821::INFO:  Started SelectChannelConnector@0.0.0.0:8888

Starting the web server and the web browser can take a while.

Some web browsers for Linux, such as Konqueror, are not well supported, so you may have problems in running the demo applications. Please use Mozilla Firefox or some other compatible browser.

Mac OS X

Double-click on the Start IT Mill Toolkit icon.

Starting the web server and the web browser can take a while.

If the start icon fails in your environment for some reason, you can start the Content Browser by following the instructions for Linux/UNIX above: open a shell window, change to the installation directory, and execute sh start.sh.

1.3.4. Running the Demo Applications

The Content Browser allows you to run demo applications. The start page features four demos:

Feature Browser
The Feature Browser allows you to view a demonstration of the standard components available in IT Mill Toolkit. Select the example from the tree on the left. The top-right panel will display a list of the examples in the category and shows which examples you have already viewed. The bottom-right panel will display the selected example. You can click on the Open in sub-window or Open in native window to open the example in a child window or native window, respectively.
Notification
The Notification demo demonstrates the four types of notification boxes: humanized, warning, error, and tray notifications. Select the notification type, enter the caption and message in the text fields, and click Show notification.
Reservation Application
The Reservation Application demonstrates use of various components in a semi-real application connected to a local database. Most importantly, it shows how to use a Google Maps view inside an application. Notice: starting the demo can take several seconds.
Windowed Demos
Windowed Demos are small examples that run inside child windows, which you can open from the list on left.

Clicking on the Additional demos opens a list of other small examples, which you can view. You can click on the sources to view the source code of each demo application.