Also available in this series:
- Build a Cross-Platform Twitter Client: Overview
- Build a Cross-Platform Twitter Client: Twitter API & Code Review
- Build a Cross-Platform Twitter Client: Completing the Code Review
- Build a Cross-Platform Twitter Client: Deployment
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
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
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".
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 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.
Various advantages of developing native applications using jQuery Mobile and PhoneGap are listed below.
- 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.
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.
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.
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.
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.
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.
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.
If the user clicks on a list item, the 'Progress' page is displayed as a separate screen.
When the results are received, the Progress page is replaced by the 'Results'.
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.
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.
<div data-role="page"> <div data-role="header">...</div> <div id="contentWithHeaderAndFooter1" data-role="content">...</div> <div data-role="footer">...</div> <div data-role="header">...</div> <div id="contentWithHeaderAndFooter2" data-role="content">...</div> <div data-role="footer">...</div> <div id="contentWithNoHeaderAndFooter" data-role="content">...</div> </div>
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.
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