Cordova plug-ins

Plug-ins maken de brug tussen de hardware van het apparaat (GPS-sensor, camera, netwerk,…)   en de functionaliteiten (adresboek, kalender,…) die normaal niet beschikbaar zijn voor web-apps.

Een plug-in bestaat uit één Javascript-bestand met bijbehorende native-code per platform. In onze code hoeven we enkel te verwijzen naar een bepaalde functie of methode uit het Javascript-bestand. Van wat er in de achtergrond gebeurt (de communicatie vanuit javascript met de native code) hoeven wij ons niets aan te trekken.

Apache onderhoudt zelf een aantal plug-ins, maar het systeem is volledig open zodat ook andere ontwikkelaars eigen plug-ins kunnen schrijven.

Je kan zoeken naar beschikbare plug-ins op:

1. Cordova website
2. PhoneGap website
3. NPM website
4. Telerik website
5. Ionic website
6. …

In dit hoofdstuk leer je hoe je een plug-in installeert en aanspreekt. De gegevens die je terugkrijgt van de hardware worden op het scherm getoond en op het einde verwerkt in een praktische toepassing.

1. Maak in de map LesCordova een nieuw project aan:
   

   $ cordova create plugins be.uwnaam.plugins Plugins
   $ cd plugins
   $ cordova platform add browser android

2. Wis de volledige www-folder en vervang deze door de bestanden uit dit bestand: start_plugins.zip.
3. Bestudeer de bestanden.
4. Test de app in Chrome. Gebruik hiervoor het commando:

   $ phonegap serve

Single Page Application (SPA)

We gaan de toepassing volledig opbouwen rond een single page application of SPA. Voorlopig is hier nog niets van te merken.

index.html

Bij het openen van de app moet enkel het eerste onderdeel (het eerste tabblad) zichtbaar zijn. Dit kunnen we makkelijk vanuit CSS verwezenlijken. Merk op dat ieder onderdeel een unieke naam heeft (div#tabDevice, div#tabNetwork en div#tabCompass) en een gemeenschappelijke klasse (div.spa).

1. Voeg aan de interne style-tag de eigenschappen voor .spa en #tabDevice toe:
   

js/app.js

De navigatielinks kregen een data-show-attribuut. Hierin staat de tab vermeld die getoond moet worden als je op de link klikt. De navigatie is reeds in op de index-pagina aanwezig maar de interactie ga je nu aan app.js toevoegen.

1. Voeg binnen $(function(){ ... } volgende code toe:
   

Telkens je een navigatielink aanklikt, worden alle tabs gesloten (lijn 4). Op lijn 5 wordt de waarde van het attribuut data-show uitgelezen. Dit gebruiken we om de gewenste tab terug zichtbaar te maken. Bijvoorbeeld: data-show="tabDevice" genereert de code $('#tabDevice').show().
Als laatste wordt op lijn 6 de navigatie terug gesloten.

Plug-ins toevoegen.

In deze toepassing worden drie plug-ins gebruikt. Deze gaan we eerst installeren.

1. Voer achtereenvolgens onderstaande commando’s uit:
   

   $ cordova plugin add cordova-plugin-device
   $ cordova plugin add cordova-plugin-network-information
   $ cordova plugin add cordova-plugin-device-orientation

2. Of in één commando:
   

   $ cordova plugin add cordova-plugin-device cordova-plugin-network-information cordova-plugin-device-orientation

De geïnstalleerde plug-ins komen in de map plugins te staan. In onze code hoeven we niets te wijzigen.
Je mag zelfs geen verwijzing leggen naar de bijbehorende javascript-documenten. Telkens je de applicatie compileert, zullen de juiste verwijzingen automatisch in de code worden aangebracht.

Tip: je kan een plug-in verwijderen met het commando

$ cordova plugin remove <plug-in>

smartphone Device.

Met de plug-in cordova-plugin-device kunnen we o.a. informatie over het toestel en het platform opvragen. Lees aandachtig de documentatie. Kijk ook altijd naar de opmerkingen (quirks) die staan vermeld. Niet alle eigenschappen zijn op alle platformen beschikbaar!

js/device.js

Voorlopig wordt enkel de tekst Device info op het scherm getoond. Deze tekst gaan we nu vervangen door nuttige informatie over ons toestel.

1. Voeg binnen de init-methode console.log(device) toe.
   
   De informatie die je van een plug-in terugkrijgt, is meestal in de vorm van een JSON-object. Via console.log(device) kan je de inhoud van het JSON-object visualiseren in de console en hieruit de relevante informatie filteren. Voorlopig testen we nog in de browser en is de info vrij beperkt.
2. Test de app ook op een smartphone en vergelijk de gegevens in de console.
   
3. Verwerk deze informatie nu in de variabele data.
   
   

network_check Network.

De plug-in cordova-plugin-network-information geeft ons informatie over onze netwerkverbinding. Is het netwerk actie, zijn we geconnecteerd met WiFi of via 4G, enz …

Aan de hand van deze informatie kunnen we beslissen of een bepaalde actie al dan niet wordt uitgevoerd. Stel dat je een app ontwikkelt waarmee je foto’s kan nemen en deze uploadt naar je Dropbox, dan ga je het uploaden waarschijnlijk enkel uitvoeren als je via WiFi verbonden bent en niet via 3G of 4G.

js/network.js

Het voorbeeld over connection.type kunnen we bijna integraal overnemen in onze app. Enkel de laatste lijn (de alert-box) gaan we vervangen door een melding op de pagina.

1. Kopieer de voorbeeldcode uit cordova-plugin-network-information en plak deze binnen de methode _getState().
2. Verwijder de alert-box en toon het resultaat in h5#networkState.
   

3. Test de functionaliteit op je smartphone. In de browser verschijnt altijd de melding Unkwown connection.

Merk op dat de connectie enkel tijdens het opstarten van de applicatie wordt getest. Als je de verbinding verbreekt of wijzigt, zal er op het scherm niets veranderen. Dit kunnen we makkelijk oplossen door op regelmatige tijdstippen het netwerk opnieuw te testen.

1. Test binnen de init-methode de netwerkstatus met een interval van 1 seconden (= 1000 ms).
   

2. Wijzig het netwerk op je smartphone en controleer de tekst op het scherm. (WiFi aan/uit, vliegtuig stand, …)

my_location Compass.

js/compass.js

Met de plug-in cordova-plugin-device-orientation krijg je toegang tot het kompas van je smartphone. De kompas-sensor detecteert de richting van de bovenkant van het apparaat ten opzichte van het noorden (noorden = 0°).

Op de index-pagina staat een tekstveld (h5#compass), een pijltje (<p>&#9660;</p>), een kompasroos (img#compassImg) en twee knoppen (a#startCompass en a#stopCompass). Voorlopig gaan we enkel de richting uitlezen en in het tekstveld   h5#compass schrijven. In de opdracht die volgt, ga je de overige elementen verwerken.

De plug-in is al iets complexer en heeft drie methodes die we kunnen gebruiken:

1. navigator.compass.getCurrentHeading(compassSuccess, compassError)
   Haal eenmalig de richting (de heading) op.
2. var watchID = navigator.compass.watchHeading(compassSuccess, compassError, [compassOptions])
   Meet continu de richting waarnaar we wijzen.
3. navigator.compass.clearWatch(watchID);
   Stop de meting.

De tweede methode hebben we nodig voor onze toepassing. We gaan continu de richting meten en op het scherm tonen. Als we de voorbeeldcode vertalen naar onze module, wordt dit:

Elke twee seconden wordt er een nieuwe meting uitgevoerd. Het resultaat verschijnt in de console (console.log(heading)). Hier kunnen we uit afleiden dan heading.magneticHeading de richting bevat. Dit getal halen op en wordt op lijn 3 afgerond naar een geheel getal. Het geheel getal wordt samen met de tekst-variabele txt doorgegeven naar de methode _update(txt, degr). De methode _update(txt, degr)  toont de tekst op het scherm. (De parameter degr wordt op dit moment nog niet gebruikt. Deze heb je straks pas nodig.)

1. Test de applicatie in Chrome en op je smartphone.
   Let op: de browser heeft geen kompas en genereert bij elke meting een willekeurig getal tussen 0° en 359°!
   

Opdracht.

Het kompas blijft continu waardes meten. Ook als de applicatie naar de achtergrond verdwijnt, blijven de metingen doorlopen.Om het verbruik te beperken en de batterij te sparen, ga je de applicatie zodanig herwerken dat je het kompas met de knoppen START en STOP kan bedienen. Dit zijn de voorwaardes:

1. Maak de init-methode in js/compass.js leeg.
   Het kompas start nu niet meer automatisch op.
2. Leg vanuit jQuery een click-event op de knop #startCompass. Dit event verwijst naar Compass.start(), dat op zijn beurt het kompas eerste stopt en dan terug start.
3. Leg vanuit jQuery een click-event op de knop #stopCompass. Dit event verwijst naar Compass.stop(). Deze methode stopt de meting.
4. Ga nu op zoek naar een CSS3-eigenschap waarmee je de afbeelding img#compassImg rond zijn middelpunt kan draaien. Verwerk de gemeten waarde degr in de rotatie.
   

Kompas kalibreren.

Voor een nauwkeurige meting moet je het kompas van je smartphone regelmatig kalibreren. Dit kan je doen in de Google Maps-app.
Voor een Samsung-device kan je volgende procedure uitvoeren:

1. Open de telefoon-app en voer de code *#0*# in.
2. Klip op de Sensor tegel.
3. Kijk onder Magnetische sensor. Je ziet een zwarte cirkel met een lijn die naar het noorden wijst.
   Een rode lijn betekent dat je het kompas moet kalibreren (afbeelding links).
   Maak, net zoals bij de Maps-app, een aantal "achtjes" tot er een blauwe lijn verschijnt (afbeelding rechts).
   
4. Verlaat het menu door enkele malen op back-toets te klikken.