Chapter 2. Getting Started with IT Mill Toolkit
Table of Contents
This chapter gives practical instructions for installing IT Mill Toolkit and the reference toolchain, importing the QuickStart project in Eclipse, and running and debugging the demo applications.
This section gives an overview of the IT Mill Toolkit package and its installation.
Installing IT Mill Toolkit is done in a few simple steps:
-
Download the newest IT Mill Toolkit from the download page at http://www.itmill.com/downloads/. Select the proper download package for your operating system: Windows, Linux, or Mac OS X.
-
Unpack the installation package to a directory using an decompression program appropriate for the package type (see below) and your operating system.
-
In Windows, use the default ZIP decompression program to unpack the package into your chosen directory e.g.
C:\dev.Warning
At least the Windows XP default decompression program and some versions of WinRAR cannot unpack the installation package properly in certain cases. Decompression can result in an error such as "The system cannot find the file specified." This is because the decompression program is unable to handle long file paths where the total length exceeds 256 characters. This occurs, for example, if you try to unpack the package under Desktop. You should unpack the package directly intoC:\devor some other short path or use another decompression program. -
In Linux, use GNU
tarand BZIP2 decompression with tar jxf itmill-toolkit-linux-5.x.x.tar.bz2 command. -
In Mac OS X, use
tarand Gzip decompression with tar zxf itmill-toolkit-mac-5.x.x.tar.gz command.
The files will be, by default, decompressed into a directory with the name
itmill-toolkit-<operatingsystem>-5.x.x. -
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 applications at the IT Mill website also: http://toolkit.itmill.com/demo/.
To start the Content Browser, run the start script in the IT Mill Toolkit installation directory as instructed below. The start script 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. If your default browser is not compatible with IT Mill Toolkit the demo applications may not work properly. In that case launch a supported browser manually and navigate to http://localhost:8888/.
If the Content Browser fails to start, make sure that no other service is using port 8888.
JRE must be installed
You must have Java Runtime Environment (JRE) installed or the batch file will fail and close immediately. A JRE can be downloaded from http://java.sun.com/javase/downloads/index.jsp.Firewall software
Executing the Content Browser locally may cause a security warning from your firewall software because of the started web server. You need to allow connections to port 8888 for the Content Browser to work.
Run the start.bat batch file by double-clicking
on the icon. Wait until the web server and web browser has started, it can take a while.
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:8888Wait until the web server and web browser has started, it can take a while.
Browser support
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 another compatible browser.Double-click on the icon. Wait until the web server and web browser has started, it 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.
In the root installation directory is the
start.bat (Windows) or start.sh
(Linux and Mac) script which launches the IT Mill Toolkit Content Browser
(described in Section 2.1.4, “Content Browser Examples”).
The WebContent directory contains all files related
to IT Mill Toolkit and the Content Browser. If you do not
wish to or can not run the Content Browser, you can open
index.html in a web browser to view the
installation package contents and documentation. The demos will
not be usable though. The release-notes.html file contains
information about changes in the latest release and the release
history. The license subdirectory contains licensing guidelines
(licensing-guidelines.html) for IT Mill Toolkit and licenses
for other libraries included in the installation package. The COPYING
file in the installation root also contains license information.
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, the full source code of the
library.
The WebContent/doc directory contains full
documentation for IT Mill Toolkit, including JavaDoc API Reference
Documentation (api subdirectory) 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
the 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, full documentation, and examples. You will need
GWT if you intend to compile custom client-side widgets for IT Mill
Toolkit (described in Chapter 9, Developing Custom Components).
In addition, the installation directory contains project files to allow importing the installation package as a project into the Eclipse IDE. See Section 2.3, “QuickStart with Eclipse” for details on how to do this.
The Content Browser contains demo applications which demonstrate how to use toolkit for different tasks. Below is a selection of demos included in the Content Browser. The sources for all demos are also available.
- Sampler
- Sampler demonstrates the standard components available in IT Mill Toolkit. Clicking on one of the available sample icons will take you to the sample page where you can see a live version of the sample and also the source code used to produce that sample. There is additionally a description for the sample and relevant links to both API documentation and to related samples. Sampler is the best place to get an overview of what is included in IT Mill Toolkit.
- Address Book tutorial
- A step-by-step tutorial which covers everything needed to build an IT Mill Toolkit application. This tutorial demonstrates how to create layouts/views, implement navigation between views, bind components to a data source, use notifications and much more. It even includes a small part on how to create a custom theme for your application.
- Reservation Application
- The Reservation Application demonstrates use of various components in a semi-real application connected to a local database. It also shows how to use a Google Maps view inside an application. Note: starting the demo can take several seconds.
- Coverflow
- A simple example on how you can integrate IT Mill Toolkit with Flex.
- ToolkitTunes
- A non-functional application which demonstrates how complex layouts can be done using IT Mill Toolkit.