Cordova Eklentisi Oluşturmak

Bu yazıda basit bir Cordova eklentisinin nasıl oluşturulacağını, ne işe yaradığını ve ne zaman ihtiyaç duyduğumuzu anlatmaya çalışacağım.

Cordova Eklentisi Nedir?

Başlamadan önce Cordova eklentisinin ne olduğuna bakalım. Cordova eklentisi, web ile yerel sistem arasında bir köprü görevi görür. Bunu JavaScript ve yerel kodun birlikte çalışmasıyla sağlar.

Ne Zaman İhtiyaç Duyarız?

Cordova uygulamaları temelde bir web tarayıcısı içinde çalışır. Ancak web katmanı her zaman yerel sistemden ihtiyaç duyduğumuz özellikleri sunmaz. Bu yüzden yerel kod yazmamız ve sistemle iletişim kurmamız gerekir. Cordova eklentileri bunu mümkün kılar.

Nasıl Oluşturulur?

Bir eklenti oluşturmak için önce Cordova CLI ve Plugman'e ihtiyacımız var. Bunları terminalden aşağıdaki komutla kurabilirsiniz.

npm install -g plugman cordova

Ardından eklentiyi Plugman üzerinden oluşturabiliriz. Toplamda 3 parametre vermemiz gerekiyor.

plugman create --name PluginName --plugin_id "me.mazlum.pluginname" --plugin_version 0.0.1

Komutu çalıştırdıktan sonra mevcut dizininizde eklentinin temel klasör ve dosyaları oluşturulur. Daha sonra oluşan klasöre girip aşağıdaki komutla eklentiye bir platform ekleyebilirsiniz. Örnek olarak Android ile devam edelim.

plugman platform add --platform_name android

Yukarıdaki komutu çalıştırdıktan sonra örnek bir Java dosyası oluşur. Android platformu için yazacağınız tüm kodlar bu dosya üzerinden yönetilir. Bu noktada aslında oldukça basit bir eklentiniz olmuş oluyor. Eğer bu eklentiyi NPM üzerinden yayınlamak istiyorsanız, aşağıdaki komutla package.json dosyasını oluşturabilirsiniz.

plugman createpackagejson .

Bu noktadan sonra örnekler Android üzerinden ilerleyecek.

JavaScript API'si

Yazının başında da söylediğim gibi biraz JavaScript, biraz da yerel koddan bahsettik. Önce JavaScript tarafına bakalım. Aşağıdaki dosyaya www/PluginName.js üzerinden ulaşabilirsiniz.

var exec = require('cordova/exec');
exports.coolMethod = function (arg0, success, error) {
  exec(success, error, 'PluginName', 'coolMethod', [arg0]);
};

Bu dosyada oluşturulan fonksiyonlar üzerinden yerel kod ile iletişim kuracağız. Örneğin bu fonksiyonu JavaScript tarafından aşağıdaki gibi çağırabilirsiniz.

cordova.plugins.PluginName.coolMethod('test', (success) => {
  console.log('response', success);
});

Şimdi bunun yerel taraftaki karşılığına bakalım. Aşağıdaki dosyaya src/android/PluginName.java üzerinden ulaşabilirsiniz.

package me.mazlum.pluginname;
import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;
import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class PluginName 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.");
    }
}

JavaScript tarafından gönderilen parametreleri execute metodu üzerinden alıp işliyoruz. Yukarıdaki örnekte coolMethod buna iyi bir örnek.

Eklentiye Bağımlılık Eklemek

Eklentiyi oluşturduktan sonra mutlaka başka bir pakete ihtiyaç duyacaksınız. Peki Cordova eklentinize paketleri nasıl ekleyeceksiniz? Süreç basit. Eklentiyi CLI ile oluşturduğunuzda plugin.xml adında bir dosya da oluşur. Paketlerimizi bu dosyaya ekleyebiliriz. Örnek olarak Agora Voice SDK'yı ekleyelim.

<platform name="android">
  ....
  <framework src="io.agora.rtc:voice-sdk:3.3.0" />
</platform>

Eklentiye İzin Eklemek

Örneğin bu SDK'yı kullanırken mikrofon iznine ihtiyacımız olacak. Bu nedenle aşağıdaki kodla eklenti kurulduğunda bu iznin AndroidManifest.xml dosyasına otomatik eklenmesini sağlayalım. Bunun için yine plugin.xml dosyamızı düzenlememiz gerekiyor.

<platform name="android">
  ....
  <config-file parent="/manifest" target="AndroidManifest.xml">
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
  </config-file>
</platform>

Eklentiye Değişken Eklemek

Bir eklenti kurarken sabit bir değişkene ihtiyaç duyabiliriz. Bu değişkenler platforma özel ya da genel olabilir. Örneğin cordova-plugin-purchase eklentisini kurarken BILLING_KEY adında bir değişken vermeniz gerekir. Aşağıda parametreli eklenti kurulumuna bir örnek var.

cordova plugin add cordova-plugin-purchase --variable BILLING_KEY="MIIB...AQAB"

Peki bu değişkeni nerede tanımlıyoruz? Evet, yine plugin.xml içinde.

<preference name="MY_GLOBAL_VARIABLE" default=" " />
<platform name="android">
  ....
  <preference name="MY_VARIABLE" default=" " />
</platform>

Eklentiyi Bir Projede Kullanmak

Eklentimizi oluşturduk, paketlerimizi ekledik ve değişkenlerimizi tanımladık. Artık bu eklentiyi bir Cordova projesinde kullanmaya hazırız. Eğer eklentiyi henüz NPM'e yayınlamadıysanız, aşağıdaki şekilde Cordova projenize ekleyebilirsiniz. Cordova projenizin ana dizinine gidin ve aşağıdaki komutla eklentinizi projeye ekleyin.

cordova plugin add --link ~/path/PluginName

Bu aşamadan sonra yerel kod üzerinde istediğiniz değişikliği yapabilirsiniz.

Sonuç

Bu yazıyla birlikte küçük bir Cordova eklentisinin nasıl oluşturulacağını ve bazı temel özelleştirmelerin nasıl yapılacağını öğrenmiş olduk. Bir sonraki yazıda görüşürüz.