Пишем плагин для cordova

Напишем плагин для apache cordova на примере определения рутованного устройства android.

Подразумевается, что вы умеете работать уже с cordova и вся экосистема развернута. Нам понадобится утилита plugman.

npm install -g plugman

Далее с помощью нее можем создать «рыбу» для плагина с помощью команды

plugman create --plugin_id "ru.trykov.rootdetection" --name cordova-plugin-root-detection --plugin_version 0.1.0

—plugin_id задает идентификатор плагина в реестре плагинов кордовы
—name задает имя плагина
—plugin_version версию плагина

В результате мы получили файл plugin.xml, папки src и www. Папка www еще содержит js файл плагина с примером экспорта функции.

plugin.xml

Конфигурация плагина, в которой можно указать различные параметры. Подбронбее о всех элементах можно прочитать в документации. Мы же остановимся на основных вещах.

engines

Указываем версию кордовы на которую ориентирован плагин. В примере указана версия не менее 3.0.0

    <engines>
        <engine name="cordova" version="&gt;=3.0.0"/>
    </engines>

js-module

Указываем js модуль плагина, его имя и расположение. Так же используется элемент clobbers, который указывает, как в приложении cordova мы будем обращаться к модулю.

<js-module name="RootDetection" src="www/rootdetection.js">
    <clobbers target="rootdetection"/>
</js-module>

platform

Добавить платформу можно командой

plugman platform add --platform_name android

В результате в plugin.xml появится элемент platform, в котором мы можем указать конфигурационный файл в конечной платформе. И требуемые файлы плагина.

<platform name="android">
        <config-file parent="/*" target="res/xml/config.xml">
            <feature name="RootDetection">
                <param name="android-package" value="ru.trykov.root.RootDetection"/>
                <param name="onload" value="true"/>
            </feature>
        </config-file>
    <config-file parent="/*" target="AndroidManifest.xml"></config-file>
    <source-file src="src/android/RootDetection.java" target-dir="src/ru/trykov/root"/>
</platform>

Связываем java и js

Итак мы прописали пути до java файлов нашего плагина, теперь неплохо бы их самих создать. В элементе source-file мы указали путь src/android/RootDetection.java. Создадим необходимые папки и файлы по данному пути.

RootDetection.java

Файл, которые отвечает за работу на android платформе. Он должен наследоваться от CordovaPlugin и переопределять метод execute.

public class RootDetection extends CordovaPlugin {

    @Override
    public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
        if (action.equals("isDeviceRooted")) {
            try {
                callbackContext.success(isDeviceRooted() ? 1 : 0);
                return true;
            } catch (Exception e) {
                callbackContext.error("N/A");
                return false;
            }
        }
        return false;
    }
}

Метод execute принимает на вход следующие параметры:

action — имя метода по которому обращаются к плагину через js
args — аргументы метода
callbackContext — контекст обратного вызова, в который передаем результат работы плагина

Мы проверяем имя метода и вызываем нужный нам приватный метод класса для его исполнения. При успешном выполнении возвращаем success через контекст, иначе error.

www/rootdetection.js

Теперь через js мы должны обратиться к плагину. Cordova позволяет это делать через интерфейс cordova.exec со следующими параметрами:

successCallback функция при успешном вызове
errorCallack функция при ошибке
Имя Класса для вызова
Имя метода
аргументы

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

exports.isDeviceRooted = function(arg0, success, error) {
    exec(success, error, "RootDetection", "isDeviceRooted", [arg0]);
};

Работа в приложении

Фактически создание плагина завершено, его уже можно добавлять в приложение cordova.

cordova plugin add /путь/до/плагина/

Вы так же можете поделится результатами своих трудов с другими разработчиками опубликовал плагин в реестре плагинов кордова.

Публикация

Итак у нас есть готовый плагин и мы хотим его зарегистрировать в cordova plugin registry т.е. реестр плагинов кордовы, для этого выполним следующие команды:

Добавляем пользователя: указываем логин, пароль, почту.

plugman adduser

Публикуем.

plugman publish

И… чуть было не опубликовались, но выскочила ошибка login error. Хотя мы тока что добавили пользователя. Гугление приводит к даунгрейду plugman до 23 версии

npm install -g plugman@0.23.0

Далее заново добавляем пользователя и публикуемся.

Теперь плагин доступен в cordova cli по id плагина.

cordova plugin add ru.trykov.rootdetection

Миграция на npm

C 21 апреля 2015 года cordova потихоньку переносит плагины в npm реестр. Чтобы начать использовать npm необходимо обновить cordova cli до версии не ниже 5.0. Меняются id основных плагинов cordova с org.apache.cordova.* на cordova-plugin-*. Теперь разработчики могут использовать команду cordova plugin add cordova-plugin-device. с использование нового ID плагина, который будет выкачиваться из npm. Что будет с текущим реестром плагинов? С 15 июля 2015 он станет доступен только для чтения до 15 октября, а дальше увидим. Подробнее читайте тут.

По шагам мигрируем на npm:

(По желанию) Можно изменить id плагина в plugin.xml и опубликовать их в реестре плагинов кордовы.
1. Отправить pull request с новым и старым id на Cordova Registry Mapper.
2. Кордова итегрирует эти id в cordova cli и будет выдавать предупреждение пользователям, чтобы они использовали новый идентификатор
Добавить package.json
1. plugman createpackagejson <directory> (если находимся в папке плагина, то ставим точку)
Опубликовать в npm
1. npm login
2. npm publish

Далее можем уже добавлять плагин cordova через новый id.

cordova plugin add cordova-plugin-root-detection

Но после логина в npm у нас эта команда вызовет ошибку

unauthorized Name or password is incorrect

Чтобы от нее избавится — удаляем .npmrc из домашней директории.

Итого

Мы написали плагин, опубликовали его в реестре плагинов кордовы и npm. Ознакомится с полным кодом плагина вы можете на github. Присылайте свои pull request’ы и пишите плагины для кордовы.

Удачного дня.

Похожее