Aquesta és una revisió antiga del document

Cordova

Apache Cordova (inicialment PhoneGap) son unes llibreries per al desenvolupament d'apps mòbils utilitzant JavaScript, HTML i CSS. La principal avantatge és que permet utilitzar un llenguatge web genèric (JS) i compilar l'app per a diverses plataformes diferents, d'entre les que destaquem les majoritàries Android i iOS.

El seu funcionament es basa en tenir una aplicació nadiua amb una simple WebView que ocupa tota la pantalla sencera. Implementant codi JavaScript dins la WebView ens permetrà controlar la interfície gràfica. Per accedir a les funcionalitats pròpies del dispositiu mòbil disposarem de certes llibreries (càmera, filesystem, acceleròmetre, etc).

Introducció i requisits

Per poder seguir aquest article se suposa que has de tenir coneixements de JavaScript, HTML i CSS.

Si tens coneixements molt bàsics també t'interessaria repassar els conceptes del DOM o Document Object Model.

Abans de començar a treballar amb Cordova caldrà que tinguem instal·lats els entorns de desenvolupament: llegeix Java i Android primerament.

Per instal·lar Cordova necessites un bon plegat d'eines. De forma general necessitaràs:

1. Android Studio que ens facilitarà les eines de l'Android SDK.
2. Java 8 JDK no ens servirà cap altra versió.
3. NodeJS que ens facilitarà el gestor de paquets NPM amb el què podrem instal·lar Cordova
4. Gradle en la darrera versió.

En cas de que puguis treballar en un Mac, hauràs d'instal·lar Xcode (des de la pròpia AppStore) i activar les CLI (Command Line Interface) Tools. En la versió Xcode 10 (High Sierra) seria:

XCode -> Preferences -> Locations -> Command Line Tools

MacOS: Instal·lació de Cordova per a MacOS.

Tens algun material per començar amb Cordova a Cacauet.org

Instal·lació en Ubuntu

1. Primer cal tenir instal·lat Anrdoid Studio:

   $ sudo snap install android-studio --classic

   1. Prova de crear un projecte dins d'Android Studio i llençar-lo sobre una VM Android (emulador) abans de seguir amb el tutorial.
2. Cal instal·lar Java 8 JDK, només funcionarà amb aquesta versió de Java.
   1. Vigila que no tens cap altra versió instal·lada. Si la tens, desinstal·la-la. Comprova si la tens amb (ha de sortir-te openjdk version 1.8):

      $ java -version

   2. Instal·la Java 8 JDK:

      $ sudo apt install openjdk-8-jdk

   3. Ajusta la variable d'entorn ANDROID_SDK_ROOT:

      $ export ANDROID_SDK_ROOT=~/Android/Sdk

   4. Millor que afegeixis aquest export a l'arxiu ~/.profile (afegiu-lo al final del fitxer). Si no, caldrà que facis l'export cada cop que obris una shell per treballar amb Cordova.
3. Necessitarem instal·lar NodeJS, no pel servidor web, sinó perquè necessitem el gestor de paquets npm:
   1. Canviem repos per descarregar la versió LTS:

      $ curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

   2. Instal·lar nodejs:

      $ sudo apt install nodejs

4. Instal·lar Cordova:

   $ sudo npm install -g cordova

5. També ens caldrà Gradle:
   1. Ajustem repos ppa per tal que s'instal·li la darrera versió:

      $ sudo add-apt-repository ppa:cwchien/gradle
      $ sudo apt install gradle

   2. Comprova que és una versió recent (7.x durant l'any 2022) amb:

      $ gradle -v

Quickstart

La seqüência típica per iniciar un projecte és com s'indica a continuació:

1. Crear projecte:

   $ cordova create proj1

2. Entrar al directori del projecte:

   $ cd proj1

3. Afegir plataformes (android/ios/browser):

   $ cordova platform add android

4. Compilar per Android:

   $ cordova build android

5. Arrencar el projecte a l'emulador:

   $ cordova run android

De vegades no arrenca bé l'emulador. Pots obrir-lo des del Android Studio, però llavors el IDE consumeix força recursos, i complica l'execució. Si tanques el projecte (File → Close Project a Android Studio) pots obrir el AVD Manager des de la pantalla d'inici d'Android Studio a Configure → AVD Manager.

També pots provar d'arrencar l'emulador des de la línia de comandes, com explica la doc oficial https://developer.android.com/studio/run/emulator-commandline

$ emulator -avd <el_meu_emulador>

Per exemple:

$ emulator -avd Pixel_2_API_28

Devices

Per córrer l'aplicació sobre un device real només cal que afegiu –device a la comanda:

$ cordova run android --device

Abans, però, caldrà que configureu el vostre dispositiu en mode developer buscant les dades del dispositiu i clicant 7 cops seguits al nº de compilació. Després activeu la Depuració USB.

Troubleshooting

Emulador KVM (Android Studio)

Si no et deixa crear una màquina virtual al Android Studio pq li falten permisos d'execució a KVM:

$ sudo chmod 777 /dev/kvm

Variables d'entorn GNU/Linux

Si al llançar el run ens dona errors en Ubuntu perquè no troba les llibreries (SDK, JDK), executa:

export ANDROID_SDK_ROOT=~/Android/Sdk

El millor és que incloguis aquestes darreres instruccions a l'arxiu ~/.profile del teu home directory i així no caldrà picar-les cada cop que vulguis treballar amb Cordova. Si ho fas, per tal de no reiniciar la màquina, pots carregar l'script manualment:

$ source ~/.profile

Variables d'entorn Windows

Alguna comanda no et funciona, és perquè necessita estar al PATH per poder ser trobada.

Cerca «variables» amb el cercador de Windows i t'hauria de facilitar accedir a les variables d'entorn. Modifica la variable PATH per afegir el què et calgui, com per exemple Gradle o el Android SDK que sol estar a:

\Users\usuari\AppData\Local\Android\Sdk

Però cerca abans per assegurar-te d'on son exactament les eines.

Altres

Si es queixa de:

No usable Android build tools found. Highest 30.x installed version is 30.0.2; minimum version required is 30.0.3

aquest post explica com corregir-ho, simplement seleccionant la versió que necessitem del SDK Manager:

Android Studio -> Tools -> SDK Manager -> Android SDK -> SDK Tools

i activant Show package details.

Java version

Si tenim el Java 11 no serveix, ha de ser Java 8. Això ho pots saber amb

$ java -version

Si tenim la 11, podem instal·lar en paral·lel la 8 amb:

$ sudo apt install openjdk-8-jdk

I posar la 8 com a versió per defecte amb:

$ sudo update-alternatives --config java
$ sudo update-alternatives --config javac

Si es queixa de que no troba JAVA_HOME, l'haurem d'afegir a l'arxiu .profile:

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/

Si aquest no fos el path adequat de JAVA_HOME us donaria un error. Mireu quin és buscant on està la ruta del compilador java

$ ll `which javac`
$ ll /etc/alternatives/javac

Gradle

Si es queixa de que li falta gradle, l'instal·lem.

Instal·lar gradle per a GNU/Linux:

$ sudo add-apt-repository ppa:cwchien/gradle
$ sudo apt install gradle

Instal·lar gradle per a Windows:

1. Descarrega la darrera versió de Gradle
2. Descomprimeix Gradle a una carpeta tipus C:\Gradle
3. Ajusta la variable d'entorn PATH per tal que inclogui C:\Gradle\bin

Instal·lar gradle per a MacOS: …coming soon… probablement brew install gradle

I ja pots tornar a provar el cordova run android

Llicències

Si es queixa de que li falten llicències per acceptar, entra a Android Studio → SDK Manager i accepta les llicències pertinents. També ho pots fer per comandes:

$ ~/Android/Sdk/tools/bin/sdkmanager --licenses

Apple, ios, macos

Treballant amb Apple podem trobar alguns problemes una mica diferents.

Les variables d'entorn cal ajustar-les d'aquesta manera (en macos Monterey):

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_311.jdk/Contents/Home/
export ANDROID_SDK_ROOT=~/Library/Android/sdk

També hi ha un problema amb el nom dels executables del compilador DX. Cal renombrar o fer un symlink als arxiu d8 i lib/d8.jar (en la meva instal·lació estan a ~/Library/Android/sdk/build-tools/32.0.0-rc1).

A la versió Xcode 10 tenim una issue que ens fa afegir un paràmetre una mica incòmode a la línia de comandes:

$ cordova build ios --buildFlag='-UseModernBuildSystem=0'
$ cordova run ios --buildFlag='-UseModernBuildSystem=0'

Sembla que a partir de Xcode 11 ja no apareix aquest problema.

Si falla amb el missatge

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

Aquest post explica la solució:

$ sudo xcode-select -s /Applications/Xcode-Beta.app/Contents/Developer

Construint una App amb JavaScript

Ara que tenim l'entorn preparat, es tracta de desenvolupar una app com si es tractés d'una aplicació web (com si fos pel browser) amb JavaScript. Podem aplicar llibreries típiques com jQuery o AngularJS, i a més disposarem d'algunes mes per poder accedir al hardware del mòbil.

Primera App

Afegint jQuery

jQuery ens pot ajudar molt a agilitzar el desenvolupament.

1. Instal·lació «a mà». Cal incloure els arxius de jQuery al nostre projecte. Ho pots fer de diverses maneres:
   1. Descarregar els arxius de la web oficial http://jquery.com
   2. Utilitzar els repositoris online (CDN). Pots veure com fer-ho en aquest tutorial:
   3. https://www.w3schools.com/jquery/jquery_get_started.asp
2. Instal·lació amb el package cordova-jquery de NodeJS que ens ho facilita (permet posar alguna plantilla típica per a apps mòbils).
   1. Està força obsolet, però té alguns templates que permeten començar ràpid.
   2. https://www.npmjs.com/package/cordova-jquery
   3. Instal·la-ho a l'arrel del teu projecte Cordova:

      $ npm install cordova-jquery

   4. Configura el template.
      • En Linux executa:

        $ node_modules/cordova-jquery/cordova-jquery

      • En Windows fes des del CMD:

        node node_modules/cordova-jquery/cordova-jquery

3. Mira com queda la plantilla fent de nou:

   $ cordova run browser

4. Prova diversos templates (per exemple: multipage, accordion, listview). Observa el codi que ens genera per cadascun d'ells, en particular el index.html.
5. Ens quedarem amb el listview ja que ens anirà bé com a base per a fer un exercici de tasklist.
   • La documentació oficial de jQuery movile listview ens serà útil per a saber com utilitzar-la.

Cordova no vol inlines

Típicament podríem fer una aplicació en JavaScript en una pàgina HTML i podríem posar botons que cridin a funcions del nostre codi amb un onclick (el què coneixem per crida inline). Doncs bé, Cordova no ens deixa fer inlines.

Forma de solventar-ho: fer els botons més senzills, sense onclick (però amb id):

<button id="boto1">Prem per afegir</button>

I després, en el nostre index.js, ja li afegim el onclick (jQuery version):

$('#addButton').click(addElem);

En aquest exemple, cridaríem a la funció addElem().

I un darrer apunt, la crida a aquesta funció no pot anar al principi del document, pq en el head encara no existeix el nostre button. Tenim 2 solucions:

1. Posar el tag <script src=… al final del doc (just després del button).
2. Posar el codi d'inicialització dins la funció onclick del document, perquè s'executi al acabar de carregar (exemple segueix):

   $(document).ready( function ()  {
   	// initialize
   	$('#addButton').click(addElem);
   	$('#apiButton').click(callAPI);
   });
   

Exercici Tasklist v1

Local Storage

localStorage és un objecte built-in de JavaScript dintre dels browsers que ens permet emmagatzemar dades persistents en una BD interna del tipus KEY-VALUE.

Les aplicacions web no estaven pensades per emmagatzemar dades, només per ser visualitzades, i en tot cas per interaccionar amb el servidor. Per això aquest recurs va trigar en implementar-se en els navegadors. A més, cal tenir en compte que, per raons de seguretat, l'accés al disc dur en un navegador sempre s'ha limitat molt (JavaScript no té accés al filesystem per seguretat de les dades de l'usuari).

És molt senzill d'utilitzar, al capdavall una DB key-value no deixa de ser un diccionari. En principi en tindreu prou amb els mètodes:

• localStorage.getItem
• localStorage.setItem

Mira't la doc de W3Schools per aprendre a utilitzar-ho.

Objectes a localStorage

Exercici Tasklist v2

Aplicarem tot l'exposat fins aquí en el següent exercici:

Utilitzant APIs amb AJAX

Treballar aplicacions en HTML+JS accedir a dades externes és molt còmode utilitzant crides asíncrones amb AJAX.

Una API web, també conegut com a web service és una interfície via web per demanar dades, així que es podria considerar una crida remota, d'aquí que en diguem API, com les llibreries de programació.

Explorarem la API externa per accedir a dades de www.musicbrainz.org

Exploreu els següents recursos:

1. API (respon en XML): https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2
2. Crides en JSON: https://musicbrainz.org/doc/Development/JSON_Web_Service
   • Per obtenir les dades en JSON cal que adjunteu el header de curl «Accept:application/json»
3. Per fer pretty print d'un JSON va molt bé «empipar-lo» a aquesta comanda:

   $ curl ... | python3 -m json.tool

Exemple:

$ curl -H 'Accept:application/json'  http://musicbrainz.org/ws/2/artist/5b11f4ce-a62d-471e-81fc-a69a8278c7da | python3 -m json.tool

AJAX amb jQuery

Aquestes mateixes les podem demanar des d'un document/aplicació HTML+JS amb crides asíncrones, el que solem conèixer per AJAX. Utilitzarem AJAX amb jQuery que ens ajudarà a simplificar el codi. Els exemples estan a la mateixa documentació, però us poso aquí un d'essencial per fer la crida i que ens retorni un objecte JSON de la API de musicbrainz.org :

$.ajax({
  method: "GET",
  url: "https://musicbrainz.org/ws/2/artist?query=queen",
  dataType: "json",   // necessitem això pq ens retorni un objecte JSON
}).done(function (msg) {
  for(let item in msg.artists) {
    console.log(msg.artists[item]);
    // aquí caldría fer mes coses, of course...
    // ...
  };
}).fail(function () {
	alert("ERROR");
});

Cal tenir en compte que les URLs a les que cridis amb AJAX han de tenir habilitada la capçalera de CORS (Cross-Origin Resource Sharing). Les APIs solen tenir-ho habilitat. Totes les APIs públiques ho tenen activat.

Pots veure una demo i explicació de com funciona a http://ieti.cat/cors/

Aquí s'explica els orígens de CORS força correctament.

Content Security Policy: Els paràmetres de la pàgina han blocat la càrrega d'un recurs a https://musicbrainz.org/ws/2/ («default-src»).

<meta http-equiv="Content-Security-Policy" content="default-src 'self' https://fonts.gstatic.com https://code.jquery.com  data: https://musicbrainz.org gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' https://fonts.googleapis.com 'unsafe-inline'; media-src *; img-src 'self' data: content:;">

Public APIs a go-go

Queries a la API de MUSICBRAINZ.COM

Documentació de musicbrainz:

• Doc oficial API Musicbrainz. Els exemples ens venen en XML.
• Instruccions per obtenir resultats en format JSON.

Exemples

Obtenir els resultats (en XML) dels grups amb «queen» al seu nom:

$ curl https://musicbrainz.org/ws/2/artist?query=queen

Per obtenir els resultats en format JSON cal afegir un header a la request de la query, per exemple:

$ curl https://musicbrainz.org/ws/2/artist?query=queen -H "Accept:application/json"

Si volem mostrar els resultats de forma mes clara en la shell, podem utilitzar una eina per indentar correctament:

$ curl ...url_query... | python -m json.tool

Materialize CSS

Plugins

…

Depuració (debug)

Per depurar el més fàcil és utilitzar al nostre codi missatges amb

console.log("missatge...")

Per poder mostrar aquests missatges dependrà de la plataforma que utilitzem:

Browser

Premem F12 per veure el Inspector de Chrome, i anem a la pestanya «Console». També ens serà útil aquesta eina per poder depurar a nivell gràfic i CSS

Android

Un cop llançada la app, executem:

$ ./platforms/android/cordova/log

Com que surten chorrocientos missatges, és més clar si filtrem només els què ens interessa (tot i que en determinats moments ens pot interessar treure el filtre per veure-ho tot). En aquest cas filtrem amb grep, case insensitive (-i), tots els missatges que continguin «console» o «cordova»:

$ ./platforms/android/cordova/log | grep -i 'console\|cordova'

Potser la manera més còmoda seria posar-ho tot a la mateixa comanda:

$ cordova run android ; ./platforms/android/cordova/log | grep -i 'console\|cordova'