Creare un'applicazione per Facebook in PHP

In un precedente articolo abbiamo introdotto i lettori alla creazione di applicazioni per Facebook, descrivendo le principali peculiarità dell'API fornita dal servizio e del linguaggio FBML. In questo articolo andremo ad ampliare i nostri orizzonti vedendo nel dettaglio la creazione di una vera applicazione, cercando spunti e soluzioni che possano essere utili in una situazione reale. L'applicazione creata è anche scaricabile dal link Download in alto in questa pagina.

Riprendendo quanto visto a conclusione del primo articolo, ricordiamo che Facebook propone delle linee guida per costruire applicazioni di qualità. In particolare, si richiede che un'applicazione sia significativa, fidata e ben disegnata. L'essere significativa dipende chiaramente dalla creatività dello sviluppatore, che deve trovare il modo di proporre un'idea utile, espressiva e sociale. Da questo punto di vista un aspetto importante è il coinvolgimento del grafo degli amici, oltre alla possibilità di esprimere informazioni sulla propria personalità. La Facebook API ci fornisce il necessario per interagire con gli altri utenti, mediante l'uso di notifiche o semplicemente pubblicando informazioni sul nostro profilo.

Un altro aspetto importante quando si progetta un'applicazione riguarda la sua integrazione con lo stesso Facebook dal punto di vista grafico. Colori e stili utilizzati da Facebook vengono parzialmente resi noti sul Wiki degli sviluppatori, e la questione viene approfondita meglio in un articolo di SocialSnippets.com. Oltre a creare un foglio di stile che vada ad imitare l'originale di Facebook, è inoltre possibile utilizzare nella propria applicazione anche gli stili originali del servizio, ma purtroppo questa opzione non è adeguatamente documentata.

Un ulteriore aspetto da curare, per dare una maggiore visibilità alla nostra applicazione e quindi aumentarne le probabilità di successo, riguarda l'internazionalizzazione: è opportuno valutare a monte la possibilità di tradurre l'applicazione in più lingue. A questo scopo, ci viene incontro l'applicazione Translations, da installare preliminarmente nel nostro account da sviluppatore, che si appoggia ad alcuni tag FBML rendendo il nostro lavoro relativamente semplice.

Con una semplice applicazione di esempio, vediamo ora come mettere insieme i vari pezzi del mosaico per ottenere un risultato finale soddisfacente. L'applicazione in questione consente di gestire una lista dei propri obiettivi da raggiungere, mostrando sul proprio profilo le scadenze e gli obiettivi raggiunti. Per visualizzare il comportamento dell'applicazione è necessario aggiungerla al proprio profilo, visitando l'indirizzo http://apps.facebook.com/htmlit-goal. Nei paragrafi che seguono viene discusso lo sviluppo dell'applicazione.

Creare una nuova applicazione

Assumendo di aver già installato le applicazioni Developers e Translations, procediamo con la registrazione della nuova applicazione come descritto nel primo articolo. Questo primo passo ci consente di ottenere i due codici API Key e Secret (nella versione in italiano: Chiave API e Invisibile) necessari per interfacciarsi con la Facebook Platform. I parametri importanti da specificare sono i seguenti:

• Nome dell'applicazione: HTML.it Goal;
• Callback URL: il nostro spazio web dove risiede l'applicazione;
• Canvas Page URL: l'indirizzo per identificare l'applicazione su Facebook, nel nostro caso http://apps.facebook.com/htmlit-goal;
• Can your application be added on Facebook? Yes: parametro fondamentale per consentire agli utenti di aggiungere l'applicazione nel proprio profilo;
• Nome e indirizzo Tab: l'etichetta e la relativa pagina web da associare alla scheda che un utente può aggiungere al proprio profilo. Nel nostro caso, utilizziamo Goal come nome e tab.php come indirizzo: ci serviranno per approfondire l'integrazione dell'applicazione con gli account dei nostri futuri utenti;

Per quanto riguarda gli aspetti di internazionalizzazione, è bene partire utilizzando la lingua inglese, English (US), ed andare a tradurre successivamente le varie stringhe con l'applicazione Translations. Anche nella descrizione dell'applicazione, utilizziamo inizialmente la lingua inglese. Teniamo presente che l'applicazione Developers ci consente di correggere in un secondo momento i dati che abbiamo inserito. A questo punto, una volta registrata l'applicazione saremo in possesso dei due codici API Key e Secret.

Primi passi nell'implementazione

Prima di procedere con l'implementazione del cuore della nostra applicazione, assicuriamoci di creare la cartella specificata come Callback URL nel nostro spazio web, e di copiarci tutti i sorgenti della PHP Facebook Client Library.

Per quanto riguarda gli obiettivi che i nostri utenti gestiranno, le informazioni verranno memorizzate nella seguente tabella MySQL:

CREATE TABLE goal ( 
    goal_id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, 
    user_id BIGINT UNSIGNED, 
    goal_date DATE , 
    goal_deadline DATE, 
    goal_title VARCHAR(250), 
    goal_status INT  
);

• goal_id è la chiave primaria;
• user_id è una chiave esterna per memorizzare l'ID dell'utente, il campo BIGINT in MySQL è necessario in quanto Facebook utilizza interi a 64 bit;
• goal_date è la data in cui l'obiettivo viene inserito;
• goal_deadline è la data di scadenza entro cui si vuole raggiungere l'obiettivo. Se il campo viene lasciato nullo, assumiamo che non ci siano scadenze;
• goal_title descrive l'obiettivo;
• goal_status rappresenta lo stato dell'obiettivo (per ora: 1 = Raggiunto, -1 = Fallito, 0 = In svolgimento); in questo caso potrebbe essere sufficiente anche un TINYINT come tipo di dato.

Per gestire il caricamento della PHP Facebook Client API, la connessione a MySQL ed eventuali altre operazioni preliminari, creiamo un file init.php da includere all'inizio di tutti gli altri script, a cui deleghiamo tali operazioni. Se la complessità dell'applicazione dovesse aumentare, probabilmente è opportuno inserire tutti i dati di configurazione in un file config.php e lasciare solo le operazioni preliminari in questo init.php, ma per ora non abbiamo problemi di complessità. I dati della connessione e dell'applicazione vanno naturalmente sostituiti con i propri.

<php
/**
 * init.php
 */

// Carico PHP Facebook Client Library
require_once 'facebook.php'; 

// Dati connessione 
$dbhost = 'localhost'; 
$dbuser = 'root'; 
$dbpass = ''; 
$dbname = 'mio-db'; 

// Creazione oggetto $facebook 
$appapikey = 'mia-api-key'; 
$appsecret = 'mio-codice-secret'; 
$facebook = new Facebook($appapikey, $appsecret); 
if (!isset($_REQUEST['fb_sig_in_profile_tab'])) {
    $user_id = $facebook->require_login();
}
// Connessione MySQL 
$db = @mysql_connect($dbhost, $dbuser, $dbpass) or die('mysql_connect() error: ' . mysql_error()); 
@mysql_select_db($dbname) or die('mysql_select_db() error: ' . mysql_error()); 

?>

Oltre a gestire la connessione a MySQL che ci servirà interfacciarci con il database, l'unica novità nel codice riguarda un controllo sulla variabile $_REQUEST['fb_sig_in_profile_tab'] che fa parte di un gruppo di variabili passati da Facebook alla nostra applicazione e che viene valorizzata ad 1 se l'applicazione è richiamata dal relativo Tab nel profilo. In tal caso, non è necessario effettuare il login con la funzione require_login().

Un'occhiata al codice dell'applicazione

Scaricando il codice dell'applicazione possiamo quindi analizzarne le scelte implementative. L'allegato comprende i seguenti file:

• index.php è la pagina principale dell'applicazione, da cui l'utente ha un riepilogo dei suoi obiettivi e può decidere di aggiungerne altri, o cancellare/modificare quelli presenti;
• add.php è la pagina per aggiungere i nuovi obiettivi;
• mod.php è la pagina di modifica;
• del.php è la pagina di eliminazione;
• init.php è il file che gestisce configurazione ed operazioni iniziali;
• tab.php è la pagina richiamata dal profilo utente;
• fb.css è il foglio di stile, preso dall'articolo di SocialSnippets.com a cui è stata fatta una piccola modifica per la classe fbth (uguale a fbtab ma senza proprietà di floating) da utilizzare nei tag <th>;
• create_table.sql è il codice SQL per creare la tabella nel database.

Analizzando ad esempio la pagina index.php, notiamo come la gestione dei fogli di stile non consenta l'uso di CSS esterni, anche se lo sviluppo di Facebook Platform si sta muovendo verso questa direzione. Comunque, per utilizzare il nostro fb.css come foglio di stile esterno, è necessario in realtà leggerne il contenuto all'interno di un normale tag <style>:

echo '<style type="text/css">' . file_get_contents('fb.css', true) . '</style>';

Le classi definite nello stile vengono sfruttate nelle diverse pagine. Per quanto riguarda i form, abbiamo preferito sfruttare lo stile di alcune classi predefinite in Facebook. Ciò è visibile ad esempio in add.php oppure mod.php, dove si nota l'uso delle seguenti classi CSS:

• editor: applicato alla tabella che contiene gli elementi del form;
• text: applicato alle righe della tabella che contengono campi testuali;
• select: applicato alle righe della tabella che contengono menù a tendina;
• label: applicato alle celle che contengono un'etichetta;
• inputtext: applicato ai tag <input /> di tipo text;
• button: applicato ai pulsanti;
• inputsubmit: applicato ai tag input di tipo submit;

Internazionalizzazione

Nei vari file dell'applicazione è possibile vedere come sia stata utilizzata in modo rigoroso una metodologia per poter tradurre la propria applicazione in più lingue. A monte, creando la nuova applicazione abbiamo definito l'inglese come lingua principale. Nel codice invece facciamo largo uso del tag <fb:intl> che nasce proprio con questo scopo: al suo interno inseriamo le parti testuali in inglese, che potremo poi tradurre utilizzando l'applicazione Translations, la quale tra l'altro consente anche ai nostri utenti di partecipare al progetto di traduzione. Per contenuti testuali particolarmente corti e non auto-esplicativi, è possibile utilizzare un attributo desc per aggiungere una descrizione relativa al testo da tradurre. Nel Wiki degli sviluppatori sono presenti dei suggerimenti che è opportuno seguire per predisporre al meglio il codice con il fine di consentire una più agevole traduzione.

Altri aspetti legati all'internazionalizzazione ruotano attorno alla gestione del tempo: da questo punto di vista, il tag <fb:date> ci consente di formattare una data in base alla localizzazione dei nostri utenti. L'input di questo tag consiste in un timestamp in formato Unix, creato quindi con la funzione mktime() e passato attraverso l'attributo t. Con l'attributo format specifichiamo invece il formato della data, come descritto nel Wiki.

Link di approfondimento

Concludiamo questa serie di articoli con dei link per approfondire quanto analizzato in queste pagine. Per la panoramica completa sull'API e sul linguaggio FBML rimandiamo naturalmente al Wiki ufficiale.

Fogli di stile:

• Articolo su SocialSnippets per creare un CSS simile allo stile di Facebook
• Indicazioni sui CSS di Facebook
• Trucchi e consigli sui CSS in Facebook
• Stili e colori utilizzati da Facebook

Internazionalizzazione:

• Tradurre le applicazioni per Facebook Platform
• Best Practices nella traduzione di applicazioni per Facebook