Node.JS plugin for Apache Cordova (built on JXcore)

Goals

This project is intended to ;

• create an easy to use node.js plugin for Apache Cordova (Android, iOS)
• show JXcore's embedding interface in details.

Installation

If you are on Visual Studio 2015, see this comment for easy installation.

If you don't have Cordova installed, follow the steps from this link to install Apache Cordova.

Assuming your first Cordova JXcore application is located under /hello folder;

Go under /hello folder.

In order to add JXcore plugin into your Android, iOS 'hello' project, follow the steps below;

1- Download JXcore from jxcore.com/downloads

2- [Optional] In case you don't have wget or something similar is installed

for unix;

sudo jx install -g download-cli

for windows

jx install -g download-cli

3- Download jxcore-cordova binary into your Cordova/Phonegap project

download https://github.com/jxcore/jxcore-cordova-release/raw/master/0.0.4/io.jxcore.node.jx

Extract JX package

jx io.jxcore.node.jx

4- Install plugin

cordova plugins add io.jxcore.node/

Once everything is set and you have added jxcore-cordova extension, create a folder named jxcore right under www

www/jxcore/app.js is your entry point to JXcore's JS.

Node modules should go in the www/jxcore/node_modules folder.

Important Steps for the First Timers
Under the sample folder you will find express sample application. There you have the entire www folder that you can use instead of the www folder under cordova project root folder. Replace www folder from the project's root to the one under the sample/express sample.

You can also use the automated script on posix platforms: install_and_run.sh. More on this here.

Are you are looking for a minimalistic sample? follow the steps below;

1. Under the sample/www folder of this repo, you will find index.html. This sample file shows how to integrate JXcore interface into Cordova client side. Prior to installing JXcore plugin, you should update Cordova's index.html as shown from this sample file.

2. This plugin expects you to have a folder named jxcore under www folder. The sample index.html tries to load app.js from this folder. You can copy sample/www/ folder into www to run the basic demo.

!In case you have a problem with installing the plugin. You may follow the steps below; (be careful though since this trick removes the existing platforms and installs them back)

cordova platform remove ios
cordova platform remove android
cordova plugins remove io.jxcore.node
cordova plugins add jxcore-cordova/
cordova platform add ios
cordova platform add android

Now you can visit platforms/ios or platforms/android folders and open Xcode project file or import the android project from Eclipse.

Updating JXcore binaries [optional]

Below are the steps to be taken if you want to update JXcore binaries in your Cordova JXcore application. They all should be called prior to cordova plugin add command. This step is optional. We keep the core binaries are updated.

1. Rebuild JXcore binaries: Compile as a Static Library

2. Refresh jxcore-cordova/src/android/jxcore-binaries folder contents:

   $ cd /my/cordova/app
   $ git clone https://github.com/jxcore/jxcore-cordova.git
   $ rm -f ./jxcore-cordova/src/android/jxcore-binaries/*
   $ cp -f /jxcore/repo/out_android/android/bin/* jxcore-cordova/src/android/jxcore-binaries/

3. Recompile .so files

   $ cd jxcore-cordova/src/android/jni
   $ ~/android-ndk-path/ndk-build

4. Add/re-add the plugin/platform

   $ cd ../../../../
   $ cordova plugin add jxcore-cordova/
   $ cordova platforms add android

5. You may run the app now

   $ cordova run

Usage

JavaScript on UI side works on top of Cordova's webUI. JXcore's JavaScript is a separate instance.

So you need an API to communicate between Cordova JS to JXcore JS.

Cordova to JXcore

These API methods are used on the side of Apache Cordova (for example, in the main index.html of your Cordova application).

Sharing a JavaScript function from Cordova to JXcore

jxcore(name_of_the_function).register(a_function_to_register);

Example:

jxcore('alert').register(function(msg){ alert(msg); });

Calling a JavaScript function (shared on JXcore side) from Cordova

jxcore(name_of_the_function).call(params_to_send..., callback);

Example:

jxcore('asyncPing').call('Hello', function(p1, p2, p3...){ });

JXcore to Cordova

These API methods are used on the side of JXcore (for example, in the main app.js of your application based on Node API).

Sharing a synchronous JavaScript function from JXcore to Cordova

Mobile(name_of_the_function).registerSync(a_function_to_register);

This method expects the registered function to be synchronous (i.e. to immediately return a value).

Example:

Mobile('syncPing').registerSync(function(msg){ return msg + ' pong'; });

Sharing an asynchronous JavaScript function from JXcore to Cordova

Mobile(name_of_the_function).registerAsync(a_function_to_register);

This method expects the registered function to be asynchronous (i.e. to return some value using a callback).

Example:

Mobile('asyncPing').registerAsync(function(msg, callback){ callback(msg + ' pong') });

Calling a JavaScript function (shared on Cordova side) from JXcore

Mobile(name_of_the_function).call(params...);

Example:

Mobile('log').call(msg);

JXcore to JAVA / Objective-C (vice versa)

You may also define JXcore JS side methods those you want to call from Java / Obj-C.

If you need a JS side method that you want to call multiple times use below approach instead depending on a method callback id.

How to Install Node Modules

Visit www/jxcore folder and install the node modules there. It's adviced to use 'jx install' command to install node modules from npm.

For example

// UNIX
www/jxcore > sudo jx install jxm --autoremove "*.gz" 

// Windows
www/jxcore > jx install jxm --autoremove "*.gz"

'--autoremove "*.gz"' will be removing the gz files from modules folder. Android APK doesn't allow you to put .gz files into application's assets.

Where To Save your Files (Write access on mobile targets) EROFS error ?

Consider using either process.userPath or require('os').tmpdir() to get the Documents (on ios) or a folder you have the write access. process.cwd() or __dirname may not target a folder that you have the write access!

If you are okay with using Mobile specific API see Mobile.GetDocumentsPath below;

Mobile.getDocumentsPath

Returns the location for Application (specific) writable folder.

Mobile.getDocumentsPath(function(err, location) {
  if (err)
    console.error("Error", err);
  else
    console.log("Documents location", location);
});

Android and iOS file systems behave differently. Android OS supports external persistent storage. If you want to store a persistent information on Android OS, consider using sdcard location.

Mobile.getConnectionStatus

Returns device's connection status

Mobile.getConnectionStatus(function(err, status) {
  if (status.NotConnected)
    console.log("No internet connection");
  else if (status.WiFi)
    console.log("WiFi");
  else if (status.WWAN)
    console.log("Mobile Connection");
});

Mobile.getDeviceName

Returns device's manufacturer and model name

Mobile.getDeviceName(function(err, name) {
  if (err)
    console.error("Something bad has happened");
  else 
    console.log("Device name", name)
});

JS Error Tracking

If you want to customize JS side errors, visit JXMobile.java for Android and JXMobile.m for iOS and update OnError behavior

Remarks

• JXcore cordova interface doesn't keep the reference for a callback id once it's used.
• JavaScript is a single threaded language. Don't call the referenced JS methods from other threads.

  Mobile('fromJXcore').registerToNative(function(param1, param2){
    // this method is reachable from Java or ObjectiveC
    // OBJ-C : [JXcore callEventCallback:@"fromJXcore" withParams:arr_parms];
    // Java  : jxcore.CallJSMethod("fromJXcore", arr_params);
  });

See JXcoreExtension.java / JXcoreExtension.m / .h for sample Java/Obj-C definitions.

Contribution

If you see a mistake / bug or you think there is a better way to do the things, feel free to contribute. All the contributions are considered under MIT license.