Offline Mode for TouchKit 4 Mobile Apps

Background

Vaadin is primarily a server-side framework. What happens with the application when the server is not available? Although this is possible on desktop computers, more often it happens when using a mobile device. This is why Vaadin TouchKit allows you to define offline behaviour. In this article I will tell you all the details you need to know about offline mode and how to use it. It is written based on Vaadin 7.3 and TouchKit 4.0.0.

Touchkit is a Vaadin addon that helps in developing mobile applications. I assume that you have some knowledge in Vaadin and an idea how to develop client-side Vaadin (GWT) code. The Parking demo one application where you might have seen offline mode in practice. While you can find its sources it here, I suggest that you read this article before you try to understand them. It will help you grasp the concepts demonstrated in the demo.

Demystifying offline mode

As said before, by default Vaadin is a server-side framework and that implies that when an application is running, and server-side views are not accessible when there is no connection. On the other hand, offline enabled applications run pure client-side Vaadin (GWT) code without connecting the server. 

There are at least a couple of approaches you might take to specify offline behavior on the client-side.

1. Write a fully client-side application for the user to interact with when the server is offline.

2. Write some views as client-side widgets and, in case the connection is lost, disable all the components that might need a server connection.

Let’s take a look at the technical details you need to know.

Setting up the offline mode

You can turn a Vaadin application into an offline-enabled TouchKit application by using an extension of TouchKitServlet as your servlet class. For example, the following might be your servlet declaration in your UI class:

@WebServlet(value = "/*")
public static class Servlet extends TouchKitServlet /* instead of VaadinServlet */ {} 

Client-side offline mode handling - method 1: checking the status

The simplest way to know if the application is online or offline is to use this code:

OfflineModeEntrypoint.get().getNetworkStatus().isAppOnline() 

You might use it before sending something to the server or calling an RPC, for example. However, the network status might change at any time. Method 2 helps you react to those changes. 

Client-side offline mode handling - method 2: handling events

In order to use this method you need an ApplicationConnection instance. We are going to use its event bus to handle online/offline events. Usually you get an ApplicationConnection instance from a component connector. Here is an example:

@Connect(MyComponent.class)
public class MyConnector extends AbstractComponentConnector
{

  @Override
  protected void init() {
      super.init();
      getConnection()
         .addHandler(OnlineEvent.TYPE, 
                     new OnlineEvent.OnlineHandler() {

          @Override
          public void onOnline(final OnlineEvent event){
            // do some stuff
          }

      });

      getConnection()
          .addHandler(OfflineEvent.TYPE, 
                      new OfflineEvent.OfflineHandler() {
         @Override
         public void onOffline(final OfflineEvent event)
         {
            // do some stuff
           }
     });
 }
} 

Note that this connector will only be created if an instance of MyComponent is created on the server side and attached to the UI. As an option, it might be a UI or Component extension connector. Otherwise your connector will never be instantiated and you will never receive these events, so you can rely on them only if you want to show some changes in the view or disable some functionality of a view when offline. In order to get true offline capabilities, use method 3.

Client-side offline mode handling - method 3: implementing OfflineMode interface 

Implementing client-side OfflineMode interface allows you to specify true offline-mode behavior: you will receive events also in case the page is loaded from cache without network connection at all.

Fortunately, there is a default implementation and you don’t need to worry about the implementation details. DefaultOfflineMode provides an OfflineMode implementation for any TouchKit application. By default it shows a loading indicator and a sad face when the network is down. In most cases all you want to do is replace this sad face with something more useful (for example Minesweeper or Sudoku), here’s a sample:

public class MyOfflineMode extends DefaultOfflineMode {

   @Override
   protected void buildDefaultContent() {
      getPanel().clear();
      getPanel().add(createOfflineApplication()); // can be a full blown GWT UI
  }
}

Then you need to specify the implementation in your widgetset definition file (*.gwt.xml):

<replace-with
   class="com.mybestapp.widgetset.client.MyOfflineMode">
   <when-type-is 
     class="com.vaadin.addon.touchkit.gwt.client.offlinemode.OfflineMode" />
</replace-with>

This is enough for showing an offline UI, it will be shown and hidden automatically, DefaultOfflineMode will take care of this. If you need a more complex functionality, like doing something when going offline/online, you might want to override additional methods from DefaultOfflineMode or implement OfflineMode.

Now when you have a setup for your offline Vaadin TouchKit application, you can go further with offline integration and for example use PhoneGap to package your app. Among other things, you can find more details about this in Vaadin wiki.

Read more about Vaadin Touchkit 4 and offline mode