Build a Cross-Platform Twitter Client: Overview

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. The user interface of the application, called simply "Tweets", will be built using jQuery Mobile and PhoneGap will be used to create the native application. We will also use the PhoneGap Storage API to access native database functionality. All coding will be done with HTML and JavaScript utilizing jQuery, jQuery Mobile, and the PhoneGap libraries.

The main features of the Tweets application discussed in this series are as follows:

There is a single instance of application code that caters to both Android and iOS platforms. This illustrates the 'write once, deploy anywhere' aspect of the jQuery Mobile and PhoneGap frameworks.

The main functionality of the Tweets application is two-fold: (1) obtain a user's timeline (e.g. the most recent tweets posted by the user) and (2) find tweets by any user where the tweet content matches a search query. To implement that functionality, the application utilizes the web based Twitter API methods user_timeline and search. The application code is based on the jQuery ajax() function to access those API methods.

The user screen names and search terms are kept in a permanent store in order for them to persist between application restarts. For that purpose, we will use the PhoneGap Database and SQLTransaction objects.

The user interface of the Tweets application supports different layouts for narrow-screen devices, where display width is less than 500 pixels, and wide-screen devices, where display width is greater than or equal to 500 pixels. In that regard, a typical Android phone or an iPod touch device is considered a narrow-screen device, whereas a tablet (e.g. the iPad) is considered a wide-screen device. The threshold separating the narrow and wide-screen devices is a constant in the application code and can be changed if further customization is needed.

The application employs jquery-mobile-960, a grid implementation for jQuery Mobile, to display content in wide-screen devices. In the original grid implementation of jQuery Mobile, the columns are split evenly. The jquery-mobile-960 grid allows variable width grid columns giving the user interface designer more flexibility. This is particularly useful for tablet environments.

The Tweets application can be imported into Eclipse for the Android platform or Xcode for the iOS platform. An archive file accompanying this series contains all the files needed to import the application to those IDEs. We provide instructions for importing the Tweets application into both Eclipse and Xcode.

Organization Of The Series

This tutorial has been organized into 4 parts. In the next section of Part I, named "jQuery Mobile and PhoneGap", we briefly introduce jQuery Mobile and PhoneGap and discuss developing cross-platform native applications using those frameworks. In the following section, "Screen Flow", we present the Tweets application and describe its screen flow. The section named "jQuery Mobile Page Structure" is an introduction to several high level concepts in the jQuery Mobile framework, in particular, container and content pages.

In Part II, we will start reviewing the Tweets application. In "Review Of index.html", our main focus is on the static structure of the HTML and jQuery Mobile code that makes up the application screens. The section named "Twitter API" gives an overview of the Twitter API methods user_timeline and search. The next section, "Code Review", gives a review of the JavaScript code that implements the application functionality. Part II will discuss "Initial Page Load", "Utility Functions", and "Database Access Functions", and will start the discussion on "Core Business Logic Functions".

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

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

Credits

All the icons and splash images in the download archive have been created based on an icon set provided by Smashing Magazine. As stated on the linked web site, "You can use the set for all of your projects for free and without any restrictions. However, it is forbidden to sell them."

jQuery Mobile and PhoneGap

The jQuery Mobile Project is a user interface system for mobile devices that works uniformly across different platforms, such as Android and iOS. While jQuery Mobile mainly focuses on the uniformity of the user interface in a web application paradigm, the PhoneGap framework allows developing HTML5 and JavaScript based native applications that can be deployed in multiple mobile platforms including Android and iOS. Those frameworks can be used together to develop native applications where the user interface is built via jQuery Mobile and native device functions are constructed using PhoneGap.

The following diagram gives a simplified view of a native application deployed into Android and iOS, which was developed using HTML5, CSS, and JavaScript.

The user interface of the application utilizes jQuery Mobile libraries consisting of several JavaScript and CSS files. Those libraries provide a common look and feel across multiple Android and iOS devices.

The PhoneGap and JavaScript library exposes a common programming model encapsulating native device APIs for Android and iOS.

The application is deployed into Android and iOS devices using platform specific development tools (e.g. Eclipse for Android and Xcode for iOS). This step is also facilitated by PhoneGap as it provides device specific libraries that integrate with the development tools.

Please note that both jQuery Mobile and PhoneGap support additional mobile platforms such as BlackBerry OS, Symbian, and others. However, in this series we will focus on only Android and iOS.

Figure 1. jQuery Mobile and PhoneGap

Various advantages of developing native applications using jQuery Mobile and PhoneGap are listed below.

With jQuery Mobile, you would develop the user interface based on the jQuery Mobile user interface system using HTML5, CSS, and JavaScript. The user interface will have the same look and feel and will support a uniform event handling model across different platforms.

Similarly, for accessing native device features, you would code in JavaScript utilizing the PhoneGap device API. There is no need to code against device specific APIs. Across different platforms, the application will function uniformly.

Since you do not have to use platform specific user interface and programming models, you can develop and deploy your applications faster.

Both jQuery Mobile and PhoneGap are open source technologies.

On the other hand, there are disadvantages of developing a native application using jQuery Mobile and PhoneGap. Some of those are mentioned below.

The user interface offered by jQuery Mobile has a peculiar web application look and feel. User interface features unique to a platform will be lost (This could potentially be avoided by incorporating a platform specific CSS library into your application. However, combining that with the jQuery Mobile libraries would require additional development effort).

To access native features, you will be limited to what the PhoneGap device API provides, which is only a subset of the available native APIs for Android or iOS (Note that the PhoneGap device API is broad and encompasses many useful native features such as the Accelerometer, Camera, Geolocation, Media, and Storage APIs among many others).

In addition, as in any development project, you still have to use platform specific development and testing tools to test and deploy your application across Android and iOS devices.

For the sample application discussed in this series, we used jQuery Mobile version 1.0 RC1 and PhoneGap version 1.1.0. Those were the latest versions at the time of creating this series.

Screen Flow

There are two distinct patterns of screen flow, one for wide-screen devices where the display width is greater than 500 pixels and one for narrow-screen devices where the display width is less than 500 pixels. With this definition, an iPad device will be considered wide-screen whereas an iPod touch or Motorola Droid phone will be considered narrow-screen. The threshold, 500, is a constant that is defined in the application code.

Let us first look at the screen flow for wide-screen devices. The initial screen has two buttons with labels 'Add Screen Name' and 'Add Search Term'. There is a text field under the buttons. On the lower left section of the screen there is a list consisting of the screen name and search terms entered by the user. The screen names have grey and the search terms have a yellow background.

Figure 2. Wide-Screen Devices: Initial Screen

In order to enter a Twitter screen name, the user types the name in the text field under the buttons and presses the 'Add Screen Name' button. Similarly, in order to enter a Twitter search term, the user types the term in the text field under the buttons and presses on the 'Add Search Term' button.

If the user clicks on the delete button on the far right section of a list item (represented as an 'x' inside a circle), that item is removed from the list.

Figure 3. Deleting the List Item

If the user clicks on a list item for a Twitter screen name, a spinning wheel is displayed as an indication that the user timeline (tweets) for that screen name is being retrieved from Twitter.

Figure 4. Wide-Screen Devices: Retrieving User Timeline

After receiving the timeline associated with the screen name, the application displays them on the right side of the page next to the list. Those are the latest 11 timeline items associated with the screen name. The threshold, 11, is a constant defined in the application code.

Figure 5. Wide-Screen Devices: User Timeline

Note that, per the Twitter API, it is possible to retrieve a user's timeline without authentication only if their timeline is not protected / private. Our application does not involve authentication, hence the reason only public timelines are available to us.

Similarly, if the user clicks on a list of items for a Twitter search term, a spinning wheel is displayed as an indicator that search results are being retrieved from Twitter, similar to the display in Figure 4. After receiving the search results, the application displays them on the right side of the page next to the list, similar to Figure 5. Those are the latest 11 results associated with the search term. The threshold, 11, is a constant defined in the application code.

The timeline or search results may include URL links. If the user presses any of those links, a web browser will be launched to display the web page associated with the link. When this happens, the Tweets application is no longer active.

The following diagram summarizes the screen flow discussed above.

Figure 6. Wide-Screen Devices: Screen Flow

For narrow-screen devices, the screen flow is similar, however, due to lack of space, the inputs (list items), progress page, and the results are displayed in different screens.

The initial screen, the 'Inputs' page, has the buttons, the text field, and the list of the screen names and search terms stacked.

Figure 7. Narrow-Screen Devices: Inputs Page

If the user clicks on a list item, the 'Progress' page is displayed as a separate screen.

Figure 8. Narrow-Screen Devices: Progress Page

When the results are received, the Progress page is replaced by the 'Results'.

Figure 9. Narrow-Screen Devices: Results Page

If the user presses any of the URL links in the Results page, a browser application will start to display the web page in the link. When this happens, the Tweets application is no longer active. In Android devices, the user can go back to the Tweets application by pressing the back button of the device. For iOS devices, the user needs to close the browser and launch the Tweets application from the home screen by pressing the application icon.

The diagram below summarizes the screen flow for narrow-screen devices.

Figure 10. Narrow-Screen Devices: Screen Flow

jQuery Mobile Page Structure

We will now discuss how the screens in our application will be represented using the jQuery Mobile page elements (Here, we borrow some material from my previous tutorial Build a Contacts Application. Also, for a detailed discussion on how pages are constructed with the jQuery Mobile framework, see the Anatomy of a Page section in the jQuery Mobile reference documentation).

A single HTML file in the jQuery Mobile framework consists of one container page with one or more content pages inside the container. The container page has a data-role="page" attribute, whereas the content pages have a data-role="content" attribute. A content page can optionally have both a header and a footer. In the example below, there are two content pages with both a header and a footer, and one content page without a header or a footer.

Within a container page, it is intended to display only one content page at a time. The idea is to group logically related screens together inside a single container page and define each of those as a content page. For example, those content pages may share common JavaScript code.

In the Tweets application, there is one container page which is stored in the physical page index.html. That container page stores all the content pages needed by the application. For the narrow-screen devices, the Inputs (Figure 7), Progress (Figure 8 ) and Results screens (Figure 9) are represented as a separate content pages. For wide-screen devices, there is only one content page, named 'Wide', providing all the required functionality. The following figure summarizes this discussion.

Figure 11. Page Structure

Closing Remarks

In the initial part of this tutorial, we briefly introduced jQuery Mobile and PhoneGap and discussed developing cross-platform native applications using those frameworks. Then, we presented the Tweets application and described its screen flow. Next, we gave an introduction to several high level concepts in the jQuery Mobile framework. In particular, the container and content pages were discussed.

In Part II, we will start reviewing the Tweets application. In "Review Of index.html", our main focus will be on the static structure of the HTML and the jQuery Mobile code that makes up the application screens. The section named "Twitter API" will give an overview of the Twitter API methods user_timeline and search. The next section, 'Code Review', will give a review of the JavaScript code that implements the application functionality. Part II will discuss the "Initial Page Load", "Utility Functions", "Database Access Functions", and then start the discussion on "Core Business Logic Functions".