The Vaadin Wiki is temporarily in read only mode due to large recent spam attacks.

Outdated content

Vaadin TouchKit - Create iPhone applications using Vaadin

WARNING: This wiki page was last edited over a year ago and might be outdated.

Note: This article discusses older versions of the Vaadin TouchKit. Please follow the documentation links on the Directory page of Vaadin TouchKit for more up-to-date information.

What is TouchKit? #

TouchKit is a tool kit that lets you develop applications that look and feel like native iPhone applications using only Vaadin. Let's get started with a short video so you get an idea of what TouchKit can do. Click the image below to view the video (opens in this window).

You can browse the actual demo here

Should I use TouchKit? #

TouchKit has been developed with two main usages in mind. The first usage is, following Vaadin philosophy, to allowing Java developers to create iPhone web applications without having to worry about the underlying HTML and CSS.

The other purpose is to give current Vaadin users a possibility to create mobile versions of their existing Vaadin applications. This way, they can use the same server-side code and work with familiar components and tools.

TouchKit is still under development, so I don't recommend it yet for production environments. It should, however, be stable enough and have enough features for building simple web apps and getting you started with mobile Vaadin development.

Advantages #

TouchKit is a purely Java based way of creating web applications that look and feel much like native iPhone applications. TouchKit also supports Gecko based browsers, allowing you to serve a big portion of your mobile users with a single solution.

TouchKit applications can be added to the iPhone home screen with a custom icon and splash screen to give a native application feel to them.

Disadvantages #

As TouchKit applications are web based, there will always be a need for applications to be able to connect to the internet to work. TouchKit is fairly JavaScript heavy, so it may feel slow on older devices.

Requirements #

TouchKit requires Vaadin 6.3 or above.

What does TouchKit contain? #

Classes #


is the main component when working with TouchKit. This is the container that takes care of navigation and layout on the client side. You use it by giving it a
to navigate to. The
remembers previous layouts, so it can navigate back. It handles the back button for the layout internally. This is also the component that handles animations on supported browsers.


is a layout for the page content. It can contain any other Vaadin components and layouts.


is the iPhone style menu used by TouchKit. It is built and used similar to the Vaadin MenuBar component. A
is built by adding
to it. Each
has a command that is run when the item is tapped by a user.


extends the default Vaadin
to add a few meta-tags into the generated HTML page header. These meta tags disable resizing of the page and define the location of both application icon and splash screen.

These classes also have a client side GWT counterpart, as shown in the class diagram. As a user, you do not have to work with these. You can simply use the server side components and let Vaadin take care of the rest.

CSS Theme #

TouchKit comes with a theme that minimally overrides the Reindeer theme. It allows the Vaadin content wrapper to expand, as it would otherwise cut of content that is outside the initially visible area. It also hides the default spinner used by Vaadin, as it does not look right in an iPhone application.

Images #

There are two images in the "touch" theme,

. These are used as the application icon and startup screen, respectively.

How do I use TouchKit? #

If you skipped the longer description above to just get to programming, here are the main things you need to know.

TouchKit is consists of three main parts:

  1. A modified ApplicationServlet that modifies the HTML header with custom tags
  2. A theme that overrides some of the default Vaadin functionality to suit mobile applications
  3. A custom set of Vaadin components for building iPhone-like interfaces

Install #

Download the latest version of TouchKit from the Vaadin Directory. I will assume here that you are using the Eclipse with the Vaadin Eclipse plugin installed.

Start off by adding the downloaded TouchKit JAR to your project lib folder (

). You can just drag and drop the jar from your file system.

The Vaadin Eclipse plugin should now ask you to rebuild your Widgetset, do so. If not, press the build Widgetset icon in the tool bar. Compiling the widgetset will take a few minutes even on a fast machine, so wait patiently. You'll only have to do this once.

After that, you need to override the default Vaadin

. Open the file
(switch to source view to see XML). Change

<servlet-class> com.vaadin.terminal.gwt.server.ApplicationServlet </servlet-class> }}}


<servlet-class> com.vaadin.touchkit.mobileapplication.MobileApplicationServlet </servlet-class> }}}

You are now ready to start using TouchKit. The following section will take you through a sample program to get you started.

Sample program #

To get you started with TouchKit, let's start off with a small sample program. I assume that you have used Vaadin before, so I'll skip the Vaadin related details here. The Book of Vaadin and the Wiki article on starting Vaadin development are worth reading if you are new to Vaadin.

The main application will look like this:

public class TouchKitApplication extends Application {

private static final long serialVersionUID = 5474522369804563317L;

@Override public void init() { final Window mainWindow = new Window("Sampler"); final TouchPanel panel = new TouchPanel();

panel.navigateTo(new SamplerHome()); mainWindow.setContent(panel);

setMainWindow(mainWindow); setTheme("touch"); } } }}}

There are three main things that you should note here. First, unlike you would probably do in a normal Vaadin application, you will call

instead of
. This is because adding a component will add some margins around our component which we want to avoid. Second, the
is given an initial
to display. Finally, the main theme of the application is set to "touch".

Ready to move on? Good.

Now let's take a look at that

we passed to our
. This is the page we want to create:

The source of the completed page looks like this:

public class SamplerHome extends TouchLayout {

public SamplerHome() {

setCaption("Vaadin Sampler");

addComponent(new Label("<p>This is the mobile version of the Vaadin " + "sampler. It showcases some of the Vaadin components " + "that are suited for use in mobile applications. </p>" + "<p>You can add the application to you home screen to make " + "the application feel more native. </p>", Label.CONTENT_XHTML));

TouchMenu menu = new TouchMenu("Samples");

menu.addItem("UI Basics", new TouchCommand() {

@Override public void itemTouched(TouchMenuItem selectedItem) { getParent().navigateTo(new UiBasics()); } });

menu.addItem("Value Input Components", new TouchCommand() {

@Override public void itemTouched(TouchMenuItem selectedItem) { getParent().navigateTo(new ValueInputComponents()); } });

menu.addItem("Forms and Data Model", new TouchCommand() {

@Override public void itemTouched(TouchMenuItem selectedItem) { getParent().navigateTo(new Forms()); } });

menu.addItem("Grids and Trees", new TouchCommand() {

@Override public void itemTouched(TouchMenuItem selectedItem) { getParent().navigateTo(new GridsAndTrees()); } });

menu.addItem("Layouts and Component Containers", new TouchCommand() {

@Override public void itemTouched(TouchMenuItem selectedItem) { getParent().navigateTo(new LayoutsAndContainers()); } });

addComponent(menu); } } }}}

That's probably a bit to take in at once, so let's take a look at it in smaller pieces.

I started off by creating a standard Vaadin

for the introduction text. I used
for the label as I wanted to add several paragraphs to the same label. I then added the component to the layout with

The second part of the page is the menu. To create a TouchKit menu, you simply make a new

. Here, I also added a caption that is shown above the menu.

TouchMenu menu = new TouchMenu("Samples"); }}}

Then, you can add as many menu items to this menu like this:

menu.addItem("UI Basics", new TouchCommand() {

@Override public void itemTouched(TouchMenuItem selectedItem) { getParent().navigateTo(new UiBasics()); } }); }}}

You simply tell the menu to add an item with a given text and a

that will run when a user touches the menu item. TouchMenuItems can optionally also have a description and an icon. When the
is triggered, it will get the parent
and tell it to navigate to a new
that is constructed in a similar manner as this one. To make the user interface feel more responsive, TouchKit uses the text of the TouchMenuItem as the caption of the next page and animates it in while waiting for content from the server.

To finish the page, add the menu to the layout:

addComponent(menu); }}}

This is just a small sampler application to show off some of the functionality in TouchKit and Vaadin components. You can see the rest of the source code for creating the Vaadin Mobile Sampler at the TouchKit SVN.

The finished application, also shown in the above video can be browsed here.

Things to consider #

When working with TouchKit, it is essential to remember that you are working with an user interface that is meant to be used with a finger as the input device. This means that you should be sure to make your components large enough to hit with a finger. It also limits the use of functionality that is dependent on a mouse, like mouse over effects.

Components that are dependent on scrolling will also be cumbersome to use because scrolling is handled by moving around the view with a finger. Just try out the Grid example in the sampler to see what I mean.

As a final tip, try to keep the amount of elements on your page to a bare minimum as processing power and memory is limited on mobile devices. Take a look at the Optimizing Sluggish UI article for some tips on keeping your app lightweight and fast.

License #

TouchKit is licensed under the AGPL 3.0 license.

I've found a bug/I want a new feature! Where can I report it? #

Great! I'm more than happy for your help in testing TouchKit. You can report bugs and check up on my progress at the TouchKit issue tracker.

4 Attachments
Average (4 Votes)
Vaadin Touchkit offers very good user experience and provides wide range of UI components to apps for building mobile web applications.

But this will not run as smooth as platform specific mobile apps. as ultimately it will not completely leverage the real power of mobile platform features as finally it is going to run in a mobile web browser. as compared to native mobile apps.

but with Vaadin touchkit, you can not use any mobile platform specific features like notification, alarm services, account services etc.

Find more detail on vaadin touchkit and comparison with similar technogies like ZK Mobile and native platform specific apps. :
Posted on 12/14/12 3:40 PM.