Purpose of Staging folder in PhoneGap 3.4? Only changes to index.html in this folder get recognized?

Question

We noticed a Staging folder that appears in Xcode's Project Navigator after creating a project with PhoneGap 3.4. This Staging folder didn't appear when creating projects with PhoneGap 3.2 or lower. The PhoneGap docs are terrible, and we can't locate the explanation for why this folder exists.

More importantly, it seems like the normal index.html file isn't recognized anymore, and only changes to index.html inside the Staging folder get recognized. Why is this?

Answer 1

I just stumbled over it too and found no explanation. I have just been puzzling around.

Short conclusion:

The "staging" folder contains those www assets that are distributed into an iOS app bundle. The staging folder is completely overwritten with files from the folders my_cordova_project/www/ (common www code for all platforms) and my_cordova_project/merges/ios/ (specific www code for Xcode project). The contents in these two are to be edited. The contents of my_cordova_project/www/ remain the same over all platforms, which is organized by the cordova build command. As of Cordova 3.3, it seems the Xcode build for ... command is not sufficient for the whole process, you also need to invoke the cordova build command in order to synchronze all folders properly.

Long answer:

The folder:
  my_cordova_project/platforms/ios/www/
is "mapped" in Xcode to
  /my_xcode_project/staging/www/

You can check this by altering a file name temporarily with Finder and observe the tree in Xcode.

The folder:
  my_cordova_project/www/
is "mapped" in Xcode to
  /my_xcode_project/www/

Then consider Cordova's merges concept that allows to distribute specific www documents for specific platforms (see here). This happens by putting them into the folder my_cordova_project/merges/ and using the command line cordova build command. It seems that cordova build is not only meant to create the app the first time. If you start a build and observe the trees in Xcode, you will see that the /my_xcode_project/staging/ folder is completely overwritten by my_cordova_project/www/ (and specialized by the merges folder).

This especially matches with this cite from here:

WARNING: When using the CLI to build your application, you should not edit any files in the /platforms/ directory unless you know what you are doing, or if documentation specifies otherwise. The files in this directory are routinely overwritten when preparing applications for building, or when plugins are reinstalled.

When I worked with early versions of PhoneGap, the www content was stored and edited in each platform project, so you had to copy the www from one platform to another. Today, there is just one www folder that is automatically distributed over all platforms by cordova build. It's very handy, and it can be adjusted for specific platforms by the merges folder.

So, the impact of a cordova build may be observed in Eclipse ADT as well, and even crossover. Just change something in Xcode in /my_xcode_project/www/, run cordova build, refresh the tree in Eclipse ADT and you will find your change distributed.

On the other hand, it is a bit puzzling that Xcode's build for running command does not copy all /my_xcode_project/www/ into /my_xcode_project/staging/www/. This is done only by the cordova build command. Yet if you inspect a produced app, you will find the files from /my_xcode_project/staging/www/, so if you edit /my_xcode_project/www/, you have to invoke cordova build too.