Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Creating a New TouchKit Project

The easiest ways to create a new TouchKit application project are to either use the Maven archetype or create the project as a regular Vaadin project with the Vaadin Plugin for Eclipse and then modify it for TouchKit.

Using the Maven Archetype

You can create a new TouchKit application project using the Maven vaadin-archetype-touchkit archetype. Creating Vaadin projects with Maven is described in more detail in "Using Vaadin with Maven".

For example, to create a project from the command-line, you could do:

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

The ApplicationName parameter for the archetype is used as a prefix for the various stub class names. For example, the above "My" name results in classes such as MyTouchKitUI.

The generated project has the following source files:

MyTouchKitUI.java

The mobile UI for the TouchKit application. See "The UI" for the basics of a TouchKit UI. The example UI uses TabBarView as the content. The first tab features a MenuView (see below), a navigation view stub defined in the project.

MyFallbackUI.java

A fallback UI for browsers unsupported by TouchKit, such as regular desktop browsers. See "Providing a Fallback UI" for more information about fallback UIs.

MyServlet.java

The servlet class for the UI, defined using the @WebServlet annotation in Servlet API 3.0. The generated servlet customizes TouchKit to define the MyUIProvider, which sets the fallback UI. See "The Servlet Class" for more details about defining a custom servlet to customize TouchKit.

MyUIProvider.java

Creates either the MyTouchKitUI for supported mobile browsers or MyFallBackUI for unsupported browsers. See "Providing a Fallback UI" for more information about fallback UIs.

MenuView.java

Presents a stub for a menu view. The menu is made of NavigationButtons laid out in a VerticalComponentGroup. Clicking a button navigates to another view; in the stub to a FormView (see below).

FormView.java

Presents a stub for a data input form.

gwt/AppWidgetSet.gwt.xml

Widget set descriptor for the project. When compiled, it is automatically updated to include possible other add-on widget sets in the project.

gwt/client/MyOfflineDataService.java

A data service stub for storing data in the offline mode. See "Offline Mode".

gwt/client/MyPersistToServerRpc.java

Client-to-Server RPC stub to persist offline data to the server-side.

If you import the project to Eclipse or other IDE, you at least need to compile the widget set to be able to deploy the project. You can to do that with Maven integration in the IDE, or from command-line with:

$ mvn vaadin:compile

See "Using Vaadin with Maven". At least in Eclipse, you should now be able to import and deploy the project to a development server. You can also compile the project and launch it in a Jetty web server (port 8080) from command-line as follows:

$ mvn package
$ mvn jetty:run

Note that a project generated by the archetype defines the servlet with the @WebServlet annotation defined in Servlet API 3.0. The application server must support Servlet 3.0. For example, if you use Tomcat, you need at least Tomcat 7.

Starting from a New Eclipse Project

You can create a new TouchKit project from a regular Vaadin project created with the Vaadin Plugin for Eclipse (see "Creating and Running a Project with Eclipse").

After creating the project, you need to do the following tasks:

  1. Install the TouchKit library in the project by including it in the ivy.xml , as described in "Installing as Ivy Dependency", and compile the widget set.

  2. Extend TouchkitServlet instead of VaadinServlet in the servlet class, as described in "The Servlet Class". It is recommended that you extract the static inner class created by the wizard to a regular class, as you most probably need to do additional configuration in it.

    @WebServlet(value = "/*",
            asyncSupported = true)
@VaadinServletConfiguration(
        productionMode = false,
        ui = MyMobileUI.class)
public class MyProjectServlet extends TouchKitServlet {
}

  3. If you intend to define a fallback UI later, as described in "Providing a Fallback UI", you may want to copy the original UI class stub to use it as a fallback UI class.

  4. To get started quickly, disable the use of custom theme by using @Theme("touchkit") in the UI class. To create a custom mobile theme later, see "Mobile Theme".

    @Theme("touchkit")
public class MyMobileUI extends UI {

  5. Build the mobile UI preferring TouchKit components instead of the core Vaadin components, as described in "The UI".

We cover these and various other tasks in more detail in "Elements of a TouchKit Application".