Advertisement

Build a Cross-Platform Twitter Client: Deployment

by
Student iconAre you a student? Get a yearly Tuts+ subscription for $45 →

In this series, we will develop a Twitter client using the jQuery Mobile and PhoneGap frameworks. This project will be deployed to Android and iOS environments as a native application.


Also available in this series:

  1. Build a Cross-Platform Twitter Client: Overview
  2. Build a Cross-Platform Twitter Client: Twitter API & Code Review
  3. Build a Cross-Platform Twitter Client: Completing the Code Review
  4. Build a Cross-Platform Twitter Client: Deployment

Organization Of Part IV Of This Series

In Part III, we continued inspecting the "Core Business Logic Functions" taking up from where we left in Part II and finished the code review of the Tweets application by looking at "Event Handlers" & "Page Display Functions".

In this the final part of our tutorial, we will start with the section named "Files In Download Archive", where we will describe the contents of the archive file accompanying this article. In "Environment Specific Topics", we will explain how to import the application into Eclipse for the Android platform and into Xcode for the iOS platform. In that section, we will also give screen images of the application in an Android phone, an iPod touch, and an iPad 2. Finally, we will give concluding remarks in the aptly named "Conclusions" section.


Files In Download Archive

In this section, we will describe the contents of the archive file accompanying this article.

The Android folder consists of a single file, Tweets.zip. This is an Eclipse project that has all the required files to create the Tweets application in an Android 2.2 device. See also "Android Development Environment" below.

The iOS folder consists of three sub-folders: www, icons, and splash. Those folders store various files that need to be copied to the Xcode project for creating the Tweets application in iOS devices. For details see the "iOS Development Environment" section below.

Please note that all the icons and splash images in the download archive have been created based on an icon set provided by http://www.smashingmagazine.com/2008/09/23/practika-a-free-icon-set/. As stated on the web site "You can use the set for all of your projects for free and without any restrictions. However, it ís forbidden to sell them."

An example of a startup icon for the Tweets application:


Figure: A Start-up Icon

An example of a splash screen image for the Tweets application:


Figure: A Splash Image


Environment Specific Topics

In this section, we will discuss topics regarding the development environments for Android and iOS versions of the sample application.

For both Android and iOS environments, the latest version of jQuery Mobile can be downloaded from http://jquerymobile.com/download/ and related documentation is available via the Documentation link in http://jquerymobile.com/.

As a prerequisite for both Android and iOS environments, PhoneGap must be installed in the development machine. PhoneGap documentation can be accessed from http://wiki.phonegap.com/. From that page, follow the links to tutorials for Android and iOS specific installation instructions and other environment specific documentation. The most recent version of PhoneGap can be downloaded from the download link on http://phonegap.com.

Android Development Environment

For the Android platform, the sample application in this article has been developed based on the following configuration.

  • Development machine: Windows Operating System
  • Development tool: Android SDK Tools, revision 8, Eclipse 3.5, Java SDK version 1.5
  • PhoneGap version: 1.1.0
  • jQuery Mobile version: 1.0rc1
  • Android version (tested): Android 2.2

Importing The Eclipse Project

Before importing the project into your Eclipse environment, make sure that the Eclipse ADT plugin points to the correct location of the Android SDK on your local system. To check this, in Eclipse menu go to Window -> Preferences -> Android. The SDK Location window must be set to the location of the Android SDK. Once set up correctly, you should see something similar to the image below:


Figure: Eclipse Preferences

The project files are provided in an archive file named Tweets.zip. To import the project, in Eclipse menu go to File -> Import and then in the file import wizard select General -> Existing Projects into Workspace (see below).


Figure: Project Import

On the next page of the wizard, choose Select archive file: and browse to where Tweets.zip is located in your file system. The Projects window will be automatically populated where the Tweets project is already selected. This is shown below. Press the Finish button to complete the import.


Figure: Project File Selection

Eclipse will build the application automatically after import. Now, you should see the Tweets project in the project explorer, as shown below:


Figure: Project Explorer

This project has been built and tested for the Android 2.2 platform. To verify this, select the Tweets project in project explorer and from the right-click menu choose Properties. On the left hand listing of properties, select Android as the property. The available build targets are displayed on the right, as shown below. You should see that Android 2.2 has been selected.


Figure: Android Build Target

File Listing

A list of the files in the project is given below:


Figure: File Listing

The src folder stores the Java code. The only Java file in our application is named App.java and is under the com.jquerymobile.tweets package. This Java file is a typical example of an Android application built on the PhoneGap framework.

 
package com.jquerymobile.tweets; 
 
import com.phonegap.DroidGap; 
import android.os.Bundle; 
 
public class App extends DroidGap { 
    /** Called when the activity is first created. */ 
    @Override 
    public void onCreate(Bundle savedInstanceState) { 
        super.onCreate(savedInstanceState); 
        super.setIntegerProperty("splashscreen", R.drawable.app_splash); 
        super.loadUrl("file:///android_asset/www/index.html"); 
    } 
}

Observe that the Java class extends DroidGap, which is provided by the PhoneGap framework. The loadURL() method loads the index.html file that has the actual application code implemented in JavaScript.

Let us continue our review of the files in the Eclipse project.

  • The gen folder contains various files automatically generated by the Eclipse ADT plugin.
  • The assets folder stores index.html, jQuery Mobile/jQuery JavaScript libraries, the jquery-mobile-960 grid library, and the PhoneGap JavaScript library. It also contains an images folder. The images folder consists of wait.gif, the spinning wheel image, and various icon images that are needed by the jQuery Mobile style sheets.
  • The lib folder stores the PhoneGap Java library.
  • The res folder stores various resources needed by the application. Specifically the icon images and configuration files strings.xml, main.xml and plugins.xml.
  • default.properties is a system generated file that defines the API version for the Android application.
  • The proguard.cfg file is automatically created by the development environment and is used by the ProGuard tool. Details can be found in ProGuard Documentation.
  • AndroidManifest.xml is the application manifest file.

iOS Development Environment

For the iOS platform, the sample application in this article has been developed based on the following configuration.

  • Development machine: MacOS Operating System
  • Development tool: Xcode
  • PhoneGap version; 1.1.0
  • jQuery Mobile version: 1.0rc1
  • iOS version (tested): 4.3

Developing The Application in Xcode

Let us review the steps to develop the Tweets application in Xcode.

From the Xcode File menu, select New Project, as shown below:


Figure: Launch New Xcode Project

Under User Templates, select PhoneGap. As mentioned previously, as a prerequisite, PhoneGap must be installed in your development machine. Otherwise, it will not show up in the Xcode environment as a template! You should see something similar to the below. Click Choose.


Figure: PhoneGap-based Application

Save the project. In the example below, we name the project TweetsTest.


Figure: Save the Xcode Project

Let us assume that the TweetsTest is the root folder for your Xcode project. From the download archive accompanying this article, copy the css-js folder and the index.html file under TweetsTest/www, as shown below:


Figure: Copy Files Under www

Because we created the Xcode project based on a PhoneGap template, the index.html already exists under www. As a result, you will be prompted whether the existing file should be replaced or not. Click Replace, as shown below:


Figure: Replace index.html

Similarly, replace the following 4 files under TweetsTest/Resources/splash with the ones in the download archive accompanying this article: Default-Landscape.png, Default-Portrait.png, Default.png, Default@2x.png. Also, replace the following 3 files under TweetsTest/Resources/icons with the ones in the download archive: icon-72.png, icon.png, icon@2x.png.

Open TweetsTest/PhoneGap.plist with the Property List Editor and add to the key named ExternalHosts an array consisting of a single element of type String. The value of the element corresponding to Item 0 should be *. This is shown below:


Figure: Edit PhoneGap.plist

Now, when you look at the source of PhoneGap.plist, e.g. via Dashcode, it should look like this:


Figure: PhoneGap.plist

Open TweetsTest/TweetsTest-Info.plist with the Property List Editor and change the bundle display name to Tweets, as shown below.


Figure: Change Bundle Display Name

Finally, edit TweetsTest/Classes/AppDelegate.m, to replace the shouldStartLoadWithRequest method as follows:

 
/** 
 * Start Loading Request 
 * This is where most of the magic happens... We take the request(s) and process the response. 
 * From here we can re direct links and other protocalls to different internal methods. 
 */ 
- (BOOL)webView:(UIWebView *)theWebView shouldStartLoadWithRequest:(NSURLRequest *)request  
  navigationType:(UIWebViewNavigationType)navigationType 
{ 
  NSURL *url = [request URL];  
  // Intercept the external http/https requests and forward them to Safari 
  // See http://www.tonylea.com/2011/phonegap-external-link/ 
  if( [[url scheme] isEqualToString:@"http"] ||  
    [[url scheme] isEqualToString:@"https"])  
  {  
    [[UIApplication sharedApplication] openURL:url];  
    return NO;  
  }  
 
  else  
  {  
    return [ super webView:theWebView shouldStartLoadWithRequest:request  
      navigationType:navigationType ];  
  }  
}

We are making this change to ensure that, when the user presses on a link on the list of results associated with a user timeline or search query, a new Safari browser window opens to display the web page. Had we not made that change, the web page would be displayed in the Tweets application itself and it would be impossible to go back to the application. For details, see http://www.tonylea.com/2011/phonegap-external-link/.

After The Installation

In this section, we will provide various screen images of the application after it has been installed on Android and iOS devices.

The following is the launch icon of the Tweets application on an Android phone.


Figure: Android Home Screen

The below image shows the Inputs and Results pages of the Tweets application on an Android phone.


Figure: Android Screens

The following is the launch icon of the Tweets application on an iPod touch device.


Figure: iPod Touch Home Screen

The below image shows the Inputs and Results pages of the Tweets application on an iPod touch device.


Figure: iPod Touch Screens

The following is the launch icon of the Tweets application on an iPad 2 device.


Figure: iPad 2 Home Screen

The following is the main screen of the Tweets application on an iPad 2 device.


Figure: iPad 2 Screen


Conclusions

In this article, we developed a Twitter client using jQuery Mobile and the PhoneGap frameworks and deployed it to the Android and iOS platforms as a native applications. We illustrated how jQuery Mobile and PhoneGap could work together when creating cross-platform native applications. In particular:

  • jQuery Mobile is used to develop the user interface functions.
  • PhoneGap is used to create the native application and to access device specific APIs.
  • There is a single code set for the application, which is written in HTML & JavaScript using jQuery, jQuery Mobile, and the PhoneGap libraries.

We also discussed several pros/cons of using jQuery Mobile and the PhoneGap frameworks when creating cross-platform native applications. Because there is a single code set for user interface and device functions, the "write once, deploy anywhere" approach saves development time. A user interface developer experienced with JavaScript and jQuery can quickly develop cross platform native applications because there is no need to learn device specific programming languages and APIs. On the other hand, the user interface will have a distinctive web application look and feel and will not fully leverage the user interface features available on the device. Similarly, the application code will be limited to the subset of the native device API as "bridged" by PhoneGap. It is the author's opinion that, for many real life applications, the advantages mentioned above will outweigh the disadvantages.

In this article, we additionally discussed the Twitter API and explained how to obtain a user's timeline, e.g. the most recent tweets posted by the user, and how to find tweets by any user where the tweet content matches a search query. We showed how to access those API methods using the jQuery ajax() function. Finally, we demonstrated jquery-mobile-960, a grid implementation for jQuery Mobile, which is very useful to define layout in wide-screen devices, e.g. an iPad tablet.

Advertisement