Sviluppatori BlackBerry

BBUI.JS e’ un progetto opensource ospitato su github (https://github.com/blackberry/bbUI.js/), che mira a rendere semplice la realizzazione di apps WebWorks con aspetto e caratteristiche uguali a quelle di un’applicazione nativa per BlackBerry.

Per realizzare questo, BBUI.JS mette a disposizione un set di controlli customizzati realizzati con css e javascript.
Alcuni dei vantaggi dall’utilizzo di questa libreria sono:

• look&feel di un’applicazione BB10 nativa.
• gestione delle schermate applicative, chiamati screens, in file HTML separati.
• gestione a stack delle schermate (push/pop)
• supporto risoluzioni device BB10 (ma non solo) automatico: al momento per Z10 e Q10.

L’elenco dei componenti utilizzabili e’ qui: https://github.com/blackberry/bbUI.js/wiki

Creazione di un progetto
Collegatevi alla pagina github di bbuijs e scaricate l’ultima versione disponibile della libreria.
All’interno della libreria scaricata c’e’ una cartella “samples” che rappresenta un piccolo progetto di test con tutti i componenti di BBUI.JS disponibili.
Copiate la directory samples nella vostra directory RippleSites.
Aprite Chrome e provate ad eseguire il tutto su Ripple.

Possiamo usare la directory “samples” come base per i nostri futuri progetti WebWorks, facendo un po’ di pulizia tra i file dentro samples:

• rimuovere tutti i file con estensione .htm ad eccezione di index.htm
• rimuovere immagini inutili dalla directory images: le directory avatars, grid , images_list, menu_icons, inboxList, slider, tabs possono essere rimosse. Eventualmente nell’utilizzo di qualche componente verificaste qualche mancanza di immagini, dalla console di chrome dovreste individuare un messaggio di errore con le immagini mancanti per poterle riaggiungere.
• rimpiazzare icona, splashscreen dentro la directory images.
• cambiare alcuni parametri del file config.xml , in particolare autore , id dell’applicazione, descrizione, versione etc (vedi tut.2) .
• rinominate la directory samples in qualcosa di piu’ sensato per il progetto che state realizzando.
• ricordate di avere il progetto nella directory RippleSites.

Il progetto sample utilizza il file index.htm come pagina di partenza.
Aprite il file index.htm con un editor di testo a vostra scelta: notepad, gvim, jedit o se preferite usate qualcosa di piu’ complesso come Aptana.
Dentro il file index.htm ci sono diverse sezioni che per ora ignoreremo: fate una ricerca per la stringa “pushScreen“.
Dovreste trovare una riga come la seguente nella pagina:

bb.pushScreen(‘menu.htm’, ‘menu’);

cambiamola in

bb.pushScreen(‘home.htm’, ‘home’);

All’interno dell’index.htm questa riga definisce quale pagina/screen deve essere chiamata al lancio dell’applicativo.
Dobbiamo immaginare che la nostra applicazione sia composta come una pila di schermate su cui agiamo con le operazioni popScren e pushScreen.

Ogni volta che eseguiamo un pushScreen, aggiungiamo una schermata alla lista e la mettiamo in cima.
Ogni volta che eseguiremo un popScreen, andiamo a togliere il primo elemento della lista.

La nostra applicazione visualizza sempre le schermate in cima alla pila di schermate.

Creiamo nella cartella un nuovo file home.htm con il seguente contenuto:

<div data-bb-type="screen" data-bb-effect="fade" style="background-color: white">

		<div data-bb-type="panel-header" >
		Hello BBDevs.com!	
	</div>
	<div data-bb-type="action-bar">
		<div data-bb-type="action"  data-bb-img="ic_info.png" data-bb-style="button" onclick="bb.pushScreen('credits.htm');">Credits</div>
	</div>
</div>

Qua non abbiamo fatto altro che mostrare un messaggio sullo schermo e renderlo uno screen adatto per BBUI.JS.

Abbiamo inoltre aggiunto un pulsante che come azione prevede il passaggio alla schermata dei credits.
Creiamo ora un secondo file credits.htm con il seguente contenuto:

<div data-bb-type="screen" data-bb-scroll-effect="on">
	<div align="center">
		<h2>Informazioni e Disclaimer</h2>
	</div>

	<h3>APP per il Terzo Tutorial di BBDevs.com sul come scrivere un app per WebWorks da 0.</h3>

	<div data-bb-type="action-bar" data-bb-back-caption="Back">
	</div>
</div>

La seguente riga del file credits.htm

<div data-bb-type="action-bar" data-bb-back-caption="Back"> </div>

indica a bbui.js di inserire nella schermata la barra standard in basso di BB10 che permette di tornare alla schermata precedente.

Il comportamento di default di questa barra è quello di richiamare popScreen, quindi anche se non lo vediamo esplicitamente riportato, è perchè BBUI.JS se ne occupa per noi.
Il resto delle pagine.. per ora è semplice HTML

Questa e’ solo un’introduzione, nel prossimo tutorial vedremo come realizzare qualcosa di piu’ complesso che utilizza BBUIJS.

Se avete domande o suggerimenti, nei commenti grazie

Il config.xml è un file di configurazione applicativo utilizzato all’interno di ogni applicazione BB10 in WebWorks, per dare al sistema operativo informazioni su:

• come dovrà presentarsi/comportarsi l’applicazione una volta installata: icona, splashscreen iniziale, descrizione, autore , orientamento etc.
• quali risorse dovrà utilizzare e quindi quali permessi richiedere all’utente di autorizzare. Es. accesso alla Fotocamera, a BBM etc
• quali sono i domini/indirizzi su cui potrà accedere: e questo presumo per motivi di sicurezza, si possono specificare un set di domini a cui l’applicazione potrà accedere.

Per facilitare la lettura ho preparato 2 immagini con la spiegazione

e la seconda parte

Da notare che queste informazioni sono da ritenersi valide solo per app BlackBerry 10 e dispositivi Z10 e Q10.

Per le specifiche della icona della app potete guardare qua: https://developer.blackberry.com/devzone/design/bb10/application_icons.html

Lo splashscreen, in caso di applicazione per Z10 deve valere 1280×768 (in caso di landscape) o 768×1280 (in caso di visualizzazione portrait).

Per Q10 c’è solo l’orientamento portrait, e lo splashscreen deve essere 720×720.

Potete specificare piu’ sezioni “splash” una sotto l’altra nel config.xml e il sistema operativo all’avvio dell’app sceglierà il piu’ opportuno.

Tenete a mente che quanto detto sulle risoluzioni puo’ cambiare nel tempo in quanto si attendono device futuri che avranno risoluzione 1280×720 e per i quali dovrete informarvi attraverso la documentazione ufficiale.

Potrete anche specificare come dominio nell’access il seguente

che dichiara che l’applicazione vuole accedere a qualsiasi sito ma, per ragioni di sicurezza solo per i domini esplicitamente dichiarati (come nel nostro esempio), sara’ possibile effettuare chiamate XMLHttpRequest/Ajax. Maggiori dettagli sull’argomento qui: https://developer.blackberry.com/html5/documentation/securing_your_ww_app_1866986_11.html

In allegato anche l’xml completo usato nel tutorial:

Config.xml

L’elenco di tutti i parametri e dei valori ammessi in config.xml e’ disponibile qui:

https://developer.blackberry.com/html5/documentation/config_doc_elements.html

Se avete domande o suggerimenti per migliorare l’articolo, scrivete nei commenti!

Grazie a: Fabrizio C., Angelo G. e Aniello D.S. per i feedbacks e miglioramenti.

Questo è il primo di una serie di tutorial collegati tra loro per guidarvi nello sviluppo di un applicazione per BlackBerry10 utilizzando WebWorks.

Lo scopo è quello di affrontare i passi chiave per sviluppare un applicazione da zero e terminerà con la pubblicazione su app world blackberry dell’app realizzata nei vari tutorial.

Ricordate che con l’app realizzata potrete partecipare al contest: http://www.bbdevs.com/site/blackberry-10-app-contest/

Prerequisiti

• Avere installato i tool di webworks: http://www.bbdevs.com/site/tutorials/iniziare-a-sviluppare-per-blackberry-10-con-webworks-i-tools/
• Avere conoscenza di HTML/CSS/Javascript
• Scaricare il template realizzato per i progetti webworks: mobtemplate

Scompattate l’archivio e copiatelo nella directory RippleSites.

Lanciare il progetto

Il progetto template contiene:

1. un file di configurazione config.xml che viene usato: da webworks e da BB10 e contiene informazioni sull’app che andiamo a realizzare; ad esempio contiene il nome dell’icona e dello splashscreen all’interno del progetto e del file html da eseguire al lancio dell’applicazione. Vedremo in dettaglio in altro tutorial l’importanza di questo file.
2. un file index.html con una pagina di sample.
3. jquery e un file mobile.css.

Andate nella cartella RippleSites/mobtemplate e aprite il file index.html dentro Chrome: 

Cliccare ora sull’icona di Ripple Emulator e premere su Start Ripple Services, la freccia rossa in figura, questo attiverà un piccolo web server.

Il webserver  utilizza come ROOT la directory RippleSites e quindi il vostro progetto dovrebbe essere raggiungibile qui http://localhost:9910/mobtemplate/index.html . Aprite la pagina e cliccate nuovamente sul Ripple Emulator, quindi questa volta premete su Enable.

Vi verrà chiesto come Ripple dovrà intepretare il progetto, selezionate BlackBerry WebWorks e dovreste avere questo risultato:

Ok non è molto per ora, ma consiglio di spulciare nel file index.html e config.xml del template per farsi un’idea di come è organizzato questo progetto template.

Seguirà presto un altro tutorial, se avete dubbi, domande, suggerimenti scriveteci nei commenti!

Per implementare il servizio bastano sei semplici step:

1 – Creare un nuovo progetto Cascades

2 – Aprire il file “nomeapp.pro” del vostro progetto, inserire la seguente stringa

“LIBS += -lbbcascadesadvertisement”

salvare e chiudere il file.

3 - Aprire il file “bar-descriptor.xml”,  nella scheda applicazioni, selezionare Device Identifying Information e facoltativamente GPS Location per gli annunci basati sulla localizzazione, salvare e chiudere il file.

4 – Nel file Qml che visualizzerà il Banner inserire il seguente codice:

import bb.cascades.advertisement 1.0 (all’inizio del file)

ed in un Container

Banner {
zoneId: 117145 //ZoneID di esempio per i test
refreshRate: 60
preferredWidth: 320
preferredHeight: 50
transitionsEnabled: true

//immagine da visualizzare in caso non ci sia un banner da visualizzare
placeHolderURL: “asset:///images/placeholder.png”
backgroundColor: Color.Green
borderColor: Color.Gray
borderWidth: 2
horizontalAlignment: HorizontalAlignment.Center
}

5 – Aggiungere il codice in grassetto al file main.cpp

#include <bb/cascades/advertisement/Banner>

ed in Q_DECL_EXPORT int main(int argc, char **argv)
{

…

qmlRegisterType<bb::cascades::advertisement::Banner>(“bb.cascades.advertisement”, 1, 0, “Banner”);

…

}

salvare e chiudere il file.

6 – Quando l’App è pronta, richiedere il proprio ZoneID al seguente link:

https://adservices.blackberry.com/

Aprire il file Qml che contiene il Banner e sostituire il zoneID di prova con quello definitivo ricevuto da AdService, salvare e chiudere il file.

E questo è tutto.

Facile ed indolore.

Questa guida e’ stata pensata per i nuovi sviluppatori BlackBerry10 e raccoglie alcuni suggerimenti, per chi si sta avvicinando alla piattaforma.

La guida e’ piu’ centrata sullo sviluppo nativa con Cascades/Qt/Qml ma alcuni consigli possono tornare utili anche per chi ha scelto lo sviluppo con WebWorks.

Logging
Il logging della nostra applicazione e’ fondamentale per capire se la nostra applicazione si sta comportando come ci aspettiamo.
E’ la forma piu’ rudimentale di debugging… e a volte si rileva piu’ che sufficiente per scovare i bug nelle nostre applicazioni.
I metodi di Logging su C++ e QT usano funzioni differenti.
Su C++ e’ possibile usare la funzione qDebug():

Possiamo utilizzare qDebug() con l’operatore “<<” per sfruttare l’operazione di append.
Es:  qDebug() << “str1″ << “str2″;

Su QML abbiamo invece la funzione console.log(stringa);

Per poter vedere le stringhe di log inserite nella nostra applicazione una volta che questa risulta in esecuzione, dobbiamo collegarci al nostro dispositivo via SSH.
Possiamo eseguire la connessione SSH al terminale attraverso una modalita’ presente nell’ ambiente qde:

Effettuata la connessione avrete un terminale connesso al telefono,se avete dimestichezza con linux o il terminale del mac vi sentirete a casa, da cui potete usare alcuni comandi.
Quello che ci interessera’ utilizzare e’ slog2info -w il cui risultato e’ visibile nelle figure sotto:

SSH: non solo per i log!
Come gia’ detto una volta che avete accesso al terminale potete utilizzare alcuni dei comandi disponibili:
- pwd: mostra il percorso della directory corrente
- cd: cambia la directory corrente
- cat: mostra il contenuto di un file di testo
- ls: lista i file presenti nella directory corrente
Ci sono anche alcuni altri comandi.. come in un ambiente unix (e’ QNX d’altronde ).
Con i 4 comandi precedentemente illustrati potrete gia’ fare alcune cose interessanti.. per esempio vedere il contenuto di un file che la vostra applicazione ha creato.
Bastera’ muoversi con il comando “cd” nella directory /accounts/1000/appdata/, quindi usare il comando ls per visualizzare l’elenco delle applicazioni installate

e usare il comando “cat” su un file creato da noi.

Aggiornare il Debug Token
Se avete un device su cui sviluppare, sia un devalpha o un telefono BlackBerry 10, avrete sicuramente generato un token di sviluppo.
Il token non ha durata illimitata e quindi ogni tanto vi tocchera’ aggiornarlo.
Potrete aggiornarlo a mano… ma  potete usare QDE, cosi’:

Tasto destro sul device USB, poi selezionate Blackberry Tools e quindi Debug Token Details, vi apparira’ la seguente finestra: