PhoneGap By Example

We will see how to install Node.js from the official website and with Homebrew.

To install Node.js on Linux, we should be familiar with the terminal as well. First of all, we need to install dependencies. Follow these steps:

After that, we need to add the following three lines to .bashrc or .zshrc:

export PATH="$HOME/.linuxbrew/bin:$PATH"
export MANPATH="$HOME/.linuxbrew/share/man:$MANPATH"
export INFOPATH="$HOME/.linuxbrew/share/info:$INFOPATH"

So, all the prerequisites are done, and we can install Node.js now. There are only two steps left to follow:

Now, we can test Node.js and NPM by running node -v and npm -v in the terminal accordingly.

The app itself is an index.html web page by default, which connects a necessary CSS, JavaScript, images, media files, and other resources needed to run the application. The application runs in the native WebView wrapper, which can be spread through app stores.

The web view used by PhoneGap is the same web view used by the native operating system. On iOS, this is the Objective-C UIWebView class; on Android, this is android.webkit.WebView. There are differences in the web view rendering engines between operating systems, so we should account for this in our UI implementation.

The application can be fully or partially wrapped by WebView. For example, only some parts of the application may be made with HTML, and the remaining elements will be implemented with native components. In this book, we will consider that the applications are fully wrapped with WebView.

For interaction between our web page and the native components in Cordova, there is implemented plugins interface. This allows the JavaScript function to call the native components, and the native components transfer data in JavaScript. It might access the camera with JavaScript, accelerometer, or other device feature. Third-party plugins provide access to native features that are not necessarily present on every mobile platform. You can view all available plugins in the plugins repository (http://plugins.cordova.io/). You can also develop your own plugins. We will discuss this later.

PhoneGap offers two approaches in the development of PhoneGap applications. These are cross-platform workflow and platform-centered workflow.

Cross-platform workflow: I recommend you to use this workflow if you intend to develop a mobile application under several platforms and you have no differences in the programs for various platforms. With this approach, Cordova CLI (The command-line interface) is primarily used. The Cordova CLI allows you to compile applications for different platforms, manage plugins, and so on.

Platform-centered workflow: I recommend you to use this workflow if you plan to focus on developing applications for a single platform and plan to quite deeply integrate with native components. This approach implies a certain development for a specific platform. For example, for iOS native development, you will use the Objective-C language, and for Android development, you will use the Java language.

PhoneGap allows you to move from a cross-platform workflow to a platform-centered workflow, but you cannot do it in the reverse order. The folder's structure is different and includes a different set of shell tools. Therefore, we start with the use of cross-platform workflow.

In this book, we will mostly use cross-platform workflow, but there will be times when you have to switch to platform-centered workflow. The difference will be in using platform-specific shell tools. For example, for iOS, we will run iOS-specific SDK shell commands. For example, for release, we will run this command:

$ /path/to/my_new_project/cordova/build –release

In this section, we will discuss how to create an application and install it on different mobile platforms using the Apache Cordova command-line interface.

You will likely be surprised and ask about the difference between the PhoneGap command line and the Cordova command line, because we have already established PhoneGap. PhoneGap is a command-line utility that encapsulates Cordova. PhoneGap is built on Apache Cordova, and nothing else. You can think of Apache Cordova as the engine that powers PhoneGap. Over time, the PhoneGap distribution may contain additional tools, and that's why they differ in command, but they do the same thing. For the local build, PhoneGap uses the local library Cordova, but on the PhoneGap Build service, it uses it's own infrastructure. The official documentation for PhoneGap uses Cordova CLI.

We will also adhere to the official documentation necessary to carry out commands using Cordova CLI. Further, if necessary, we will use the PhoneGap CLI as well.

Before using the command-line tools, we needed to install the SDKs for each mobile platform we are targeting.

Cordova CLI supports the following combinations of platforms and operating systems:

On Mac, the command line is available via Terminal Application. On Windows PC, it's available as Command Prompt under Accessories.

We have already installed a PhoneGap library, but Cordova CLI also requires the installation.

For proper working of Cordova CLI, you must install a Git client, as the Cordova CLI refers to Git repositories to retrieve the necessary information. For more information on installing a Git client, you can refer to http://git-scm.com/. We should be able to run the Git command from the console. Once we have verified that the Git client is installed and running, let's install the Cordova CLI using NPM:

$ sudo npm install -g cordova

The preceding -g flag tells npm to install Cordova globally. Otherwise, it will be installed in the node_modules subfolder in the current folder.

Now, let's run our application in the iOS emulator using the following steps:

A similar procedure can be done with the help of the Cordova CLI:

$ cordova build ios

This generates ios platform-specific code within the project's platforms subdirectory.

The cordova build command is a shorthand for the following command:

    $ cordova prepare ios
    $ cordova compile ios

To run our application in the iOS emulator, it is enough to execute the following command:

$ cordova emulate ios

We will see the same application in the emulator that we saw when run from Xcode.

Under the Certificates section, press the + button in order to start certificate generation. On the screen, select iOS App Development.

Then, press the Continue button. After that, we see the instructions for how to generate Certificate Signing Request (CSR) on our computer. At this stage, we can begin to generate the CSR on our computer. In the Applications folder on your Mac, open the Utilities folder and launch Keychain Access. Within the Keychain Access drop-down menu, go to Keychain Access | Certificate Assistant | Request a Certificate from a Certificate Authority. After that, we will see the following screen:

In the User Email Address field, I entered my current e-mail. Usually, this is the same e-mail to access the Apple Developer Portal. In the Common Name field, I usually enter my name. If you have a company, it might be the company name. I am the owner of an Apple Developer account, so I do not need to send a request by e-mail. I just clicked on Save to disk and then on the Continue button. I saved the CSR file on your computer and completed the process of generating the Certificate Signing request.

Now, go back to the browser with instructions for the generation of CSR and click on Continue. I selected the .certSigningRequest file saved on my Mac and clicked on the Generate button. Once the certificate generation is over, I downloaded a ready certificate on my computer and double-clicked on it to add to my Mac keychain.

At this stage, the generation of the certificate is completed. Now, you need to attach your project team. The Xcode project needs to be assigned to a team so that Xcode knows where to create your code signing and provisioning assets.

To assign the Xcode project to a team, follow these steps:

This message appears because we have not generated a Provisioning Profile yet.

In order to generate a Provisioning Profile for our application, it must be registered with the Apple Developer Portal. To do this, on the presented Xcode screen, copy Bundle Identifier to the clipboard and switch to Apple Developer Portal. In the Identifiers section, press the + button. On the next page, you must enter the application Name and paste Bundle ID from the clipboard, as presented in the following screenshot:

After that, click on the Continue button, and on the next page, check the entered data and click on Submit. We added our application. Now, we need to register the device where we will be able to run our application.

To register the device in the Apple Developer Portal, go to Devices and click on the + button. On the form, you must enter the name of the device and its unique device identifier (UDID).

UDID can be found by connecting the Apple device to your computer in iTunes. If you go to the Device Manager tab and then to Summary, you will see the following screen:

Here, in the main section, you can copy the UDID by right-clicking on the UDID value. After that, go to the Apple Developer Portal, insert UDID, enter the Name of your device, and click on the Continue button:

Once the operation is complete, we will see our device in the Devices section. The next step is Provisioning Profile generation.

To generate a Provisioning Profile for our application, go to the Provisioning Profiles | Development and press the + button. After that, select the iOS Development application type and click on Continue.

In the next step, we will choose our application, Travelly, and go to the next page. Select the certificate generated by us and move on to the next step. In this step, we will select the devices on which we want to run our application:

At this stage, I chose two devices. I want to be able to test our application on both devices.

Finally, go to the next page and enter a name of the Provisioning Profile. Let's enter Travelly. Complete the generation by pressing the Generate button. Then, we can download this Provisioning Profile, or allow Xcode to it.

Now, in Xcode, we need to select a proper Provisioning Profile. Follow these steps:

Alternatively, you can simply click on a provisioning profile, and it will be automatically installed in the Xcode.

That's all. Now, you can run the application on the device. Connect your device to your computer using the USB cable. Select the intended device from the toolbar's scheme menu; in my case, it is Cybind's iPhone. Press the Run button that appears in the same toolbar to the left of the scheme. This button builds, deploys, and runs the application in the device. We can see how the application started on our device.

Similarly, we can run the application on our device from the console:

$ cordova run ios

This command displays a lot of information because the Cordova CLI builds iOS projects using Xcode, which displays all the information about how it builds the application.

Congratulations! We have successfully executed our initial application on the real iOS device.

So, I do not have Java installed. I go to the official website, http://www.oracle.com/technetwork/java/javase/downloads/index.html, to get the latest version of it. I download JDK for MAC OS X and install it. You should pay attention that it should be JDK, not JRE. Only JDK provides the required functionality to build our Android application. After JDK installation let's run this command and check whether Java has been successfully installed:

$ java -version
java version "1.8.0_25"
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.25-b02, mixed mode)

OK! We have successfully installed the JDK.

Let's try to add the Android platform in our application using the Cordova CLI again:

$ cordova platform add android
Creating android project...
Error: Please install Android target "android-19".
Hint: Run "android" from your command-line to open the SDK manager.

Apparently, we have not installed all the necessary packages for development under Android 4.4.2 (API 19) yet. Open the Android SDK Manager using the android console command. Select Android 4.4.2 (API 19) and press Install. The installation process should look like this:

You also need to install all the following packages in order to make sure that they all run smoothly:

For Cordova command-line tools to work, or the CLI that is based upon them, we need to include the SDK's tools and platform-tools directories in our path. On a Mac, I use a text editor to create or modify the ~/.bash_profile file, adding a line such as the following one:

export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools

You can see the path to your Android SDK in the SDK Manager window. You can launch it by going to Android Studio | Tools | Android | SDK Manager.

Here, in the top-left corner, you can see the SDK Path value. It is what we included in the path.

Once all the required packages are installed let's try to add the Android platform again:

$ cordova platform add android
Creating android project...
Creating Cordova project for the Android platform:
  Path: platforms/android
  Package: com.cybind.travelly
  Name: Travelly
  Android target: android-19
Copying template files...
Project successfully created.

And we have successfully done it! Now, in our platforms directory, we got the android subfolder. In the plugins folder, there appeared a new file named android.json.

To get started, go to https://developer.android.com/sdk/index.html and download Android Studio (with the Android SDK for Mac):

Once downloaded, install it using the following steps:

There will be one step where we need to add a path to the JDK. In my case, it looks like this:

On the license agreement screen, we will accept all the points:

It will take some time after that, and eventually, we will see the successful installation screen:

Now, let's try to open our Android project in Android Studio by following these steps:

Now, we can build and run the Android application directly from Android Studio.

We can add the Android emulator device now.

Open the terminal and enter the following command:

$ android avd

In the opened window, click on Create. In the window that appears, enter the parameters of the emulator. In my case, it looks like this:

I entered the name of the device, selected the Nexus 4 (4.7", 768 x 1280: xhdpi) device, and targeted Android 4.4.2 - API Level 19.

After that, I clicked on the OK button. We successfully added the emulator.

Go back to the main window of Eclipse, highlight the project, and click on the Run button. As a result, we see our project running in the Android emulator:

So, we can run our application in the emulator from the console with this command:

$ cordova emulate android

To run the application on the device, we only need to connect it to our computer and run this command:

$ cordova run android

That's all! We have completed the configuration of our project to run on iOS and Android emulators and devices. Now, let's discuss some of the best development practices for PhoneGap applications.

Single-page application (SPA) is a web application or website that fits on a single web page with the goal of providing a more fluid user experience.

Loosely defined, a SPA is a client-side application that is run from one request of a web page. The user loads an initial set of resources (HTML, CSS, and JavaScript) and further updates (showing a new view, loading data) are done via AJAX.

Some SPA libraries you can use in your Cordova applications are:

Often, we need an interaction between our application and other servers. We need it to share data between multiple endpoints: other mobile devices, websites, and so on. Very often, the architecture is built in such a way that it sends not just data, but layout information as well.

It will be better to just create a needed set of data on the server side and send it with JSON, XML, or other formats. It can be customized as well. Do not send HTML through the Internet because it could be stored on the client. We will reduce the payload without sending HTML through Internet.

Cache static and dynamic data on the device. It can be filesystem, local storage, or database. Use the offline-first approach. We will discuss this approach in the upcoming chapters.

We can create the illusion of faster hybrid application with the following approaches:

Using hardware-accelerated CSS transitions will be dramatically better than using JavaScript to create animations. See the list of resources at the end of this section for examples.

Combine images in sprites. It will decrease the number of requests and will improve the speed of image display. Just use CSS sprite sheets, which support high-resolution screens.

You can read about sprites on the following sites:

There are a lot of other resources that you can find online as well.

Compress CSS and JavaScript. Compress JPEG pictures. Don't use a full-stack framework just because you like a small piece of it. Use system fonts. Use fonts for icons.

Minimizing browser reflows will help in saving memory and CPU resources. We can do it with following steps:

Use Chrome Developer tools, Xcode profiler, and other tools to understand performance problems, memory leaks, and other issues in the application.

This framework is pure JavaScript and CSS. Sencha Touch is a mature framework built to fit the most demanding app needs. It is a versatile enterprise-level workhorse using CSS3 and HTML5 best practices. It uses the Model–View­Controller–Store pattern meant for serious business, with over 50 built-in components, from the basic ones such as component, container, form, and various fields to more complex carousel, lists, pickers, charts, grid, and much more. Sencha Touch includes themes for every popular mobile platform. Sencha Touch abstracts device APIs for their native packager and Cordova/PhoneGap. It has a large community and very detailed documentation. It takes some time to learn, but the documentation is awesome and everything goes smoothly. Unfortunately, it has a commercial license.

This jQuery-based framework is the most commonly used mobile application HTML5 framework. This is because jQuery is popular and transition to jQuery mobile is very easy. However, it is sluggish on mobile devices; it is not optimized as is Sencha Touch. It has an average UI, and the official documentation is lacking some information. There is no MVC support. It is even more sluggish when combined with PhoneGap.

Ionic is an open source framework. It is a pretty new library. Since its release, it has gained a lot of respect in the hybrid and mobile development community. Ionic provides a lot of utilities, and it is pretty easy to do small customizations for iOS, Android, and other operating systems. It uses Cordova for packaging from the box.

This is an open source framework from the Twitter Bootstrap creators. It provides a basic UI for iOS and Android (it's just UI components). To organize your application properly, you should architect it properly or use an additional library to do it for you. It means it doesn't support any kind of MV* pattern.

This jQuery-based framework is beautiful. It supports MVVM and has its own support for server-side communication (.NET, PHP and Java). It will cost you some money if you want to build a commercial application. It has great template support; every template looks like a native template. It supports MVC from the box and has great documentation.

This is just an open source library with well-done CSS. When you develop with Topcoat, you should care about the application structure, JavaScript, and performance on your own. It doesn't provide application wire framing or scaffolding.

This is the only view framework from Facebook. Yes, the developers had a little crooked soul; they did not make it for the sake of marketing. In fact, React is a view-oriented MVC framework, although it does not appear as such at first sight. The biggest advantage of React is that is uses a virtual DOM diff implementation for ultra-high performance. It is great with performance on the mobile device, but the learning curve is steep, and the documentation is still not too detailed or understood.

This is a free and full-featured HTML framework for building iOS apps. It is also an indispensable prototyping apps tool to show a working app prototype as soon as possible, in case you need to. It is easy to use and customize. It provides its own MVC framework. However, I would not use it for multiplatform development, because it represents only iOS UX/UI.

The Famo.us's mobile framework is a newborn baby. It's the newest framework on the market nowadays. Famo.us targets a specific need at this time: performance. With 60 fps animations, Famo.us is the choice for you if you want to brag in your hybrid app. Basically, Famo.us uses its own JavaScript engine that works with the GPU acceleration provided by CSS3 3D transformation functions to make animations as smooth as can be at 60 fps. Of course, we will not be able to reach 60 fps performance on old devices. This is for devices with good graphic cards. The Famo.us team is trying to tie it closely with the AngularJS framework. It is a good choice when building complex user experience animations, but the learning curve is steep, and the documentation is still not too detailed or understood.

Onsen UI is an Ionic competitor. It also comes with AngularJS support and provides the same solution as the Ionic team meant to build. Onsen UI was born as an answer for PhoneGap and Cordova developers who were struggling with the UI when starting a project, as the Internet lacks in mobile UI frameworks. The documentation in some places is not clear. I do not really like that I cannot use the default HTML layout but their own with ons- tags.

When I was researching these libraries, I compared them long enough to understand what I should choose to implement applications in this book. The main problem was the choice between Sencha Touch, Ionic and Onsen UI. Only these libraries have a sufficient set of ready-to-use components for the iOS and Android platforms and have solutions for an MV* pattern and a fairly good performance level on mobile devices. After some deliberation, I decided to choose the library that is the oldest on the market, has a huge community, and has good documentation. So, I selected Sencha Touch.