Comments
Description
Transcript
Struttura progetto Phonegap/Cordova
Struttura progetto Phonegap/Cordova Antonio Gallo [email protected] 1 Creazione app Per creare una nuova app con cordova entrare nella cartella dei vostri progetti e premere shift + tasto destro. Selezionare "apri finestra di comando qui". L'istruzione per creare una app è, ad esempio: cordova create hello com.example.hello HelloWorld Dove: hello: nome cartella dove starà la vostra app. Se non c'è, la crea. com.example.hello: dice dove andrà installata la vostra app all'interno della sottocartella android. Stile package Java. Lasciare immutato per ora (non va bene example per Google Play!) HelloWorld: Nome della app come comparirà nel vostro cellulare. Potete usare i nomi che volete, ad esempio: cordova creare mio_test com.antonio.mio_test MioTest A questo punto dovete caricare tutti i file che servono ad Android per poter far girare la vostra app: cordova platform add android Per provare a vedere se la app funziona, collegate il vostro cellulare e lanciate: cordova run android 2 Struttura cartelle Una volta creata la cartella hello, potete entrarci facendo: cd hello L'istruzione cd sta per change directory e serve per entrare dentro una cartella dalla riga di comandi (prompt). Potete anche entrarci navigando tra le cartelle nel modo usuale (visuale). All'interno della cartella hello avrete i seguenti file e cartelle: hooks/ platforms/ plugins/ www/ config.xml Il significato delle suddette cartelle è il seguente: Cartella hooks: Contiene degli script (pezzi di codice) che intervengono nel build del progetto. Cosa significa? Quando voi usate cordova per lanciare la app (cordova run android), il software cordova si prende in carico di preparare tutti i file e di caricarli nel vostro cellulare, lanciare la compilazione di quello che serve, etc (questo più o meno è il build del progetto). Può capitare però che voi abbiate necessità che cordova faccia anche qualcosa che serve a voi prima di lanciare la app. Quindi create degli script e li inserite nella cartella hooks, dicendo a cordova di eseguirli. Non useremo mai la cartella hooks. Cartella platforms: La cartella platforms è una delle più importanti e contiene tutti i file che servono ad Android per poter far funzionare la app. Se la aprite vedrete quindi che esiste una cartella android. Noi vedremo questa cartella solo più avanti nel corso. Cartella plugins: La cartella plugins contiene i file di una serie di plugin. Cosa sono i plugin e a cosa servono? I plugin sono dei programmi scritti in due o più linguaggi. Nel caso di android sue linguaggi Javascript e Java. Perché in due linguaggi? Il vantaggio di usare Javascript anziché Java è la semplicità e la portabilità su altre piattaforme. Noi costruiamo la app in Javascript e poi, potenzialmente, possiamo far girare la stessa app su iOS utilizzando sempre cordova. Il problema è che Javascript non può accedere direttamente alle funzionalità del telefono, come la fotocamera, i file interni, etc. Solo i linguaggi nativi possono farlo. Nel caso di Android il linguaggio nativo che viene usato per chiamare quest funzioni è Java. Di conseguenza Javascript deve interfacciarsi con Java e richiamare le funzioni scritte in Java. Per questo il plugin deve avere sia codice Javascrip che codice Java. Nel caso di una app fatta con cordova per iOS i linguaggi in cui è scritto un plugin saranno Javascript e ObjectiveC. Se aprite uno dei plugin all'interno della cartella plugins troverete diverse sottocartelle, ma ce ne sono due di particolare importanza: la cartella src e la cartella www. La cartella www contiene il codice Javascript del plugin. La cartella src contiene il codice scritto in linguaggio nativo. E' solitamente suddivisa in sottocartelle, una per per ogni piattaforma (android, ios, etc). Più avanti nel corso andremo ad analizzare come è fatto un plugin e come se ne può scrivere uno. In generale se volete accedere a qualche funzionalità del cellulare avete due strade: • andare a vedere se esiste un plugin che già lo fa, scaricarlo ed usarlo • corstruire il vostro plugin e usare quello (dovete scriverlo in Javascript e Java) Cartella www: La cartella www è quella che contiene il codice della vostra app scritta con cordova. In generale la vostra app sarà scritta con: Javascript, HTML, CSS. Di conseguenza all'interno della cartella www troverete le sottocartelle: css/ img/ js/ index.html Il file index.html contiene l'html che servirà a costruire il layout della vostra app. La cartella css conterrà i file css che gli daranno un bell'aspetto. La cartella js conterrà i file javaascript che andranno a creare la logca della vostra app. Ecco un esempio di file index.html (prendendo quello creato di default e pulendolo un po'): <html> <head> <meta charset="utf-8" /> <meta name="format-detection" content="telephone=no" /> <meta name="msapplication-tap-highlight" content="no" /> <!-- WARNING: for iOS 7, remove the width=device-width and height=device-height attributes. See https://issues.apache.org/jira/browse/CB4323 --> <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" /> <link rel="stylesheet" type="text/css" href="css/index.css" /> <title>Hello World</title> </head> <body> <div class="app"> <h1>Apache Cordova 2</h1> <div id="deviceready" class="blink"> <p class="event listening">Connecting to Device</p> <p class="event received">Device is Ready</p> </div> </div> <script type="text/javascript" src="cordova.js"></script> <script type="text/javascript" src="js/index.js"></script> </body> </html> Come vedete il codice sovrastante ha un'istruzione per caricare il file css: <link rel="stylesheet" type="text/css" href="css/index.css" /> E due istruzioni per caricare il codice Javascript: <script type="text/javascript" src="cordova.js"></script> <script type="text/javascript" src="js/index.js"></script> La prima carica il codice Javascript di Cordova. La seconda carica il file Javascript che andrete a scrivere voi. Ecco un esempio di file Javascript di partenza su cui lavorare (ho preso il file Javascript creato da cordova e ho tolto delle parti): var app = { // Application Constructor initialize: function() { this.bindEvents(); }, // Bind Event Listeners // // Bind any events that are required on startup. Common events are: // 'load', 'deviceready', 'offline', and 'online'. bindEvents: function() { document.addEventListener('deviceready', this.onDeviceReady, false); }, // deviceready Event Handler // // The scope of 'this' is the event. In order to call the 'receivedEvent' // function, we must explicitly call 'app.receivedEvent(...);' onDeviceReady: function() { }, // Update DOM on a Received Event receivedEvent: function(id) { }; } app.initialize(); Il vostro codice verrà scritto dentro la funzione: // function, we must explicitly call 'app.receivedEvent(...);' onDeviceReady: function() { }, Per lavorare alla vostra app dovete anche pulire il file css creato in automatico da cordova. Quindi aprite il file index.css che sta nella cartella css, selezionate tutto e cancellate, poi salvate. 3 File di configurazione config.xml Guida online: http://docs.phonegap.com/en/4.0.0/config_ref_index.md.html#The%20config.xml %20File Il file config.xml sta nella root della cartella della vostra app e permette di configurare la vostra app. Cordova legge quel file quando lanciate il comando per lanciare la app sul vostro cellulare: cordova run android E' un file xml e ha il seguente aspetto: <?xml version='1.0' encoding='utf-8'?> <widget id="com.example.hello" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0"> <name>HelloWorld</name> <description> A sample Apache Cordova application that responds to the deviceready event. </description> <author email="[email protected]" href="http://cordova.io"> Apache Cordova Team </author> <content src="index.html" /> <access origin="*" /> </widget> Contiene molte cose, tra le quali: Nome della app: <name>HelloWorld</name> Breve descrizione: <description> A sample Apache Cordova application that responds to the deviceready event. </description> L'autore: <author email="[email protected]" href="http://cordova.io"> Apache Cordova Team </author> Il file HTML della vostra app: <content src="index.html" /> L'elenco dei siti esterni a cui può eccedere: <access origin="*" /> Oltre a queste opzioni ne esitono altre. Potete trovare la lista a questo indirizzo: http://docs.phonegap.com/en/4.0.0/guide_platforms_android_config.md.html#Android %20Configuration 3.1 Cambiare l'icona della vostra app Guida online: http://docs.phonegap.com/en/4.0.0/config_ref_images.md.html Per cambiare l'icona della vostra app: navigate nella cartella platform/android e copiate la cartella res. Incollatela nella root della vostra app, dove c'è il file config.xml. Aprite la cartella res, dentro avrete una serie di sottocartelle. Ogni sottocartella si inizia con drawable- e continua con un codice che può essere: ldpi, mdpi, hdpi, xhdpi. Questa è la densità di pixel del vostro device. In base alla densità di pixel che avete, il telefono sceglie da quale cartella prendere l'icona della vostra app. Ad esempio, se avete la densità 1(mdpi), il vostro telefono prenderà l'icona dalla cartella: drawable-mdpi Per specificare di usare quelle cartelle dovete scriverlo nel file config, come mostrato nel seguente codice: <?xml version='1.0' encoding='utf-8'?> <widget id="com.example.icon" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0"> <name>Icone</name> <description> A sample Apache Cordova application that responds to the deviceready event. </description> <author email="[email protected]" href="http://cordova.io"> Apache Cordova Team </author> <content src="index.html" /> <platform name="android"> <icon src="res/drawable-ldpi/icon.png" density="ldpi" /> <icon <icon <icon <icon <icon </platform> src="res/drawable-mdpi/icon.png" density="mdpi" /> src="res/drawable-hdpi/icon.png" density="hdpi" /> src="res/drawable-xhdpi/icon.png" density="xhdpi" /> src="res/drawable-xxhdpi/icon.png" density="xxhdpi" /> src="res/drawable-xxxhdpi/icon.png" density="xxxhdpi" /> <access origin="*" /> </widget> Ad esempio la seguente istruzione: <icon src="res/drawable-mdpi/icon.png" density="mdpi" /> Dice a ad android di usare, nel caso la densità sia mdpi, il file res/drawable-mdpi/icon.png Le cartelle che finiscono in xxhdpi e xxxhdpi non esistono, bisogna crearle. Le dimensioni delle icome per le varie risoluzioni sono le seguenti: 36x36 (0.75x) for low-density (cartella ldpi) 48x48 (1.0x baseline) for medium-density (cartella mdpi) 72x72 (1.5x) for high-density (cartella hdpi) 96x96 (2.0x) for extra-high-density (cartella xhdpi) 180x180 (3.0x) for extra-extra-high-density (cartella xxhdpi) 192x192 (4.0x) for extra-extra-extra-high-density (cartella xxxhdpi) 4 Splash screen Guida online: http://docs.phonegap.com/en/4.0.0/config_ref_images.md.html Lo spashscreen è quell'immagine che compare sullo schermo mentre aspettate coem la vostra app carichi. Lo splash screen si imposta nello stesso modo in cui si imposta l'icona, specificando nel file config.xml i percorsi dei vari file. Anche in questo caso esiste una cartella per ogni risoluzione, solo che questa volta per ogni risoluzione dovete specificare due file, uno nel caso in cui il device sia "verticale" (portrait) e una in cui sia "orizzontale" (landscape). I file di splashscreen vanno sempre messi nella cartella res (se l'avete copiata dalla cartella platform/android avrà già le varie cartelle, basta creare quelle per xxhdpi e xxxhdpi) Ecco un esempio di configurazione: <preference name="SplashScreen" value="screen" /> <platform name="android"> <!-- you can use any density that exists in the Android project --> <splash src="res/drawable-port-hdpi/screen.png" density="port-hdpi"/> <splash src="res/drawable-port-ldpi/screen.png" density="port-ldpi"/> <splash src="res/drawable-port-mdpi/screen.png" density="port-mdpi"/> <splash src="res/drawable-port-xhdpi/screen.png" density="port-xhdpi"/> <splash <splash <splash <splash </platform> src="res/drawable-land-hdpi/screen.png" density="land-hdpi"/> src="res/drawable-land-ldpi/screen.png" density="land-ldpi"/> src="res/drawable-land-mdpi/screen.png" density="land-mdpi"/> src="res/drawable-land-xhdpi/screen.png" density="land-xhdpi"/> L'struzione: <preference name="SplashScreen" value="screen" /> Serve a definire il nome del file di splashscreen, in questo caso screen.png 4.1 Sulle dimensioni delle immagini di splash Approfondimento android: http://developer.android.com/guide/practices/screens_support.html Ecco una lista delle dimensioni dei vostri splashscreens: • LDPI: Portrait: 200x320px. Landscape: 320x200px. • • • • • MDPI: Portrait: 320x480px. Landscape: 480x320px. HDPI: Portrait: 480x800px. Landscape: 800x480px. XHDPI: Portrait: 720px1280px. Landscape: 1280x720px. XXHDPI: Portrait: 960px1600px. Landscape: 1600x960px. XXXHDPI: Portrait: 1280px1920px. Landscape: 1920x1280px.