This section describes how to create a new app in Cordova and then configure Cordova to work with the Akula platform. Akula's Cordova libraries add support for Akula's sync and persistence mechanisms to JavaScript-based apps.

While it is not certified, you can integrate Akula with a PhoneGap app. For more information, see Building with PhoneGap

This document contains the following procedures:

Cordova SDK development environment requirements

To develop client apps, your development environment must meet the following system requirements:

Step 1: Preparing to configure Cordova for Akula

Before using the instructions in this section, you must install Cordova 3.0 or later. After installing Cordova, you can create a new app and add any platforms to it that you want to create apps for. For example, to create a new app:

$cordova create hello com . example . hello "HelloWorld"

This creates a new app in a directory called "hello". The default display text for this app is "HelloWorld". For more information on using Cordova commands, see http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html.

To add the iOS and Android platforms for your output, change to the /hello directory and use the following commands:

$cordova platform add ios 
$cordova platform add android

These commands create the /platforms/ios and /platforms/android directories under /hello. 

After you create the Cordova app, the go to the following sections to integrate Akula into the app based on your platform type:

• Step 2a: Configuring Cordova and Akula for iOS
• Step 2b: Configuring Cordova with Akula for Android  

Step 2: Integrating Akula into a Cordova app

This section describes how to integrate Akula into a Cordova app for the appropriate platform: Android or iOS.

Step 2a: Configuring Cordova and Akula for iOS

After you create a new Cordova app and add the iOS platform, you can add the Akula.framework and other necessary files to your Xcode project.

To configure the iOS development environment:

1. Locate the /cordova-sdk directory in the location where you installed Akula. If you have not done so already, download Akula from the Downloads page (you must log in to access this page).
2. Copy the /cordova -sdk/lib directory to the hello/www/js/lib directory in your Cordova project.
3. Copy the following JS files from /cordova -sdk/ datasources /sqlite directory to the hello/www/js/datasource/sqlite directory:
   
   • akula-cordova-sqlite-plugin.js
   • akula-cordova-sqlite-plugin-min.js
4. Copy the following files from the /cordova -sdk/datasources/sqlite/platform/ios/plugins directory to the hello/platforms/ios/HelloWorld/Plugins/AkulaCordova directory:
   
   • AKCordovaSQLitePlugin.h
   • AKCordovaSQLitePlugin.m
     
     
     The following example shows a suggested directory structure:
     

5. Edit the hello/platforms/ios/HelloWorld/config.xml file to add a reference to the Akula plugin. Add the following lines to the config.xml file:
6. Open the the hello/platforms/ios/HelloWorld.xcodeproj file in Xcode.
7. In the Xcode file explorer for your project, select the Plugins directory.
8. Add the following files to the Plugins directory: 
   
   1. hello/platforms/ios/HelloWorld/Plugins/AkulaCordova/AkulaCordovaSQLitePlugin.h
   2. hello/platforms/ios/HelloWorld/Plugins/AkulaCordova/ AkulaCordovaSQLitePlugin.m
9. In the Xcode Project Navigator pane, highlight your project to reveal the project settings.
10. Select the Build Phases tab.
11. Expand the Link Binary With Libraries section, and select its + button.
12. In the window that opens, select the Add Other button.
13. Select the Cordova frameworks directory at /cordova -sdk/AkulaCordovaSQLitePlugin.framework.
14. Click the Open button.
15. Select the + button in the Link Binary With Libraries section.
16. Add the SystemConfiguration.framework and Security.framework frameworks, and the libsqlite3.dylib library to your project.

17. Include the following <script> tags in your HTML file:

    Note The order of JS files that are loaded by your Cordova project is important. You must adhere to the following rules: underscore-min.js must be loaded before the cryptojs files. akula-cordova.js/akula-cordova-min.js and akula-cordova-sqlite-plugin.js/akula-cordova-sqlite-plugin-min.js must be loaded after the other JS files.

18. Test your configuration by following the steps in Step 3: Testing the Akula/Cordova configuration.

Step 2b: Configuring Cordova with Akula for Android

After you have created a new Cordova app and added the Android platform, you can add the required Akula files to your Android project.

To configure the Android development environment:

1. Locate the /cordova-sdk directory in the location where you installed Akula. If you have not done so already, download Akula from the Downloads page (you must log in to access this page).

2. Copy the /cordova-sdk/lib directory to your project's /www/js/lib directory.
3. Copy the following JS file from the /cordova-sdk/datasources/sqlite directory to your project's /www/js/datasources/sqlite directory:
   
   • akula-cordova-sqlite-plugin.js
   • akula-cordova-sqlite-plugin-min.js
     
     
   You can organize your project files in any directory structure that you want. The following example shows a suggested structure:
   
   

4. Include the JS files in your project's HTML files that use the Akula APIs.

   The following example includes these files:

   Note The order of JS files that are loaded by your Cordova project is important. You must adhere to the following rules: underscore-min.js must be loaded before the cryptojs files. akula-cordova.js/akula-cordova-min.js and akula-cordova-sqlite-plugin.js/akula-cordova-sqlite-plugin-min.js must be loaded after the other JS files.

5. Add the Akula Cordova plugin to your Cordova project. This plugin lets Cordova communicate with the persistent data store so that sync and persistence operations work.

   To do this, edit the /hello/platforms/android/res/xml/config.xml file and add the following section:
6. Copy the /cordova-sdk/datasources/sqlite/platform/android/AkulaCordovaSQLitePlugin.jar file to your Cordova project's /platforms/android/libs directory. 
7. If you are using an IDE, add the AkulaCordovaSQLitePlugin.jar file to your build IDE project's path.
8. Test your configuration by following the steps in Step 3: Testing the Akula/Cordova configuration.

Step 3: Testing the Akula/Cordova configuration

After you have configured Akula to use with your Cordova app, you can test that the APIs are accessible.

To use Akula in your Cordova app:

1. Create a new JS file in your /www/js directory.

2. Edit the file and include at least one call to a method in the Akula API. The following example initializes a connection to the MyApp app scope running on the Akula Server and then attempts to initialize the data store:

   my_akula.js
3. Load your new JS file in an HTML file in your project by adding a <script> tag, as the following example shows:
   
   <script type="text/javascript" src="js/my_akula.js"></script>
4. Trigger the call to the initializeApp() method in your HTML file. The following example adds an HTML button to do this:
   
   <button id="init_app" onclick="initializeApp()">Init App</button>
5. Prepare the app to run by using the Cordova prepare command, as the following example shows:
   
   $cordova prepare
   
   Run this command from the /hello directory. This command copies the contents of the app's /www directory to the platform-specific app in your /platforms directory.
6. Run your app in a simulator or on a device and click the HTML button (once).
   

   If you get an error such as "Uncaught ReferenceError: AK is not defined at file akula-cordova.js", then your JavaScript files might be loading in the wrong order. Use the following rules when adding JS files to an HTML page:

   
   
   • underscore-min.js must be loaded before the cryptojs files.
   • akula-cordova.js/akula-cordova-min.js and akula-cordova-sqlite-plugin.js/akula-cordova-sqlite-plugin-min.js must be loaded after the other JS files.