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 appe

Answer 1

The contents of "Staging" folder actually goes into execution on your device.

myAwesomeProject/www ---copy---> Staging/www

Cordova's build command copies contents from your "myAwesomeProject/www" folder to the "Staging/www" folder. The commands are:

sudo cordova build ios  //ios build
sudo cordova build android //android build

Caution! Remember that the build command not only copies the contents to the "Staging" folder but also build the whole app including native ios/android code. So, it will take long. For minor changes I usually copy the changed files to the "Staging" folder manually and build and run the app using XCODE incase of iOS.

Answer 2

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.

Answer 3

You should sudo cordova build after making any changes, before you build/run in XCode.

This will cause Cordova to update the /staging folder with a "staged" (i.e. assembled for production) version of your assets that has some Cordova magic like device-specific plugins. Compare /staging to /www and you'll notice some additional files in the former.

Answer 4

I've been encountering the same situation. In my environment, myProject/www/ directory is NOT copied to myProject/Staging/www/ directory. So, I'm directly editing files in Staging/www/ directory.