For the latest Couchbase Mobile documentation, visit the Couchbase Mobile developer portal.
PhoneGap is a web application framework that provides a container to wrap your app in. You develop an app that uses Couchbase Lite and standard web technologies, wrap it in a PhoneGap container, and then build executables for iOS and Android devices from the same code base.
The following diagram shows the architecture of iOS and Android mobile apps that use the Couchbase Lite Plug-in for PhoneGap:
The following sections show how to build iOS and Android apps with the Couchbase Lite Plug-in for PhoneGap. This example uses a shared to-do list app called Todo Lite that demonstrates many Couchbase Lite features. When you develop your own apps later, you can follow these instructions and substitute your own source code for the ToDo Lite app source code.
Before you can build apps with PhoneGap, you need to install PhoneGap and several other tools on your computer. You might already have some of them installed. If you have problems installing the tools, see the troubleshooting section.
To get set up to use PhoneGap, install the following tools:
Install Git, which is a distributed version control system.
If you want to build apps for iOS devices:
$ brew install ios-sim
For additional information about setting up your iOS development environment, refer to the PhoneGap iOS Platform Guide.
If you want to build apps for Android devices:
Install Apache Ant, which is a build tool.
Install Android Studio.
Install the Android SDK by using the Android SDK Manager. If you have a project open in Android Studio, you can run the SDK Manager by selecting Tools > Android > SDK Manager.
Set up an Android emulator by using the Android AVD Manager. If you have a project open in Android Studio, you can run the AVD Manager by selecting Tools > Android > AVD Manager.
Add paths to the Android SDK tools and platform tools to your system’s PATH environment variable; for example, on Mac OS X add the following:
For additional information about setting up your Android development environment, refer to the PhoneGap Android Platform Guide.
The Node.js download installs both Node.js and the Node.js package manager (npm).
$ npm install -g phonegap
If you can’t install PhoneGap with this command, try
sudo npm install -g phonegap instead.
Now that you have all the tools installed, you can build the Todo Lite app. If you have problems building the app, see the troubleshooting section.
Get out a stopwatch, your 5 minutes starts now!
Open a terminal window and change to the directory that you want to store the Todo Lite project in.
Create a new PhoneGap project and change to its directory:
$ phonegap create todo-lite com.couchbase.TodoLite TodoLite $ cd todo-lite
After you create a new PhoneGap project, the project directory contains a directory named www. The www directory contains a default application.
Add the Couchbase Lite plug-in to your project:
$ phonegap local plugin add https://github.com/couchbaselabs/Couchbase-Lite-PhoneGap-Plugin.git
Add the following additional plug-ins to your project:
$ phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git $ phonegap local plugin add https://github.com/apache/cordova-plugin-inappbrowser.git $ phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git
These plug-ins activate the camera, the InAppBrowser, and network information.
Replace the default application in the www directory with the Todo Lite source code:
$ rm -rf www $ git clone https://github.com/couchbaselabs/TodoLite-PhoneGap.git www
When you develop your own app, replace the default application in the www directory with your source code.
Build and run the Todo Lite iOS app:
$ phonegap run ios
The Todo Lite app opens in the iOS simulator. If the iOS simulator does not open automatically, make sure ios-sim is installed.
Build and run the Todo Lite Android app:
$ phonegap run android
The Todo Lite app opens in the Android simulator. If the Android simulator does not open and you are prompted to log on to the Adobe PhoneGap build service, your Android device emulator is not set up correctly. You do not need to sign up for the PhoneGap build service to run this example.
If you cannot build the ToDo Lite app, review the troubleshooting tips in this section.
If you can’t build the ToDo Lite app, first make sure you have all the tools listed in Before You Begin installed and that you have the latest released version of each tool.
To verify that the command-line tools are installed and check version numbers, you can run the following commands in a terminal window:
$ git --version $ brew -v $ ios-sim --version $ node -v $ npm -v $ phonegap -v
To make sure PhoneGap and your IDEs are set up correctly, try building the default PhoneGap app for iOS and Android:
$ phonegap create my-app $ cd my-app $ phonegap run ios $ phonegap run android
For more information about setting up the SDKs on your computer, see:
The following table contains solutions for some other problems you might encounter when building the ToDo Lite app:
|You can’t install a command-line tool.|| Use the
|When you add plug-ins to your project, you get the following error message: [error] project directory could not be found.||Make sure you are in the /todo-lite directory.|
|When you build an iOS app, the iOS simulator doesn’t start automatically.||Make sure ios-sim is installed.|
|When you build an Android app, it uses the remote environment and prompts you to log on to the PhoneGap build service.||Make sure your Android device emulator is set up. For more information about setting up an emulator, read the Deploy to Emulator section in the PhoneGap Android Platform Guide|
|When attempting to run the app for Android, you encounter the following error: [error] An error occurred during creation of android sub-project.||Ensure that the Android SDK tools and platform-tools directories are added to your system’s PATH environment variable.|
If you cannot access the Couchbase Lite Plug-in for PhoneGap in the GitHub repository, you can use the Cordova download as an alternative. You can build apps with the Couchbase Lite Plug-in for PhoneGap by using Cordova instead of PhoneGap. The Couchbase Lite Plug-in for PhoneGap is listed on the Cordova Plugin Registry.
When using Cordova, you install the Couchbase Lite Plug-in for PhoneGap into your app by using the Cordova command-line tool.
To install Cordova on your computer:
$ npm install -g cordova
If you can’t install Cordova with this command, try
sudo npm install -g cordova instead.
To use Cordova to add the Couchbase Lite Plug-in for PhoneGap to your app:
$ cd <your/project/directory> $ cordova local plugin add com.couchbase.lite.phonegap