This repository is a first step to help the Couchbase community develop a standard, cross-platform (iOS, Android, and future platforms!) way of managing a CouchDB when using PhoneGap.

I started a thread explain this: https://groups.google.com/group/mobile-couchbase/browse_thread/thread/f4e9bc30e1dd3818

The goals are:
1) Allow for offline CouchApp, views and seed data loading since you cannot assume there will be a connection to download a CouchApp.
2) Provide a standard way for users to to authorized locally and to create an account on a remote server. 
3) Provide best practice samples for organizing and syncing local and remote databases. For example: using local databases like "appdata_db" with server databases like "myusername/appdata_db" and making sure authentication and authorization is secure.
4) Allow for users to trigger synchronizations from their mobile device while handling 2) and 3).
5) Cross-platform project creation in as simple and trouble free way as possible.

Current Progress
**************
1) Offline CouchApp, views and seed data loading on iOS - YES
2) Offline CouchApp, views and seed data loading on Android - YES (but buggy - I believe due to the libcouch-android refactor: views don't work and I was only able to get 2.3.1 and 2.3.3 working)

Workflow (only tested on Mac OSX):
**************

1) The workflow to update the CouchApp is currently as follows:

  a) Load the CouchApp into a desktop/laptop/cloud CouchDB. For example: 
     couchapp autopush http://127.0.0.1:5984/mycouchapp_db

  Note: don't forget the first time to run plain old 'push' like:
     couchapp push http://127.0.0.1:5984/mycouchapp_db

  b) When you are happy with the CouchApp, serialize it and don't forget to put it in the Resources XCode project directory. 

  Note: you must remove the "_id" and "_rev" fields from the exported file - you can do it by hand or use the couchpack gem.

  --------------------------------
  By hand (the hard way!):

     cd phonegap-couchbase-xplatform/phonegap-couchbase-ios/phonegap-couchbase-ios/Resources
     curl -X GET http://127.0.0.1:5984/mycouchapp_db/_design/mycouchapp?attachments=true > mycouchapp.json
     Then edit mycouchapp.json to remove the "_id" and "_rev" fields.

  --------------------------------
  By using couchpack:

    Install:
     gem install couchpack

    Run (one time):

     cd phonegap-couchbase-xplatform/phonegap-couchbase-ios/phonegap-couchbase-ios/Resources
     couchpack document http://localhost:5984/mycouchapp/_design/mycouchapp mycouchapp 

    Run (automatically watching for changes):
     
     couchpack document http://localhost:5984/mycouchapp/_design/mycouchapp mycouchapp --auto


  c) Make sure the file is added to the resource directory in your project. Then build and run in XCode.

Sample Code (iOS):
**************
Goal 1) Allow for offline CouchApp, views and seed data loading

There is an objective-C class called CouchMover which handles: 
- document version checking using a client supplied version string (version check can be performed without CouchApp JSON loading/parsing)
- creating the document database if it doesn't exist, creating and replacing the document
- loading of any CouchApp page URL

1) See AppDelegate.h and AppDelegate.m for integration tips. All Couchbase code that is integrated into PhoneGap is labeled with:

// Couchbase changes START
// Couchbase changes END

2) The CouchMover class handles loading (or "moving") couch documents into CouchBase. It can be used for CouchApps or even initialization data or views. PhoneGap and CouchApps are completely optional. 

  --------------------------------
  For example, for a couchapp:

    NSURLCredential *credential = [NSURLCredential credentialWithUser:@"admin" password:@"admin" persistence:NSURLCredentialPersistenceForSession];
    CouchMover* couchMover = [[CouchMover alloc] init:serverURL serverCredential:credential databaseName:@"mycouchapp_db"];
  
    // load the coachapp if needed from a bundle (you can create non-bundle loading options through loadDocument)
    [couchMover loadDocumentFromBundle:[NSBundle mainBundle] documentName:@"_design/mycouchapp" documentBundlePath:@"mycouchapp.json" versionBundlePath:@"mycouchapp.version"];
  
    [couchMover gotoAppPage:@"_design/mycouchapp" webView:self.webView page:@"index.html"];
    [couchMover release];

  --------------------------------
  For example, to load a document:

    NSURLCredential *credential = [NSURLCredential credentialWithUser:@"admin" password:@"admin" persistence:NSURLCredentialPersistenceForSession];
    CouchMover* couchMover = [[CouchMover alloc] init:serverURL serverCredential:credential databaseName:@"mycouchdocument_db"];

    // load the data if needed from a bundle (you can create non-bundle loading options through loadDocument)
    [couchMover loadDocumentFromBundle:[NSBundle mainBundle] documentName:@"mydata" documentBundlePath:@"mydata.json" versionBundlePath:@"mydata.version"];

    [couchMover release];


3) In order to add CouchMover into your project, current you need to:

  a) include the CouchMover files (CouchMover.h, CouchMover.m) 
  
  b) include the normal Couchbase files (Couchbase.bundle, Couchbase.h, libCouchbase.a) 
  
  c) include four files from TouchFoundation (Base64Transcoder.c, Base64Transcoder.h, NSData_Base64Extensions.h, NSData_Base64Extensions.m). This is for Base64 encoding for authentication - once Apple releases a standard implementation (and the project is updated) or if you link with TouchFoundation, you will no longer need these files. 


Sample Code (Android): (buggy - I believe due to the libcouch-android refactor: views don't work and I was only able to get 2.3.1 and 2.3.3 working)
**************
Goal 1) Allow for offline CouchApp, views and seed data loading

There is a Java class called com.couchbaseextensions.CouchMover which handles: 

- document version checking using a client supplied version string (version check can be performed without CouchApp JSON loading/parsing)
- creating the document database if it doesn't exist, creating and replacing the document
- loading of any CouchApp page URL

1) See PhonegapCouchbaseAndroid.java and com.couchbaseextensions.CouchStarter for integration tips. All Couchbase code that is integrated into PhoneGap is labeled with:

// Couchbase changes START
// Couchbase changes END

2) The CouchMover class handles loading (or "moving") couch documents into CouchBase. It can be used for CouchApps or even initialization data or views. PhoneGap and CouchApps are completely optional. 

  --------------------------------
  For example, for a couchapp:

	PasswordAuthentication credential = new PasswordAuthentication("admin", "admin".toCharArray());
  CouchMover couchMover = new CouchMover(serverURL, credential, "mycouchapp_db");
    
  // load the coachapp if needed from a bundle (you can create non-bundle loading options through loadDocument)
  couchMover.loadDocumentFromAssetManager(getAssets(), "_design/mycouchapp", "mycouchapp.json", "mycouchapp.version");
      
	couchMover.gotoAppPage("_design/mycouchapp", appView, "index.html");

  --------------------------------
  For example, to load a document:

	PasswordAuthentication credential = new PasswordAuthentication("admin", "admin".toCharArray());
	credential = null; // NO USER/PASSWORD ON ANDROID
  CouchMover couchMover = new CouchMover(serverURL, credential, "mycouchapp_db");
    
  // load the data if needed from a bundle (you can create non-bundle loading options through loadDocument)
  couchMover.loadDocumentFromAssetManager(getAssets(), "mydata", "mydata.json", "mydata.version");

	couchMover.gotoAppPage("_design/mycouchapp", appView, "index.html");


3) In order to add CouchMover into your project, current you need to:

  a) include the CouchMover files (CouchMover.java). You can also use CouchStarter.java if you like, but I'm probably not going to maintain it once I start dealing with real-world error conditions. 
  
  b) include the libcouch-android library and set it up using the online instructions: https://github.com/couchbaselabs/Android-Couchbase/blob/master/README.md
  

Notes:
**************
- iOS version doesn't use Trundle to try to keep it minimal.
- iOS version is currently bundled with minimal Vendor Source (Couchbase, TouchFoundation).
- currently the CouchMover libraries are written to use synchronous HTTP calls to keep the program flow simple. You can use Grand Central Dispatch (GCD) to put it on a background thread, but on Android, it is up to you how to put it on a background thread.


Troubleshooting:
**************
1) If you want to run it on a physical device:
-> You need to apply for an appID and configure it using these instructions: http://wiki.phonegap.com/w/page/39991939/Getting-Started-with-PhoneGap-iOS-using-Xcode-4-(Template-Version)

2) If you are having problems with your app switching from PhoneGap to the local Safari app when you call [webView stringByEvaluatingJavaScriptFromString:couchappApgeURL], you need to 
add localhost to the ExternalHosts key in your PhoneGap.plist:
-> Select your PhoneGap.plist in the "Supporting Files" directory, and 
add the following 2 items as separate entries: 127.0.0.1 and 0.0.0.0.

3) If you get this warning: "Sending 'AppDelegate *' to parameter of incompatible type 'id<CouchbaseDelegate>'" 
-> This is because you need to set up your app delegate to also be a 
CouchbaseDelegate like this: 
    @interface AppDelegate : PhoneGapDelegate<CouchbaseDelegate>

4) If you get this warning: "Warning: The Copy Bundle Resources build phase contains this target's Info.plist file 'YourApp-Info.plist'. " 
-> You need to go into the "Copy Bundle Resources" and delete your App 
plist...Select your project in the left side panel, then select your 
TARGET, then choose the "Build Phases" tab, open "Copy Bundle 
Resources", select your App plist, press '-' to delete. 

5) If you app doesn't load, make sure you removed the "_id" and "_rev" fields, and that you added it as a resource in your XCode project.

6) If you are having build issues, make sure you have included in your project what you need from the Vendor directory.

Good luck!

Kevin