Cross-Platform PhoneGap (aka Cordova) Project Templates in a Jiffy!

October 4, 2012By 24 Comments

Often times half the battle to getting started with cross platform development is getting set up. I’ve blogged about this often times before, but now there’s a helpful new tool available from our Adobe engineers to help you set up a cross-platform project template quickly! The tool is called cordova-client, and it allows you to edit one code base and maintain and manage your overall cross-platform development project with almost no setup hassle or IDE (Eclipse/XCode) overhead. It’s run from the command line and takes advantage of the underlying Cordova command line interface recently released. It’s basically a set of scripts that do all the hassle work for you and keep the code base consistent by copying your latest source into the different supported platforms at build time.

It’s very easy to set up and use and this post is intended to help you get started with it right away. I was very excited when I saw this demo’d at PhoneGap Day in Portland recently because I have also felt like developers needed something like this to help them become uber productive in their mobile development, so please read on. The setup can take 10 minutes or less depending on what you already have installed from the pre-requisities, but please see the main github site for the requirements and installation instructions and install before continuing.

Important Note
Be sure to have your android-sdks/tools and android-sdk/platform-tools set on your system path to be accessed globally before running the cordova commands for android, the cordova scripts require access to those tools.

Create/Debug and Launch a Cross-Platform Project

  1. Create a new project by entering the following command in the terminal window starting in the directory where you want to create the new project:

    cordova create MyCordovaProject org.devgirl.my-cordova-app MyCordovaApp

    In my terminal window, it looks like this (starting after the hollyschinsky$):

    Creates a folder named MyCordovaProject in the current directory with an application name of MyCordovaApp and package of org.devgirl.my-cordova-app (also the bundle identifier for iOS).

  2. cd into the new project folder (MyCordovaProject in this case) and list the contents. It should show the following:

  3. Note: Currently the platforms and plugins folders are empty because we haven’t specified that any be added yet. The default www folder however contains a basic PhoneGap application architecture preset for you (includes js, css, img folders etc and includes the links to them from index.html. Note that it also includes config.xml for PhoneGap Build use). It’s important to note that this is the folder where you will be developing. It will be copied down into the different platforms to be used when you build and launch your application so the latest is used.

    Note:
    If you’re not familiar with PhoneGap/Cordova enough to know what this www folder means, it’s basically the path to the index.html and associated source code and assets for all PhoneGap/Cordova projects. If you think about the overall architecture with PhoneGap and how it needs to work with different platforms, it will make more sense to understand there needs to be an entry point to bootstrap into the index.html. The www folder was the chosen way to ensure the consistency across platforms. For the super-curious (or geeky – you choose ;)), the following is the code that is used to bootstrap from iOS (AppDelegate.m) and Android (MyCordovaAppActivity.java) to PhoneGap respectively:

    iOS Native Hook

    self.viewController.wwwFolderName = @"www";
    self.viewController.startPage = @"index.html";
    

    Android Native Hook

    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        super.loadUrl("file:///android_asset/www/index.html");
    }
    
  4. Add your desired platforms. Here I am adding ios then going into the platforms folder to show that it has been added, then back out and adding android and showing how that exists after the command is run:

    cordova platform add ios

    cordova platform add android

  5. Now you have a basic application scaffolding in place where you could build and run on all platforms added to see a default cordova project in action. If one of your platforms include android, you’ll need to first either connect an actual android device or start up an android virtual device you’ve previously created by navigating to MyCordovaProject/platforms/android and typing cordova/emulate. (Note: if you don’t have an android virtual device setup or your own to test with, you can create one using the android tool that comes with the required SDK in the pre-req’s for this tool. For more details, see this link).

    Nothing needs to be done before building and emulating for XCode, except for of course to have XCode (version 4.x). I have not tested with BlackBerry yet so I cannot say for that platform.

    Navigate to your project’s platforms folder and type the following:

    cordova build && cordova emulate:

    The result should be an app that looks like the following screenshot:

    Note: on Android you *may* see the application get installed but not run immediately and have to click to start it. Look for the name of it in your applications with a logo that looks like the above.

  6. Now you could go back into the ../MyCordovaProject/www folder that I talked about being the base above and make desired code changes, and simply go back and repeat step 5 to see your changes cross-platform! I suggest trying this quickly by making a simple change to the index.html and rerunning cordova build && cordova emulate from within the platforms folder to see how easy it is.

Additional Notes

  • If you’re perusing the generated code, you may notice there’s a cordova subfolder created under each of the platforms (../android/cordova, ..ios/cordova etc). Those are created as part of the PhoneGap/Cordova command line interface that this tool basically wraps. So the subfolder cordova scripts are intended to do a debug or emulation for just that one particular platform whereas the cordova-client commands covered above (build, emulate) are intended to work at the project level to cover all platforms.
  • The cordova-client create command can also be run with just a folder name and will default the name to Hello Cordova and package to io.cordova.hello-cordova, but since the extra parameters to name it yourself aren’t much hassle, I showed that as an example above. I also think it helps to understand better what was generated from the scripts based on knowing what exactly you entered. Also, there’s currently a bug in this step where the generated **.app file is built is named Hello Cordova.app so you need to rename it to Hello_Cordova.app (with the underscore) before you run the emulate command or it will not find it.
  • If you want to get to the files that resulted from a build (the .apk or .app) you can find them in the following paths:
    ../MyCordovaProject/platforms/android/bin
    ../MyCordovaProject/platforms/ios/build
  • If you’re curious exactly where cordova is installed, the node package manager (npm) installs on Mac OS to a path of /usr/local/lib/node_modules/cordova. If you end up with any errors about a cordova-2.0.1.jar file missing there during the process, check that folder and if it’s missing, copy it from your {phonegap 2.0.1-path}/lib/android folder to /usr/local/lib/node_modules/cordova/lib/android/framework/cordova-2.1.0.jar.

Filed in: CordovaHTML/JSMobile DevelopmentPhoneGap Tags:

About the Author ()

Comments (24)

Trackback URL | Comments RSS Feed

  1. julio says:

    I’ve got this error “TypeError: undefined is not a function]” but I don’t say why.
    Can you help me please?

    Thanks

  2. First off – big thanks to Holly here. I had played with the – I don’t know, “main” CLI stuff before, but not this version of it. (Hopefully that makes sense.) While the CLI stuff I saw before was nice, this REALLY adds some kick butt stuff on top of it. Here are some issues I want to point out in case others run into it.

    a) You will most likely want to run this command on your install: (This note is credit Filip Maj of Adobe)

    -**NOTE**: on Mac OS X, you may want to change the owner of the cordova directory that npm installs to. This will allow you to run cordova as local user without requiring root permissions. Assuming your node_modules directory is in `/usr/local/lib/`, you can do this by running: `sudo chown -R /usr/local/lib/node_modules/cordova`

    I ran into many issues that all went away when I did this.

    b) Holly mentioned added the 2 Android paths to your install. I ignored it. I paid the price. What’s odd is that you will get – seemingly – no response from the command line. Be sure to do this.

    c) For Android, when I ran emulate, it didn’t run the app. The CLI stuff was smart enough to _kill_ the app if running, but not rerun it. Just keep it in mind.

  3. Clemenza says:

    Working on Windows 7, I get stuck at “cordova platform add android” which returns [RangeError: Maximum call stack size exceeded].

  4. I want to leave another tip. Since this process skips XCode, you may be wondering if it is possible to see console.log messages. Turns out you can – this tip at StackOverflow (http://stackoverflow.com/questions/10165641/ios-simulator-console) worked perfectly. The only thing that would possibly make this nicer is if you could filter out the tail on things that match [INFO], but for now, it’s manageable.

  5. Actually – I stand corrected. While watching that log, I saw this:

    stdoutPath: /Users/ray/Dropbox/mobile/examples/mp3viewer/platforms/ios/cordova/console.log

    And I checked – and yep – that is a log just for the app. So I’d still recommend tail -f, but use that one instead.

  6. As just an FYI, oddly, any console messages before deviceready will not be logged. That kinda makes sense I guess. Just don’t forget it.

  7. julio says:

    Hi!
    When I’ve have TypeError: undefined is not a function], file console.log is delete and in /var/log/system.log I just see the command-line I execute that is to say “sudo cordova platform add ios”.

    I don’t know I do

  8. Fil Maj says:

    Hey guys, thanks for reporting the erros! I am working on fixes!

    If you find any more please submit it to GitHub: http://github.com/filmaj/cordova-client

    I’ve just pushed 0.1.1 to npm to address the “undefined is not a function” error some were seeing.

    Am taking all of these issues you guys are seeing and making sure they are addressed _somewhere_ in the pipeline, either in this tool itself, or in the underlying CLI scripts for Cordova.

  9. julio says:

    Someone have a bug when you try to execute ./debug in a ios project ?

  10. tilovi says:

    Thanks for great post :)

    the command cordova platform add android failed with error: [Error: An error occured during creation of android sub-project. /usr/lib/node_modules/cordova/lib/android
    An error occured. Deleting project...
    ]

    After some digging I found the create script is looking for commons-codec-1.7.jar in the $BUILD_PATH”/framework/libs/ folder.
    It could not find it and it tries to wget it, and extract it in that location.

    My quick fix was to copy that file manually into that directory

  11. arunkumar says:

    I have position fixed problem on blackberry application……. what i do now?…
    Pls guide me…..

  12. Mal says:

    Hi,

    im quiet new to the mobile development, but i got all running for now ;) but i still got some question among the development process.

    i got this toplevel folder www wich i guess is the codebase. What i wanne is change the codebase with xcode.. but the projectfile for xbase is just for the plattform specific ios part not the base.. is there a common way to do that. My next and last question is about apache-incubator project.. is this similar to this just the offical release ?

    thx hope someone will still look at this thread.

    thx for all your work Mal

  13. Mal says:

    Hi again,

    the first question i found out by myself figuring out that for the andorid version its not enough use just “cordova build && cordova emulate” its also necessary run the an seperate ant build.

    Is there any possibility to add the windowsphone platform ?

    thx Mal

Leave a Reply