In Android, when the screen orientation changes, the current activity is destroyed and re-created. One way to preserve state data between instances is to override onSaveInstanceState and access the properties that are stored into the Bundle in the onCreate override.
When writing a PhoneGap-based app, does the base of the main activity, com.phonegap.DroidGap, automatically take care of saving the state of the web view?
What does an Android web app need to do to save its instance state for the next instantiation of the activity?
Is a callback made available to the JS engine which signals that the screen orientation was changed?
Having a look at the DroidGap source I can't see any handling as per what you describe in your question. Orientation changes in the a WebView in more recent versions of the Android fire an onorientationchange change event at the window level. Some of the older browser implementations don't support this event though so you are left to handle things by capturing the onresize event. You are best detecting what you have available through feature level detection.
In the source code (which you can download from the Apress site) I wrote some code which shows an example on how to deal with this. Content is covered in chapter 2.
If you don't want to download the full zip, then you can also have a look at the code on github:
So essentially you capture the orientation changes at the web level with no need for any notifications to be passed through from PhoneGap. This is good as it means your code will work in both a hosted and "native wrapped" app situation.
With regards to the second part of the question (saving instance state) my approach is generally to "serialize as I go". Basically, if I expect that something should be available and remain in the same state if the application was loaded from scratch then I will write a value using HTML5 localStorage (actually, I tend to serialize all my settings together as JSON first and write and read the whole lot together). I then look for these settings (or other state variables) on application load and then restore application state appropriately.
As far as content on this topic in the book goes, Chapter 3 and 4 cover using localStorage and the Web SQL database to save data, but not primarily around the topic of managing application state (although the JSON serialization technique I spoke about is covered). As per previous threads, I might see if I can put some content on the topic of "Managing application state through local storage" online somewhere. The books focus is primarily on managing application data.
Hope that makes sense, and answers both your questions Daniel.