前回は、Cordovaプラグインの仕組みを理解するために、Plugmanで作成できるCordovaプラグインの雛形を使用して、plugin.xmlの設定について説明しました。今回も、前回使用したCordovaプラグインを使用して、SamplePlugin.jsの設定について説明していきたいと思います。

/SamplePlugin/www/SamplePlugin.jsの設定について

アプリ側のJavaScriptからCordovaプラグインの機能を利用(参照)するためのメソッドやプロパティーを設定したい場合は、SamplePlugin.jsに設定します。雛形では、coolMethodという名前の関数が設定されています。

var exec = require('cordova/exec');

exports.coolMethod = function (arg0, success, error) {
    exec(success, error, 'SamplePlugin', 'coolMethod', [arg0]);
};

このcoolMethod関数が、以下のように、CordovaプラグインのcoolMethodメソッドとして参照する事ができます。

  • cordova.plugins.SamplePlugin.coolMethod()

coolMethod関数内のexec関数が実行されることで、ネイティブ側の処理が実行されます。exec関数については、以下を参照してください。

exec関数の第1引数のsuccessは、処理が成功した際のコールバック関数になります。

exec関数の第2引数のerrorは、処理が失敗した際のコールバック関数になります。

exec関数の第3引数に設定されている値SamplePluginは、

  • /plugin/platform/config-file/feature

のname属性に設定した値を指定します。

exec関数の第4引数に設定されている値coolMethodは、ネイティブ側で処理を判別するための文字列になります。

exec関数の第5引数には、ネイティブ側に渡すデータの配列になります。

このことから、

  • coolMethod関数の第1引数は、exec関数の第5引数に渡すデータ。
  • coolMethod関数の第2引数は、exec関数の第1引数に渡す成功時のコールバック関数。
  • coolMethod関数の第3引数は、exec関数の第2引数に渡す失敗時のコールバック関数。

になります。

ソースコードを確認してみる

雛形で作成された以下のAndroid用ソースコードファイルを確認してみます。

  • /src/android/SamplePlugin.java

ソースコードの内容は、以下になります。

package cordova-plugin-sample;

import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

/**
 * This class echoes a string called from JavaScript.
 */
public class SamplePlugin extends CordovaPlugin {

    @Override
    public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
        if (action.equals("coolMethod")) {
            String message = args.getString(0);
            this.coolMethod(message, callbackContext);
            return true;
        }
        return false;
    }

    private void coolMethod(String message, CallbackContext callbackContext) {
        if (message != null && message.length() > 0) {
            callbackContext.success(message);
        } else {
            callbackContext.error("Expected one non-empty string argument.");
        }
    }
}

exec関数が実行されると、SamplePlugin.javaのexecuteメソッドが実行されます。

executeメソッドの第1引数には、exec関数の第4引数に設定されているcoolMethodが渡されます。第2引数には、exec関数の第5引数に設定されている[arg0](配列)が渡されます。arg0は、coolMethod関数の第1引数の値になります。

executeメソッドでは、以下の処理が実行されています。

if (action.equals("coolMethod")) {
}

処理を識別する文字列としてcoolMethodと第1引数(action)と比較されている事がわかります。

注目するソースコードは、以下になります。

String message = args.getString(0);

第2引数として渡されたcoolMethod関数の第1引数の値が、String型として処理されています。JavaのString型は、文字列になります。そのことから、coolMethod関数に設定する第1引数は、文字列という事になります。

雛形で作成された以下のiOS用ソースコードファイルも、Androidと同様の処理を行っています。

  • /src/ios/SamplePlugin.m

アプリ側のJavaScriptからは、以下のように実行する事で、雛形のCordovaプラグインを実行する事ができます。第1引数に文字列を設定し、第2引数には、成功時のコールバック関数、第3引数には、失敗時のコールバック関数を指定します。

cordova.plugins.SamplePlugin.coolMethod(
    "SamplePlugin", 
    function(result) {
        alert(result);
    }, 
    function(err) {
        alert(err);
    });

おわりに

今回は、雛形で作成されたSamplePlugin.jsの設定について説明しました。plugin.xmlの

  • /plugin/js-module

ディレクティブに設定されているファイルを確認することで、Cordovaプラグインで利用できるメソッドやプロパティーを確認する事ができます。Cordovaプラグインに設定されているメソッドやプロパティーの設定内容を確認したい時は、js-moduleディレクティブに設定されているファイルを確認してみてください。

Cordovaプラグインを理解しよう(構成編)では、雛形のCordovaプラグインの状態では、Androidでビルドエラーが発生することを伝えました。次回は、ビルドエラーを解消したいと思います。