photoKandy Studios

Consider this to be the little brother to PhoneGap 2.x Mobile Application Development. This essentially explores a modified version of the social app as presented in Chapter 2 of the full book.

About The Book

This book is all about creating a simple Social Media application, mostly using Twitter. You’ll learn how to:

• Consume feeds using Twitter’s JSON API (v1) ¹
• Share content using Twitter’s Web Intents
• Cross-Platform Application Development
• How to Install Plugins

Do keep in mind the following:

• The book was written with PhoneGap 2.2 in mind. Of course, PG has advanced a bit, but the project itself should still work. You may want, however, to consider using PG’s In App Browser instead of the Child Browser plugin.
• The project was conceived before there was real talk of killing the V1 Twitter API. This API goes dark May 7, 2013. That means the app in the book will go dark then as well, although that doesn’t mean there’s not a lot else contained in the book about how to write cross-platform apps and parse feeds and such. I am investigating some modifications to the app that would keep it relevant after v1 goes dark.
• You should be familiar with HTML, CSS, and Javascript, as well as your operating system’s command line, and your development environment. You should also be able to install the platform-specific SDKs and PhoneGap.
• Just like the full book, this book utilises the YASMF library, but used v0.2. v0.3 is under active development should you wish to contribute.

Sample / Purchase

You can get the book or a preview at any of the following:

• Amazon.com
• Packt’s Site

The code package for the book is also available at Packt’s site as listed above. Just go under the “Support” tab.

What the Book Does Not Cover

Finally, also understand that the book does not deal with any of the following:

• PhoneGap Build
• Using a specific IDE (other than required; I tried to remain IDE-agnostic)
• Installing PhoneGap (the book assumes you can install PhoneGap first)
• Installing any of the platform-specific SDKs (again, the book assumes you can do this)
• Submitting to any of the App Stores

What the Book Assumes

The book also assumes that you:

• Understand the command line on your operating system. (The bias here is Mac, so the command line examples are BSD/*nix-like. Windows users will have to translate on their own as I’m no longer a Windows CLI expert.)
• Understand HTML, CSS, and Javascript. Although I try to explain what each particular piece of code, there are places where your understanding is simply going to have to supply the meaning. The book is long enough as it is — and each topic alone would consume several books. This book is more about how to put it all together to make something cool, not about how to make your next website with some CSS and HTML.
• Can Install the required SDKs and install PhoneGap.
• Understand how to use your preferred IDE (and Eclipse/XCode when required).

Who This Book May Not Be For

Who this book may not be for:

• I don’t go into a lot of great depth about the PG APIs. I do show how you can use some of them to interesting and cool effect, but I don’t go into every last detail about every last method in the API. Frankly, that’s what the PhoneGap Docs are for.
• The app, though relatively simple, is fully functional, and relies heavily on HTML, CSS, and lots of Javascript. If you’re looking more for snippets of how to use specific APIs, this isn’t for you. The book is about how to write an entire mobile app, not about snippets of code.
• If you don’t like cookbooks, then you might want to find another book. I did try to lean away from being overly cookbook-ish by adding in lots of explanation, but for those who really, really don’t like the format, there are other books for you.

Contest

So Packt’s been kind enough to give away FOUR free copies of the book. All you need to do is look at the book’s description from Packt’s Site and let me know what interests you the most about the book in the comments below. Be absolutely certain to use your real email address as that will be how you are contacted if you’ve won a free copy. (Note that Packt will be picking the winners; I have no control over who is chosen.)

The contest itself ends April 20th. If you do win, there are no other conditions, though if you find the book useful (or not), I’d love to hear your thoughts about it. Even better, leave a review on Amazon’s site. Just remember, though, you aren’t required to leave a review of any kind.

Edits

• Added image of book cover (4/15/2013)

As you may have noticed on my website, or my postings on the Google Group, I’ve written a book about PhoneGap entitled “PhoneGap 2.x Mobile Application Development”.

I’ll be the first to say that the title is a little bit of a misnomer: PhoneGap 2.2 is the version that all the projects use. And PG itself is now several versions beyond that. C’est la vie — this is not atypical when writing a tech book. By the time it is published, it is already becoming out-of-date.

But that’s not to say that the book doesn’t hold any value: I think it has quite a bit of value (and as far as I know, the projects themselves should still work under PG2.5, perhaps with minor modifications), and I wanted to put up a quick post about what the book is all about.

Ten Mobile Apps

The book is about more than just PhoneGap, it’s about how to write some interesting mobile apps for iOS and Android. So even though some things have changed with recent versions of PhoneGap, the book is really more about creating mobile apps, and it just happens to use some of PhoneGap APIs to get access to various native features on the mobile device.

There are ten projects and two appendices:

• A simple Quiz app, giving a good example on how to do localization and globalization.
• A simple social media app, using Twitter’s API and native sharing plugins.
• A simple note-taking app, with persistent storage using the PG File API.
• An app that can record a trip using geolocation and then render that path on a map using the Google Maps API as well as the Geolocation API.
• An memo app that can record and playback short voice memos using the PG APIs for media recording and playback.
• A simple camera & gallery app, using the PG Camera APIs.
• A simple video app, that both recordes and played-back videos using the Media APIs as well as some plugins to handle the video.
• A simple arcade-style game, showing how to use the accelerometer for input.
• A variation on the social media app, this time using native iOS plugins for a closer-to-native feel.
• Two variations on the note-taking app showing how to adjust the user interface when dealing with larger devices (like the iPad).
• A short appendix on some common mobile design patterns.
• A short appendix on how to install ShareKit 2.0 for iOS into a PG app.

In each project, we describe the design of the look and feel, the design of the various data models needed, and then the actual implementation. The style here is a bit “cookbook”, and this was at the insistence of the publisher. (My preference would have been a bit different. But one doesn’t win every battle, and I still think it provides a lot to chew on as it is presented.)

For each project, the full code is available from Packt, and also on my own Github repo. All but the last two chapters work on both iOS and Android, though I will admit to there being an iOS bias to the book. After all, I own a couple Macs, an iPad, and an iPhone, and they are my preferred devices. You can download the code from Packt’s site for the book, or from GitHub.

Where to Get It

If you’d like to get a sample chapter, or even better, purchase the book, you can find it in several places, including Packt’s site for the book or on Amazon.com. It’s available both in print and e-book form.

Errata

If you do decide to purchase the book, do be aware, that like any book, there will be errors and mistakes found. Be sure to check the errata for the book on the “Support” tab on Packt’s site for the book.

Caveats

Also, please remember that 2.3.0 came out at about the same time. It had been a miracle that I was able to update the book for 2.2, so there are doubtless some issues between 2.2 and the current version that may crop up. This was also prior to being able to use Cordova-CLI to manage projects (released with 2.3), and so the intial project-creation steps are a bit daunting. Honestly, it’s easier to use the repo instead of typing all the commands to create a project based on my structure, but you might also want to use Cordova-CLI to create the projects now instead of the steps in the book, just refer back to my earlier article on Getting Started with Cordova-CLI.

What the Book Does Not Cover

Finally, also understand that the book does not deal with any of the following:

• PhoneGap Build
• Using a specific IDE (other than required; I tried to remain IDE-agnostic)
• Installing PhoneGap (the book assumes you can install PhoneGap first)
• Installing any of the platform-specific SDKs (again, the book assumes you can do this)
• Submitting to any of the App Stores

What the Book Assumes

The book also assumes that you:

• Understand the command line on your operating system. (The bias here is Mac, so the command line examples are BSD/*nix-like. Windows users will have to translate on their own as I’m no longer a Windows CLI expert.)
• Understand HTML, CSS, and Javascript. Although I try to explain what each particular piece of code, there are places where your understanding is simply going to have to supply the meaning. The book is long enough as it is — and each topic alone would consume several books. This book is more about how to put it all together to make something cool, not about how to make your next website with some CSS and HTML.
• Can Install the required SDKs and install PhoneGap.
• Understand how to use your preferred IDE (and Eclipse/XCode when required).

Some Important Notes

Also a couple of things to note (based on reviews already received from Amazon):

• The command-line is pretty critical to PG now-a-days, and so there’s nothing in the book about how to create multi-platform projects graphically. There is a section that describes the steps I used to go through (before Cordova-CLI), and I’ll admit that it comes in on the long side. But examine the project structure, and I think it’ll be clear why I did what I did.
• The preface refers to the code repository on Packt’s website. Chapter 1, for a time, referred to a repo that was private, and so appeared to be invalid. Frankly, my mistake, though I had thought that the editor had changed the link to refer to the book’s website, not the repo. I’ve since corrected the error, and so address in the book does point at a valid repo.
• The book does use YASMF as the framework for the apps – not jQuery, Sencha, or the like. I have a very good reason for this: the idea is not to muddy the waters with lots of stuff that’s specific to jQuery or Sencha. YASMF met that need by being especially simple (v0.2 provides a very basic framework, and very few widgets), and so the intent was to focus more on how everything connects together. The idea is then that you can take those ideas and apply them to any framework of your choice. That said, v0.3 of the framework is under development, and will be a bit more complex than the version used in the book (especially with widgets).
• I’m of the camp that we should build PhoneGap apps a lot like the way we build native apps: that is, a little bit of “visual stuff” (HTML/CSS), and a lot of code to glue it all together. These are apps, not websites, and so the code should reflect that nature.

Who This Book May Not Be For

Who this book may not be for:

• I don’t go into a lot of great depth about the PG APIs. I do show how you can use some of them to interesting and cool effect, but I don’t go into every last detail about every last method in the API. Frankly, that’s what the PhoneGap Docs are for.
• The apps, though relatively simple, are fully functional, and rely heavily on HTML, CSS, and lots of Javascript. If you’re looking more for snippets of how to use specific APIs, this isn’t for you. The book is about how to write an entire mobile app, not about snippets of code.
• There are places where I expect your intuition to fill in some of the gaps – the book is quite long as it is, and so there were places where I could explain every single facet.
• If you don’t like cookbooks, then you might want to find another book. I did try to lean away from being overly cookbook-ish by adding in lots of explanation, but for those who really, really don’t like the format, there are other books for you.

Contest (Added 4/12/2013)

So Packt’s been kind enough to give away THREE free copies of the book. All you need to do is leave a comment below indicating that you’d like to participate in the contest and also indicating what you think the coolest thing about PhoneGap is. Be absolutely certain to use your real email address as that will be how you are contacted if you’ve won a free copy.

The contest itself ends April 20th. If you do win, there are no other conditions, though if you find the book useful (or not), I’d love to hear your thoughts about it. Even better, leave a review on Amazon’s site. Just remember, though, you aren’t required to leave a review of any kind.

Edits

• Added photo cover (4/15/2013)

Not too long ago, I wrote a short article about Getting Started with Cordova-CLI, and I thought I’d write a short follow-up – this time about hooks and merges.

Hooks

The concept of hooks in Cordova-CLI is pretty simple: before and/or after any command is run (that supports hooks, say cordova prepare or cordova emulate), you can have small scripts fire. This means that the Cordova-CLI system can be immensely flexible in both input and output, especially when integrating with external Build Servers.

There’s plenty of things you can hook into (obtained from the $PROJECT_ROOT/.cordova/hooks directory):

• build
• compile
• docs (?)
• emulate
• platform add
• platform ls (list)
• platform rm (remove)
• plugin add
• plugin ls (list)
• plugin (remove)
• prepare

I’ll be the first to admit to not knowing what “docs” does. I can’t seem to find it anywhere in the Cordova-CLI source, so I presume it is a placeholder for something related to documentation down the road.

A hook can be a Javascript or shell script. I won’t particularly say any one is better than the other: your needs and your platform will likely determine which one you should use. For any chance at cross-platform project compatibility, you should probably use Javascript.

However, my needs were simple: all I wanted to do was to copy a folder external to the project into the project’s www folder when a cordova prepare was executed. This would then permit that directory to filter on down to all the other platform-specific www directories.

So I just wrote a small script (it doesn’t matter what it’s named, really):

#!/bin/sh
cp -r ../framework ./www

Once created, be sure to give it executable permissions (chmod +x), or your script won’t work right.

There’s just one fly in the ointment: it doesn’t work unless you’re in the project’s root directory. This is because the directory I want to copy is a sibling to the project’s root, but the hook doesn’t get the project’s root directory, so there’s no (easy) way to create a hook that will work regardless of where you are in the project’s hiearchy.

Looking at recent commits to Cordova-CLI, it looks like this might be out in the next version.

Because of the issue, I put a notice in the script that says the hook will fail to work if the user isn’t in the project’s root. Of course, there’s nothing preventing the script from executing, but the cp will return an error because the passed directories will be wrong.

Now when I run cordova prepare, my external content is copied into my www directory, and since this is a before hook, it runs before cordova prepare actually does anything. This means that when cordova prepare actually does its work, it’ll then happily copy down the external content into the platform-specific subdirectories, ready for building, deploying, etc.

Now there’s a lot more you could do with hooks… but I’ll let you figure that out!

Merges

The merges directory that Cordova-CLI creates is an interesting one – it almost pulls you in as you just try and figure out a use for it!

Here’s one: use it for a platform-specifc index.html file.

Sometimes it is necessary to alter the index.html file according to the platform well in advance of your code being able to actually figure out the platform. Perhaps you want to statically include different scripts or styles, or even just different meta viewports.

And that’s just what I did. In the merges directory:

merges/
       ios/
           index.html
       android/
           index.html

Each file varies by only a line, and perhaps there’s a really nifty way of dealing with it after we could programatically determine the platform, but for me, it was easier this way. See, when I do a cordova prepare (or anything that calls it, like cordova compile) the index.html file from each platform in the merge directory will be copied to that platform’s respective code. So now the iOS project and the Android project have two very slightly different index.html files.

Note that when using cordova serve platform, the www used seems to be the project’s www, not the platform’s. This means you can’t serve anything from the merges folder.

But what about the main www directory? Turns out I still need an index.html file there, too, because it seems that cordova serve still serves from there, regardless of the platform. Because of this, though, we can get even more interesting: because it will be overwritten in the cordova prepare process, it can be totally different. In my case, I use this index.html file to make a couple changes to support running the project in Google Chrome. But also, in case I forget, I add a comment inside indicating that the file will be overwritten by those from the merges directory.

It seems that the behavior is the same when using cordova ripple. Thus you won’t see any merges content in the Ripple environment.

Now there’s a lot more you could do with this, but it is important to note that it only applies to the www directory.

So will you use the merges directory much? No, probably not. Nor should you, really. Only use it in those situations where there’s no other reasonably simple way and when you know what you’re doing, because you’re ultimately making the project more complicated. For example, if I ever add anything extra to my index.html file, I have to do it in three places now, not just once.

But for the index.html file, that’s a price I’m willing to pay, since each platform expects one, and the only way to get a different one per platform is to use this method or edit the project’s native code. I like this way better.

Could you accomplish something similar with hooks? Sure, why not? Think of this as a shortcut to having to write your own hook to accomplish it, but why not try to make a hook to do it as an exercise?

Cordova-CLI is doing some great things to make working with multiple platforms in one Cordova project easier. But installing with it can initially seem a little daunting if you’ve never played with it before, and so I thought it would help to write this guide up to help anyone else getting their feet wet.

Note: I’m a Mac OS X user. Therefore, I’ve only tested any of this on my Mac. It should translate to Linux fairly easily. Getting anything to work on Windows is probably going to be painful, given that Cordova-CLI indicates it has only been tested on Mac OS X and Linux.

Downloading and Installing node.js

The first thing you need to do is install node.js. This is available at http://nodejs.org/. You can download the Mac OS X package by clicking “Install”.

Once downloaded, double-click the package file, and step through the instructions. node.js will tell you that it is installing to /usr/local/bin and that your PATH will need to be updated to include this.

Updating your PATH

To update your path, you can simply navigate back to your home directory (~) and edit your .profile:

cd ~
vi .profile

Next, the following commands in your .profile will add /usr/local/bin to your path — be sure to add them at the end of your .profile.

# for NODE
PATH="${PATH}:/usr/local/bin"
export PATH

Before you do anything, be sure to close and restart your terminal session, or the PATH won’t be correct. Alternatively, source your .profile:

. ./.profile

Before installing Cordova-CLI

You need to be absolutely certain that you have access to your development tool’s command-line tools via the command line, or the install will error out later on.

You must have the latest version of each development environment installed, or things will most likely go very wrong.

Xcode (iOS)

Install Xcode Command Line Tools

Open up Xcode and then navigate to Xcode → Preferences…, then select the Downloads tab. If the Components section isn’t already selected, select that.

Now, near the bottom of the list, there should be a Command Line Tools option with an Install option if it hasn’t already been installed. Click Install to let it download and install.

Only proceed once the components have been fully installed. You may need to restart your terminal as well.

Agree to XCode’s License

Once you’ve got the command line components installed, the you must agree to the Xcode license agreement for all users of the computer.

Open terminal and type:

sudo xcodebuild -license

Enter your password when prompted. Then be sure to [space] through the license, and then type agree at the end.

Android

Download Most Recent Android SDK

If you don’t have an Android SDK installed, be sure to download the Android SDK from Google at http://developer.android.com/sdk/index.html.

Be sure you’ve got the most recent version of the Android SDK installed. If you’ve already got a version installed and in the PATH, you can type:

android

Alternatively, just open Eclipse and navigate to Window → Android SDK Manager.

If you have any updates, click the Install # packages… button, then click Accept All to accept all the license agreements, and then click Install.

Add Android Tools To Your PATH

Once again, navigate to your home directory (~) and edit your .profile:

cd ~
vi .profile

Then add this to the end of your .profile:

# for Android
PATH="${PATH}:/Path-To-Android-SDK/android-sdk-macosx/tools:/Path-To-Android-SDK/android-sdk-macosx/platform-tools"
export PATH

Be careful to replace Path-To-Android_SDK with the actual path to your Android SDK. On my Mac, this is under /Applications, but it may be in another spot on your machine.

Before you do anything more, be sure to close and restart your terminal session, or the PATH won’t be correct. Alternatively, source your .profile:

. ./.profile

Installing Cordova-CLI

The install instructions don’t warn you that you need to be root in order to install the package successfully. So, here’s the command I used:

sudo npm install -g cordova

When prompted, be sure to supply your user’s password, and then you should see output that looks like this:

npm http GET https://registry.npmjs.org/cordova
npm http 304 https://registry.npmjs.org/cordova
npm http GET https://registry.npmjs.org/colors
npm http GET https://registry.npmjs.org/elementtree/0.1.3
npm http GET https://registry.npmjs.org/xcode/0.5.1
…

If the install hangs, like mine did, just break the process (CTRL-C), and re-run the installation command.

The final output should look something like this:

SUCCESS: Minimum requirements for blackberry met.
BOOTSTRAPPING blackberry...
SUCCESS: Minimum requirements for ios met.
BOOTSTRAPPING ios...
SUCCESS: ios ready to rock!
SUCCESS: blackberry ready to rock!
SUCCESS: Minimum requirements for android met.
BOOTSTRAPPING android...
SUCCESS: android ready to rock!
**************************************************************************
* WARNING: YOU ARE INSTALLING GLOBALLY INTO A ROOT-ONLY DIRECTORY!!!1one *
* Your node install is global, so global modules get installed there too.*
* You should probably run the following command for this tool to run:    *
    $ sudo chown -R your-user /usr/local/lib/node_modules/cordova
* This will allow you to run this tool globally without using `sudo`.    *
**************************************************************************
cordova@2.5.5 /usr/local/lib/node_modules/cordova
├── ncallbacks@1.0.0
├── colors@0.6.0-1
├── semver@1.1.0
├── shelljs@0.1.2
├── request@2.11.4
├── elementtree@0.1.3 (sax@0.3.5)
├── xcode@0.5.1 (node-uuid@1.3.3, pegjs@0.6.2)
├── prompt@0.2.7 (revalidator@0.1.5, pkginfo@0.3.0, read@1.0.4, utile@0.1.7, winston@0.6.2)
├── express@3.0.6 (methods@0.0.1, fresh@0.1.0, range-parser@0.0.4, cookie-signature@0.0.1, buffer-crc32@0.1.1, cookie@0.0.5, debug@0.7.2, commander@0.6.1, mkdirp@0.3.3, send@0.1.0, connect@2.7.2)
├── plugman@0.5.6 (osenv@0.0.3, bplist-parser@0.0.4, xcode@0.4.2, nopt@1.0.10, glob@3.0.1)
└── plist@0.4.0 (xmlbuilder@0.4.2, xmldom@0.1.13)

If, at any point you see notices that the minimum requirements aren’t met for a particular platform, be sure that you’ve downloaded the most recent version, agreed to any license agreement, and have the correct paths in PATH. You can re-run the installation command any number of times to repeat the process until you have all the minimum requirements met.

If you don’t intend to develop for a specific platform, you don’t need to worry if the install process complains that the minimum requirements aren’t met.

Finally, notice that big warning block in the output? This indicates that since node.js has been installed globally for all users, it currently has permissions that would require that you sudo in order to execute any commands.

Therefore, execute the command as shown in order to make the command friendlier to use:

sudo chown -R your-user /usr/local/lib/node_modules/cordova

Installing iOS Simulator Support

If you intend on using the iOS Simulator from the command line, you aren’t done yet. You need to instal ios-sim first, most easily accomplished using homebrew.

Installing homebrew

You can learn more about homebrew at http://mxcl.github.com/homebrew/, but essentially it requests that you use the following command:

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

Let me first say how absolutely I abhor this method of installation. Therefore, be absolutely certain you trust the content of the file being downloaded and then executed before you run this command. I looked at it, and it looks safe enough to me, but you are expected to verify that it will be safe for you. If it turns out that it isn’t, not my fault. Sorry.

It will display a list of things it will do to your system, and then prompts you to press [ENTER] when ready. (Or, press any other key to exit.)

==> This script will install:
/usr/local/bin/brew
… 
==> The following directories will be made group writable:
/usr/local/.
/usr/local/bin
… 
==> The following directories will have their group set to admin:
/usr/local/.
/usr/local/bin
/usr/local/include
… 
Press ENTER to continue or any other key to abort

When it starts to do real work, it will prompt you for your sudo password (assuming the previous sudo attempts have timed out).

You should have output similar to this:

==> /usr/bin/sudo /bin/chmod g+rwx /usr/local/. /usr/local/bin /usr/local/include /usr/local/lib /usr/local/share /usr/local/share/locale /usr/local/share/man /usr/local/share/man/man1 /usr/local/share/man/man5
==> /usr/bin/sudo /usr/bin/chgrp admin /usr/local/. /usr/local/bin /usr/local/include /usr/local/lib /usr/local/share /usr/local/share/locale /usr/local/share/man /usr/local/share/man/man1 /usr/local/share/man/man5
==> Downloading and Installing Homebrew...
remote: Counting objects: 105377, done.
remote: Compressing objects: 100% (44209/44209), done.
remote: Total 105377 (delta 74733), reused 88054 (delta 60267)
Receiving objects: 100% (105377/105377), 15.76 MiB | 229 KiB/s, done.
Resolving deltas: 100% (74733/74733), done.
From https://github.com/mxcl/homebrew
 * [new branch]      master     -> origin/master
HEAD is now at b412fe3 exiftool 9.24
Warning: Install the "Command Line Tools for Xcode": http://connect.apple.com
==> Installation successful!
You should run `brew doctor' *before* you install anything.
Now type: brew help

I’ll be honest as to not knowing why it insists I don’t have Command Line Tools installed — I do.

Next, run brew doctor as it suggests. You’ll receive some warnings (I got plenty), but it is up to you to decide if they are worth fixing or not.

Installing ios-sim

Next, we can install ios-sim

brew install ios-sim

You’ll see output like this:

==> Downloading https://github.com/phonegap/ios-sim/tarball/1.6
######################################################################## 100.0%
==> /System/Library/Frameworks/Ruby.framework/Versions/1.8/usr/bin/rake install prefix=/usr/local/Cellar/ios-sim/1.6
   /usr/local/Cellar/ios-sim/1.6: 4 files, 96K, built in 5 seconds

If you run this and you see a mug of beer, yes – that’s normal.

Creating Your First Project

You should now be able to create the project by issuing the following at the command prompt:

cordova create path-to-project/ reverse.domain.name project-name

For example, you might use something like this:

cordova create ./exampleApp demo.example.com exampleApp

After this, you’ll have a directory structure that looks like this:

exampleApp/
    .cordova/
    merges/
    platforms/
    plugins/
    www/
        index.html
        … 

Adding Platforms to your Project

Without any target platforms, the project won’t be going anywhere. Let’s add some:

cd exampleApp
cordova platform add ios android

Now, the directory structure looks like this:

exampleApp/
    .cordova/
    merges/
    platforms/
        ios/
        android/
    plugins/
    www/
        index.html
        … 

Listing Project-supported Platforms

If you ever in the future want to know what platforms a project supports, you can execute cordova platform list:

cordova platform list

The output will be something like this:

[ 'android', 'ios' ]

Removing a Platform

Perhaps you’ve decided to remove a platform from the project. You can remove it very easily:

cordova platform remove android

After which a cordova platform list returns (for our example):

[ 'ios' ]

Compiling a Project

There are several ways you can compile a project.

• use cordova prepare and then cordova compile
• use cordova prepare from the command line, and then use your IDE
• use cordova build from the command line

If you’re working solely from the command line, the latter is probably the easiest method. If, however, you like to use your IDE for building, deployment, and testing, you could always use the second option.

If you only want to compile for one platform (instead of all of them), you can specify the list of platforms, like so:

cordova build ios android

The first and third options above are the same thing. The latter simply does both steps for you.

Emulating a Project

To emulate a project in your platform’s emulator, you can use:

cordova emulate [platform…]

If you don’t specify any platform, you’ll end up emulating the project on every emulator the project is valid for. While this is sometimes the goal, I often test on one platform first, and then move on to the other. So you’ll almost certainly want to specify a single platform:

cordova emulate android

Note: there’s no prompt as to which device you’re going to emulate. You’ll need to have specified that in advance using the appropriate tool in your SDK.

Now, if you try to emulate an iOS device without installing ios-sim, you’ll hit a roadblock:

[Error: An error occurred while emulating/deploying the ios project.Error: ios-sim was not found. Please download, build and install version 1.4 or greater from https://github.com/phonegap/ios-sim into your path. Or "brew install ios-sim" using homebrew: http://mxcl.github.com/homebrew/
]

Why Cordova-CLI doesn’t do this (or prompt to do this) or even warn you at install time is beyond me. Rather it creates a rather rude interruption in your workflow that you have to overcome in order to just test on iOS. Now you know why we installed it ahead of time. But, if like me, you get caught by this error, look above at the section entitled “Installing iOS Simulator Support” and follow the instructions before repeating the emulator command.

Testing using a Webkit Browser

If your app doesn’t rely on any of the Phonegap APIs or use any plugins, you can test the app using a Webkit browser such as Chrome or Safari.

cordova serve platform [port]

Here you must specify a platform (like iOS), so if you’ve made changes to the global www directory, you’ll need to, at a minimum, cordova prepare the platform in question, or you’ll see out-dated content.

The port is optional; it will default to 8000 on its own.

Once started, you’ll see this output:

{}
Static file server running at
  => http://localhost:8000/
CTRL + C to shutdown

Now you can navigate to http://localhost:8000 from your machine, or do the same from any other device (substituting localhost with the proper hostname of your development machine).

Keep in mind that this in no way provides a PhoneGap API or emulation to the project. So even if you access the content from your iPhone, you’ll find that it behaves no better than it would in a browser on your machine. That said, it’s still useful for testing rendering without doing a full deploy on your devices.

When done, you can kill the server using CTRL+C.

Only use cordova serve on development machines behind a firewall. The web server used in this context is not intended to be used in production.

Update your config.xml file

Before you go much further, you’re going to want to check and update your config.xml file. It was created when you used cordova create, and it contains all sorts of properties you’ll need to double-check and change.

The file itself will be in project-directory/www/config.xml and you can edit it using any editor that understands plain text or XML.

You’ll almost certainly want to update the description and author sections to your liking, but you’ll also eventually need to deal with the other properties as well. You can see more about these on PhoneGap’s Documentation Site. You’ll also eventually need to adjust the whitelisting property as well, though by default it allows any external reference.

More, so much more…

There’s far more to Cordova-CLI than what I’ve gone over here. You’ll note that I’ve not covered plugins at all, though I will write an article at some point in the future. In the meantime, if you want the syntax for dealing with plugins, I’ve included it below:

cordova plugin list                -- lists all the plugins in the project
cordova plugin add path-to-plugin… -- adds one or more plugins to the project
cordova plugin remove plugin-name… -- removes one or more plugins from the project.

There are also hooks you can add for each command if you need to integrate your own build system or somehow need them for integrating with your version control system. Regardless, they are beyond the scope of this article.

Comments, thoughts, corrections? Post them below, or feel free to reach out to me via my website or my handle on Twitter or ADN (@photokandy). I’m also pretty active on the Google Group for Phonegap.

Edits

• March 27, 2013 - Tumblr dropped some inline links. Fixed a couple of spelling errors. Thanks to @Steve in the comments!

Quick shot of what just went in for the 1.2 beta of the Greek Interlinear Bible: http://grab.by/kjTe.

3 changes in there: Strong’s indexes can be on top (optional); smaller non-greek text; and no “G” in front of the indexes. 

Should submit next week.

Seriously?

Is there an echo in the Apple App Store?

It’s happened again, for the third time. The app, Greek Interlinear Bible, has been infringed on again by an app called “Bible : The Greek Interlinear Bible” by a developer called “Teddy Jackson”. Here’s a screenshot: http://grab.by/jW86

Guess what, even though the name is different, it’s the same developer who infringed the app the first time not so long ago. His response then was that he wouldn’t upload the app again. Well, clearly an F in telling the truth.

As always, I’ve contacted Apple, and requested the app to be removed. Since he used virtually the same code he used the last time, I can prove to Apple that these two accounts, at least, are linked. Maybe that will get them to nuke his entire operation. Or maybe it won’t. If it doesn’t, I’ll be a bit more disappointed in Apple, and it will be clear that they’re not really serious about preventing copyright infringement. Wasn’t this supposed to be one of the benefits of a walled garden?

Now, for some of the juicier bits. I downloaded the app - had to, really, just to be sure. And guess what? Here’s what I found:

• It’s virtually identical to the first version. (It may be identical, for all that matters, except for some of the configuration stuff.) He even re-used the icon from the previous infringement.
• This means it is using unfinished code in between version 1.0 and version 1.1. That’s not at all good for anyone who manages to come across the app and try to use it. For those users: sorry.
• Again, he’s removed attribution everywhere in the user-facing portion of the app, and even introduced his own support view. 
• And guess what — in the “about.html” page, I’ve got a copyright light. It wasn’t simply removed, it was commented out. So was part of one of the Biblical text attributions.
• The assets are again, unchanged beyond the icon. The license so doesn’t cover those. Clearly he’s going off the last available source that didn’t remove these assets, since they are no longer available in the current repository.
• The last version of the infringement had an Ad-supported copy. This one doesn’t. Interesting. 
• Like last time, he’s reused the marketing content on the App Store. Couldn’t be bothered to come up with a new description, eh?
• The last time I reported this dev’s infringement was January 3rd. It’s now February 15th. Did this dev seriously think I would stop looking? Really? I’m just a little bit insulted.
• Oh, and does one never look at the purchase price of the app being infringed? Seriously? Our app is currently $1.99. His app? $4.99.
• Oh, three times infringed? I guess to some degree I should feel flattered. But seriously, people, if you’re going to copy and infringe an app, copy one that’s neither a niche product nor a successful product. Our app is never going to be #1 on iTunes, simply because it is a very niche product. But because it is so niche, it’s easy to spot infringement. I guess it goes to show how little thought this developer is putting into their infringement. 

In all the excitement, I totally forgot to mention that Apple finally got hold of the dev infringing my app, and they took it down. This would have been late Monday. 

So, thanks to Apple! The dev, on the other hand, didn’t even bother to apologize — just said “The app has been removed”. **Thanks** Next time, don’t infringe in the first place. Or, even better, use the code within the bounds of the license. Or best, contribute back to the app — it’s on Github for a reason!

Oh well. It’s done for now, until the next person tries it again. I suppose it’s only a matter of time until someone else thinks they can get away with it. What’s frustrating is that there’s no way to really prevent this in the future. Sure I could close the source down, but one can still unpack the IPA, dig around in the internals and do the work to create a new app out of that. At least I’m pretty sure that’s possible. Why isn’t Apple encrypting the IPA itself?

ANYway. On to the upcoming 1.2 release. There’s a lot of great features that I think you’ll love, and I can’t wait to drop them. Look for it around the end of the month.

It’s happened again. My app, Greek Interlinear Bible, has been copied by another person and posted on the Apple App Store. This time it’s under the name of “bible [Greek and English] and “bible HD [Greek and English]” The author is duduBear. 

This time the app looks to be a version of the app at the 1.0 stage, with some very notable bugs. The infringer didn’t even bother changing the copyright notices, which, I suppose throws one part of the license out (the part requiring attribution).

That said, he’s charging for the apps, and he’s made the app non-universal. This is clearly an infringement on the license.

Furthermore, the developer hasn’t even bothered updating the assets in any way — including the app’s icon, slash screen, or icons. Many of the icons are third-party icons, and not licensed to this developer. Therefore another count of infringement

*Sigh* — those of us who put our code online should not need to worry about unscrupulous developers such as Wang Ting and duduBear. 

I’ve sent Apple the appropriate DMCA notice. I would have contacted the developer as well, but get this — there is no contact information on the store. Period. No email, no website, no support site, etc.

He’s got several other apps available — I’ll be doing some searching to see if I can find the original owners. Maybe we can get this guy off the store for good.

I’ll send an update when Apple removes the apps.

My app, Greek Interlinear Bible v1.1, has passed Apple review, and should be live in the App Store soon. For more information, see http://www.photokandy.com/apps/gib. (For the curious, review time was 6 days.)