In questo paragrafo vediamo come aggiungere nuovi plugin Cordova alla propria applicazione.
Innanzitutto è necessario trovare il plugin Cordova giusto e, anche per questa ricerca, è possibile utilizzare il sito npm. Immaginiamo di voler controllare la “torcia” del dispositivo: ricercando “cordova flashlight” su npm, otteniamo questo risultato: cordova-plugin-flashlight.
Se non esiste un plugin Cordova che integra le funzioni native richieste, è possibile crearne uno seguendo la guida allo sviluppo dei plugin (in lingua inglese).
Vediamo adesso come integrare il cordova-plugin-flashlight. È possibile vedere il risultato dell’integrazione nel progetto Extensibility Design Patterns.
Dopo aver selezionato il plugin, è necessario definire la sua interfaccia all’interno del progetto Instant Developer Cloud. Questo avviene in modo simile a quanto abbiamo già fatto per gli elementi visuali. I passaggi sono i seguenti:
- Creare una nuova libreria di tipo Applicazione, oppure usarne una già esistente. Le librerie di tipo Applicazione definiscono le interfacce verso i vari componenti del framework, anche quelli aggiunti, e non contengono codice Instant Developer Cloud.
- All’interno della libreria, creare una nuova classe senza tipo e senza estensione. In questo esempio viene chiamata Flashlight.
- Definire proprietà, metodi ed eventi dell’elemento in modo corrispondente alle funzioni messe a disposizione dal plugin. Tutte le funzioni dovranno essere definite come asincrone e quindi avere la callback come ultimo parametro.
- Aggiungere alla classe una risorsa di tipo Plugin, in cui verrà scritto il codice JavaScript che implementa la classe di interfaccia del plugin. Il nome della risorsa deve essere uguale a quello della classe. A differenza degli elementi visuali, per i plugin la classe di interfaccia non deve essere caricata da un file esterno, ma scritta direttamente nell’editor di codice della risorsa di tipo Plugin.
- Infine, nella cartella App Objects dell’applicazione in cui si vuole utilizzare il plugin, si espande la proprietà device, e al suo interno si identifica la proprietà flashlight che viene creata dal sistema proprio per accedere al plugin. Nel campo parametri della proprietà occorre scrivere cordova-plugin-flashlight, cioè il parametro del comando cordova plugin add che serve per aggiungere il plugin al progetto Cordova. Il valore corretto è presente nel campo Install della pagina del plugin di npm, come mostrato nell’immagine seguente. Se devono essere specificati dei parametri di installazione, possono essere aggiunti dopo il nome del pacchetto, sempre nel campo parametri.
A questo punto è possibile utilizzare i metodi del plugin nella propria applicazione. Tuttavia il plugin funzionerà solo se l’applicazione è in funzione in un launcher personalizzato.
Definizione della classe di interfaccia #
La classe di interfaccia è un file JavaScript che mette in comunicazione il plugin Cordova con il framework di Instant Developer Cloud. Vediamo ora le varie parti che la compongono, utilizzando sempre l’esempio della torcia. Per verificare come sono stati integrati i plugin standard, è possibile vedere il repository pubblico di InstaLauncher.
Si ricorda che la classe di interfaccia deve essere caricata come risorsa di tipo Plugin nella classe che definisce il plugin.
Inizializzazione del plugin #
L’inizializzazione del plugin avviene tramite le seguenti righe di codice:
var Plugin = Plugin || {};
var PlugMan = PlugMan || {};
Plugin.Flashlight = {};
Plugin.Flashlight.init = function ()
{
// inserire qui il codice di inizializzazione
};Implementazione dei metodi #
Per ogni metodo della libreria, deve essere presente una corrispondente funzione del plugin. Nel caso di esempio, sono stati implementati i seguenti metodi:
Plugin.Flashlight.available = function (req)
{
window.plugins.flashlight.available(function(isAvailable) {
req.setResult(isAvailable);
});
}
Plugin.Flashlight.switchOn = function (req)
{
var opt = {};
if (req.params.intensity)
opt.intensity = req.params.intensity;
//
window.plugins.flashlight.switchOn(
function() {}, // optional success callback
function() {}, // optional error callback
opt // optional as well
);
}
Plugin.Flashlight.toggle = function (req)
{
var opt = {};
if (req.params.intensity)
opt.intensity = req.params.intensity;
//
window.plugins.flashlight.toggle(
function() {}, // optional success callback
function() {}, // optional error callback
opt // optional as well
);
}
Plugin.Flashlight.switchOff = function (req)
{
window.plugins.flashlight.switchOff();
}È importante notare che ogni metodo riceve un parametro req, che rappresenta la chiamata da parte dell’applicazione. I parametri della chiamata sono presenti nella proprietà req.params, come si vede nel metodo switchOn.
L’implementazione vera e propria dipende dal plugin Cordova utilizzato. Per restituire un risultato all’applicazione è necessario chiamare:
- req.setResult(result): per restituire un valore.
- req.setError(error): per generare un’eccezione.
Per notificare eventi all’applicazione, è necessario chiamare il metodo PlugMan.sendEvent nell’event handler che la classe di integrazione registra presso il plugin. Vediamo come esempio il metodo watchAcceleration del plugin Accelerometer. Questo metodo attiva la notifica dell’accelerometro all’applicazione chiamando il relativo metodo del plugin e passando la callback evidenziata in giallo. La riga di codice PlugMan.sendEvent genera la notifica dell’evento onAcceleration all’applicazione.
Plugin.Accelerometer.watchAcceleration = function (req)
{
// Clean, then set.
this.clearWatch(req);
//
var watchID = navigator.accelerometer.watchAcceleration(
function (acceleration) {
req.result = acceleration;
PlugMan.sendEvent(req, "Acceleration");
},
function () {
req.result = {error: "error"};
PlugMan.sendEvent(req, "Acceleration");
},
req.params);
//
// Remember which app requests this watch
this.watchList.push({id: watchID, app: req.app});
};Deallocazione delle risorse #
Al momento della chiusura dell’applicazione viene chiamato il metodo stopApp del plugin, che si deve occupare di liberare eventuali risorse acquisite durante il funzionamento.
Plugin.Flashlight.stopApp = function (app)
{
window.plugins.flashlight.switchOff();
};Test del plugin #
È possibile lanciare l’applicazione in anteprima in un browser, tuttavia:
- Chiamando un metodo che non restituisce risultati, esso non avrà effetto.
- Chiamando un metodo che restituisce risultati, viene generata l’eccezione: Plugin not found.
- Nessun evento verrà notificato.
Per testare il plugin in anteprima, è consigliabile creare e configurare un Developer Launcher tramite la console di Instant Developer Cloud, come indicato nel manuale Launcher: funzioni native e pubblicazione sugli store.
Un Developer Launcher è un’app che funziona come InstaLauncher, ma contiene anche i plugin nativi definiti nell’applicazione che viene installata nel launcher. A questo punto sarà possibile eseguire i test completi dell’applicazione, sia collegandola all’IDE che usando l’applicazione installata.
Per installare un Developer Launcher sui propri dispositivi è possibile operare come segue:
- Per iOS è possibile scaricare il progetto Cordova dalla console di Instant Developer Cloud e poi usare XCode per caricarlo direttamente sul proprio iPhone o iPad. In questo modo si ha la possibilità di effettuare un debug di basso livello. In alternativa è possibile configurare l’intera applicazione nel portale developer di Apple, caricare l’applicazione tramite il build server e poi attivare l’alpha test o il beta test tramite TestFlight.
- Per Android è conveniente scaricare l’applicazione in formato APK sui propri device e poi usare direttamente quella. È possibile anche scaricare il progetto Cordova nel caso in cui sia necessario un debug di basso livello; tuttavia questo richiede la configurazione completa dell’ambiente Cordova per Android.
Nota bene: il Developer Launcher contiene i plugin aggiuntivi solo se essi sono stati direttamente referenziati almeno una volta nel progetto. Nel caso di esempio, il plugin flashlight viene aggiunto solo se nel codice dell’applicazione viene fatto riferimento diretto a app.device.flashlight. Per verificare se una riga di codice contiene un riferimento diretto, è sufficiente aprire il menù contestuale nell’editor di codice sulla proprietà flashlight e verificare che sia presente la voce di menù Vai a flashlight.
Pubblicazione del plugin #
Come già visto nel paragrafo Pubblicazione di elementi tramite package, anche per i plugin è possibile creare pacchetti Instant Developer che ne consentono il riutilizzo in altri progetti, oppure la condivisione con altri utenti.
La procedura per la creazione del pacchetto è identica a quella per gli elementi. Tuttavia dopo aver importato il pacchetto in un altro progetto, sarà necessario indicare il comando di importazione nel parametro della proprietà relativa al plugin nell’applicazione, come indicato al punto 5 della lista precedente.