How to use Ripple Emulator for Windows to test PhoneGap application?

Question 1

tl;dr: On contrary to what is said in PGB's docs, you must keep a copy of cordova.js file in your app's root directory and this file must be taken from exactly version 2.0 of PhoneGap, as latest version of Ripple Emulator does not work neither with other version nor without this file.

Solution

I'm developing my PhoneGap apps using PhoneGap Build, not local PhoneGap environment. So -- as I was instructed -- I have deleted phonegap.js file from my application's webroot and only left reference to it in index.html. This is fine for PhoneGap Build, but absolutely not fine for Ripple Emulator.

Ever since I put that file back (actually cordova.js from lib\android\example\assets\www\ folder from phonegap-2.0.0.zip I managed to see license, start Ripple Services and test working PhoneGap application locally.

Notice for people struggling with similar problem: Current version of Ripple Emulator uses Cordova 2.0. Make sure, that you download right version of PhoneGap and take cordova.js from it! Do not attempt to use cordova.js from newer version (currently 3.0.0) as you may run into undetectable situations, including seeing many strange alert()'s and even hanging up overloaded Chrome.

Always make sure, that you're using PhoneGap's JS file version, that maches the one behind Ripple.

Step by step

Key steps to be able to test PhoneGap application under Windows, using Chrome and Ripple Emulator:

Put cordova.js file back to your folder root and check the reference to it. You can grab it from lib\android\example\assets\www\ folder from any downloadable version of PhoneGap (you should use phonegap-2.0.0.zip though, see above).
Install Ripple Emulator extension for your Chrome browser, using Chrome Store. Enable it.
Start your local webserver and run your HTML code of your mobile application through it (testing through direct file access is mainly possible in Ripple Emulator, but highly not advisable and may produce unpredictable results).
Click Ripple Emulator icon, right to your Chrome omnibar and then click Enable (or select proper option from context menu, right-clicking page).
Accept license agreement and select proper platform (Cordova 2.0.0).
Click Ripple Emulator icon again and click Start Ripple Services if they're not started automatically.
Set destination platform (device) and enjoy working PhoneGap application locally.

Version and API differences

You also have to keep your eye for PhoneGap API and carefully check, what was available and how it was accessible in PhoneGap 2.0.0? For example, simple connection type checking has changed ever since that. In 2.9.0 API it is done via navigator.connection, while in 2.0.0 API it was accessed under the navigator.network interface.

Since Ripple Emulator uses PhoneGap 2.0.0, currently supported way of calling this object:

var networkState = navigator.connection.type;

will fail. You'll have to use it this way:

var networkState = navigator.network.connection.type;

Though you can select PhoneGap version, when compiling in PhoneGap Build (and you can force it to use version 2.0.0, though compile this code in an unchanged way), you will most likey want to develop your application using newest version of PhoneGap.

In this case, you have to use a "secured" approach, that will work in both Ripple and PhoneGap:

var networkState = ((navigator.connection) ? navigator.connection.type : ((navigator.network && navigator.network.connection) ? navigator.network.connection.type : 'unknown'));

Or you can declare some special variable:

var debugMode = typeof(window.tinyHippos) !== 'undefined';

And use it as a switch:

var networkState = (debugMode) ? navigator.network.connection.type : navigator.connection.type;

Hopefully, Ripple will be updated soon to newest PhoneGap so we could drop such things away.

Question 2

Ripple should work with the latest versions of Phonegap, although you may get a few spurious error messages that popup during the page loading which are due to Ripple not quite being up-to-date with the latest Phonegap versions. Make sure you've included the Phonegap JS into your page. Try the following example - it works fine for me in Ripple:

<html>
    <head>
        <script type="text/javascript" charset="utf-8" src="cordova-2.8.0.js"></script>
        <script type="text/javascript">
        function deviceready() {
            console.log("Device ready");
            navigator.compass.watchHeading(function(heading){
                document.getElementById("heading").innerHTML = heading.trueHeading;
            },function(error){
                var errorType;
                switch(error.code){
                    case CompassError.COMPASS_NOT_SUPPORTED:
                        errorType = "Compass not supported";
                        break;
                    case CompassError.COMPASS_INTERNAL_ERR:
                        errorType = "Compass internal error";
                        break;
                    default:
                        errorType = "Unknown compass error";
                }
                document.getElementById("heading").innerHTML = errorType;
            });
        }
        document.addEventListener("deviceready", deviceready, true);
        </script>
    </head>
    <body>
        <h1>Test</h1>
        <p>Heading: <span id="heading"></span></p>
    </body>
</html>