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

October 4, 2012By Holly Schinsky24 Comments

spacer 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$):
    spacer

    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:

    spacer

  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.

    spacer

    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

    spacer

    cordova platform add android

    spacer

  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:

    spacer

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

    spacer

    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: Cordova • HTML/JS • Mobile Development • PhoneGap Tags: cordova • cordova template • cross platform mobile • cross platform mobile development • Mobile Development • phonegap • phonegap template

spacer

About the Author (Author Profile)

Comments (24)

Trackback URL | Comments RSS Feed

Sites That Link to this Post

  1. Tutorial: Apple Push Notifications with PhoneGap – Part 1 | Devgirls Weblog | October 19, 2012
  1. spacer julio says:
    October 4, 2012 at 1:22 pm

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

    Thanks

    Reply
    • spacer Holly Schinsky says:
      October 4, 2012 at 1:44 pm

      Hi there, at what point are you getting this error? Can you give me some more information? Thanks in advance! Holly

      Reply
      • spacer julio says:
        October 4, 2012 at 2:12 pm

        Oh sorry I forgot spacer
        I’ve got this error when I run this command :
        “cordova platform add ios” (same error if run to root user et user )

        Reply
        • spacer julio says:
          October 4, 2012 at 2:16 pm

          My directory /usr/local/lib/node_modules/cordova/ have the good permission (julio:staff cordova). I don’t know if I change the group permission can solve the problem

          Reply
        • spacer Raymond Camden says:
          October 4, 2012 at 2:16 pm

          Julio, I get that too. I’ve reported the bug on Github.

          Reply
          • spacer julio says:
            October 4, 2012 at 2:28 pm

            okay

          • spacer julio says:
            October 4, 2012 at 2:39 pm

            What github url are you use to fork this problem ?
            Thanx

          • spacer Raymond Camden says:
            October 4, 2012 at 2:45 pm

            https://github.com/filmaj/cordova-client/issues

  2. spacer Raymond Camden says:
    October 4, 2012 at 2:04 pm

    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.

    Reply
  3. spacer Clemenza says:
    October 5, 2012 at 5:01 am

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

    Reply
  4. spacer Raymond Camden says:
    October 5, 2012 at 9:15 am

    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 (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.

    Reply
  5. spacer Raymond Camden says:
    October 5, 2012 at 9:27 am

    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.

    Reply
  6. spacer Raymond Camden says:
    October 5, 2012 at 9:42 am

    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.

    Reply
  7. spacer julio says:
    October 5, 2012 at 9:58 am

    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

    Reply
  8. spacer Fil Maj says:
    October 5, 2012 at 11:30 am

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

    If you find any more please submit it to GitHub: 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.

    Reply
  9. spacer julio says:
    October 5, 2012 at 11:59 am
Related searches:
cordova october platform phonegap folder
gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.