Файл: book-of-vaadin.pdf

Mobile Applications with TouchKit

higher during hiccups.You may need to limit the use of the immediate mode, text change events, and polling.

22.2.3. Mobile Features

Phones and tablets have many integrated features that are often available in the browser interface as well. Location-awareness is one of the most recent features. And of course, you can also make phone calls.

22.2.4. Compatibility

The mobile browsing field is currently evolving at fast pace and the special conventions that are introduced by leading manufacturers may, in the next few years, stabilize as new web standards. The browser support in TouchKit concentrates on WebKit, which appears to be emerging as the leading mobile browser core. In addition to Apple's products, also the default browser in Android uses WebKit as the layout engine.Yet they have differences, as the Android's JavaScript engine, which is highly relevant for Vaadin, is the Google Chrome's V8 engine.

Vaadin TouchKit aims to follow the quickly evolving APIs of these major platforms, with the assumption that other browsers will follow their lead in standardization. Other platforms will be supported if they rise in popularity.

Back Button

Some mobile devices, especially Android devices, have a dedicated back button, while iOS devices in particular do not. TouchKit does not provide any particular support for the button, but as it is a regular browser back button, you can handle it with URI fragments, as described in Section 11.10, “URI Fragment and History Management with UriFragmentUtility”. For iOS, the browser back button is hidden if the user adds the application to the home screen, in which case you need to implement application-specific logic for the back-navigation.

22.3. Installing Vaadin TouchKit

You can download and install TouchKit from the Vaadin Directory at https://vaadin.com/addon/vaad- in-touchkit as an installation package or get it with Maven. If your project requires the use of the CVAL license, they can be purchased from the Directory.

See Chapter 17, Using Vaadin Add-ons for details regarding add-on installation. The add-on includes a widget set, so you need to compile the widget set for your project.

22.3.1. Installing the Zip Package

Vaadin TouchKit is distributed as a Zip package that contains the TouchKit JAR, a JavaDoc JAR, license texts, and other documentation. You can download the Zip package from the Vaadin Directory. A different package is provided for the two licenses, and the Directory asks for your choice.

The JAR should be put in the WEB-INF/lib folder of the web application.

Please see the README.html for more information about the package contents.

Mobile Applications with TouchKit

Library Dependencies

TouchKit requires the Reflections library for compiling the widget set. You can get the JAR from http://code.google.com/p/reflections/.

If you use the Vaadin Plugin for Eclipse and manage the Vaadin library dependencies with Ivy, you can get the Reflections library by adding the following dependency:

<dependency org="org.reflections" name="reflections" rev="0.9.8" />

22.3.2. Installing in Maven

You can install Vaadin TouchKit in a Maven project by adding it a dependency, as described first below. If you are creating a new project, you can use the TouchKit Maven archetype to create a project skeleton.

Defining as a Dependency

To use TouchKit in a Vaadin project, you need to include the following dependency in the POM. The artifactId should be vaadin-touchkit-agpl or vaadin-touchkit-cval, depending on your choise for the license.

<dependency>

<groupId>com.vaadin.addon</groupId> <artifactId>vaadin-touchkit-agpl</artifactId> <version>LATEST</version>

</dependency>

You can use the LATEST version as shown above or a specific version by its version number.

You also need to define the repository for the Vaadin add-ons under the <repositories> element:

<repository> <id>vaadin-addons</id>

<url>http://maven.vaadin.com/vaadin-addons</url> </repository>

You also need to enable the widget set compilation in the POM, as described in Section 17.4.3, “Enabling Widget Set Compilation”, and compile it.

Using the Archetype

You can create a new TouchKit application project using the Maven vaadin-archetype-touchkit archetype, as described in Section 2.6, “Using Vaadin with Maven”.

For example, from command-line, you could do:

$ mvn archetype:generate \ -DarchetypeGroupId=com.vaadin \ -DarchetypeArtifactId=vaadin-archetype-touchkit \ -DgroupId=example.com -DartifactId=myproject \ -Dversion=0.1.0 -Dpackaging=war

Mobile Applications with TouchKit

22.3.3. Importing the Vornitologist Demo

The Vornitologist demo, illustrated in Figure 22.1, “The Vornitologist Demo for Vaadin TouchKit” in the overview, showcases most of the functionality in Vaadin TouchKit. You can try the demo on-line with a TouchKit-compatible browser at http://demo.vaadin.com/vornitologist/.

You can browse the sources on-line or, more conveniently, import the project in Eclipse (or other IDE). As the project is Maven-based, eclipse users need to install the m2e (or m2eclipse for older versions) plugin to be able to import Maven projects, as well as Subclipse for making SVN access easier. Once they are installed, you should be able to import Vornitologist as follows.

1. Select File Import

2. Select Maven Check out Maven Project from SCM, and click Next.

3.In SCM URL, select svn and enter URL for the repository. You can find the current repository URL from the TouchKit add-on page at http://vaadin.com/addon/vaadin-touchkit.

4.Click Finish.

Instead of using Subclipse, you can check out the project with another Subversion tool and then import it in Eclipse as a Maven project.

22.4. Elements of a TouchKit Application

At minimum, a TouchKit application requires a UI class, which is defined in a deployment descriptor, as usual for Vaadin applications. You usually also need to have a custom theme. To enable various other features, you may need to provide a custom servlet. These and other tasks are described in the following subsections.

22.4.1. Deployment Descriptor

The deployment descriptor of a TouchKit application is much like for any Vaadin application. However, you need to use the special TouchKitServlet class instead of the regular VaadinServlet in the web.xml deployment descriptor. Often you need to make some configuration or add special logic in a custom servlet, as described in the next section, in which case you need to define your servlet in the deployment descriptor.

As TouchKit comes with a custom widget set, you need to use a combining widget set for your project. The combining widget set descriptor is automatically generated by the Vaadin Plugin for Eclipse and in Maven when you install or define the TouchKit add-on.

<servlet>

<servlet-name>Vaadin UI Servlet</servlet-name> <servlet-class>

com.vaadin.addon.touchkit.server.TouchKitServlet

</servlet-class> <init-param>

<description>Vaadin UI class to start</description> <param-name>ui</param-name> <param-value>com.example.myapp.MyMobileUI</param-value>

</init-param> <init-param>

<param-name>widgetset</param-name> <param-value>com.example.myapp.MyAppWidgetSet</param-value>

</init-param> </servlet>

Mobile Applications with TouchKit

22.4.2. Creating a Custom Servlet

Some tasks can only be done in the initial request to the server, before the UI is created. You need to make a custom servlet class if you want to use the following TouchKit features:

•Customize bookmark or home screen icon

•Customize splash screen image

•Customize status bar in iOS

•Use special web app mode in iOS

•Provide a fallback UI (Section 22.6.1, “Providing a Fallback UI”)

•Enable offline mode

A custom servlet should normally extend the TouchKitServlet. You should place your code in servletInitialized() and call the super method in the beginning.

public class MyServlet extends TouchKitServlet { @Override

protected void servletInitialized() throws ServletException { super.servletInitialized();

... customization ...

}

}

If you need to rather extend some other servlet, possibly in another add-on, it should be trivial to reimplement the functionality of TouchKitServlet, which is just to manage the TouchKit settings object.

22.4.3. TouchKit Settings

TouchKit has a number of settings that you can customize for your needs.The TouchKitSettings configuration object is managed by TouchKitServlet, so if you make any modifications to it, you need to implement a custom servlet, as described earlier.

public class MyServlet extends TouchKitServlet { @Override

protected void servletInitialized() throws ServletException { super.servletInitialized();

TouchKitSettings s = getTouchKitSettings();

...

}

}

The settings include special settings for iOS devices, which are contained in a separate IosWebAppSettings object, available from the TouchKit settings with getIosWebAppSettings().

Application Icons

The location bar, bookmarks, and other places can display an icon for the web application. You can set the icon, or more exactly icons, in an ApplicationIcons object, which manages icons for different resolutions. The most properly sized icon for the context is used. iOS devices prefer

Mobile Applications with TouchKit

icons with 57×57, 72×72, and 144×144 pixels, and Android devices 36×36, 48×48, 72×72, and 96×96 pixels.

You can add an icon to the application icons collection with addApplicationIcon().You can acquire the base URL for your application from the servlet context, as shown in the following example.

TouchKitSettings s = getTouchKitSettings(); String contextPath = getServletConfig()

.getServletContext().getContextPath(); s.getApplicationIcons().addApplicationIcon(

contextPath + "VAADIN/themes/mytheme/icon.png");

The basic method just takes the icon name, while the other one lets you define its size. It also has a preComposed parameter, which when true, instructs Safari from adding effects to the icon in iOS.

Viewport Settings

The ViewPortSettings object, which you can get from the TouchKit settings with getViewPortSettings(), manages settings related to the display, most importantly the scaling limitations.

TouchKitSettings s = getTouchKitSettings(); ViewPortSettings vp = s.getViewPortSettings(); vp.setViewPortUserScalable(true);

...

See the Safari Development Library [http://developer.apple.com/library/safari/] at the Apple developer's site for more details regarding the functionality in the iOS browser.

Startup Image for iOS

iOS browser supports a startup (splash) image that is shown while the application is loading.You can set it in the IosWebAppSettings object with setStartupImage(). You can acquire the base URL for your application from the servlet context, as shown in the following example.

TouchKitSettings s = getTouchKitSettings();

String contextPath = getServletConfig().getServletContext()

.getContextPath(); s.getIosWebAppSettings().setStartupImage(

contextPath + "VAADIN/themes/mytheme/startup.png");

Web App Capability for iOS

iOS supports a special web app mode for bookmarks added and started from the home screen. With the mode enabled, the client may, among other things, hide the browser's own UI to give more space for the web application. The mode is enabled by a header that tells the browser whether the application is designed to be used as a web application rather than a web page.

TouchKitSettings s = getTouchKitSettings(); s.getIosWebAppSettings().setWebAppCapable(true);

See the Safari Development Library [http://developer.apple.com/library/safari/] at the Apple developer's site for more details regarding the functionality in the iOS browser.