P4A3 framework: il widget Countdown rinnovato e con funzione timer

Questo widget per il framework P4A è l’aggiornamento di quello descritto in questo post.
L’aggiornamento deriva dal fatto che la nuova versione del codice originale per jQuery, presenta cambiamenti importanti e ha richiesto la riscrittura di una buona parte del widget. La versione del Countdown for jQuery attualmente installata è la 1.4.3.

Ho pensato di cogliere l’occasione per rendere un poco più interattivo il widget, facendo scattare un evento gestibile dall’utente attraverso un metodo personalizzato, allo scadere del contatempo. Inoltre, ho utilizzato l’integrazione di P4A con i18n, per impostare automaticamente la lingua per gli output delle etichette e il formato della data e dell’ora.

Questo è l’elenco dei metodi fino ad esso implementati:

Elenco dei metodi:
Nome	Tipo	Default	Note
`setSince()`	integer	"`null`"	Imposta la data e l’ora di avvio in formato UNIX timestamp
`setUntil()`	integer	"`null`"	Imposta la data e l’ora di stop in formato UNIX timestamp.
`setDisplayFormat()`	string	"`dHMS`"	‘Y’ anni, ‘O’ mesi, ‘W’ settimane, ‘D’ giorni, ‘H’ ore, ‘M’ minuti, ‘S’ secondi. I caratteri minuscoli impostano la visualizzazione opzionale
`setCompactFormat()`	string	"`false`"	Imposta il formato ridotto.
`setDescription()`	string	""	Imposta la descrizione del contatempo.
`setServerTime()`	string	`null`	Imposta l’offset per il fuso orario. Valori di esempio: ‘+1’, ‘+2’, ‘+3’, ‘-1’, ‘-2’, ‘-3’. etc.
`setLayout()`	string	`''`	Imposta un layout personalizzabile attraverso tag HTML e parametri per esprimere la data e l’ora. Le singole sezioni sono delimitate da %x…%x, dove x è ‘Y’ per definire gli anni, ‘O’ per i mesi, ‘W’ per le settimane, e ‘D’ per i giorni, ‘H’ per le ore, ‘M’ per i minuti, e ‘S’ per i secondi. All’interno di queste sezioni, è possibile utilizzare ‘%n’ per determinare il valore del periodo, ‘%nn’ per il valore con un minimo di due caratteri, e ‘%l’ per l’etichetta del periodo (in accordo con quanto impostato in `setCompactFormat()`).
`setlocale()`	string	`'auto'`	Imposta un valore per la regionalizzazione. Per default viene presa l’impostazione di `P4A_LOCALE`. In alternativa è possibile impostarla manualmente. Le traduzioni disponibili sono: Chinese – Simplified “zh-CN”, Chinese – Traditional “zh-TW”, Czech “cs”, Danish “da”, Dutch “nl”, French “fr”, German “de”, Hebrew “he”, Hungarian “hu”, Indonesian “id”, Italian “it”, Norwegian “nb”, Persian/Farsi “fa”, Polish “pl”, Portuguese/Brazilian “pt-BR”, Romanian “ro”, Russian “ru”, Slovak “sk”, Spanish “es”, Swedish “sv”, Turkish “tr”, Ukranian “uk”
`setPauseResumeType()`	string	`null`	Se impostato con i valori: “lap” o “pause” mostra un pulsante che ferma o riavvia il contatempo. “lap” ferma solo la visualizzazione, “pause” ferma anche il conteggio. Se `null` il pulsante non viene mostrato.
`setPauseResumeLabels()`	string	`'pause,resume'`	Imposta le etichette per il pulsante “Pause/resume”. I valori per l’azione toggle devono essere separati da una virgola.
`onExpiry()`	boolean	`false`	Imposta se deve scattare un evento allo scadere del countdown (funziona solo quando è impostato `setUntil()`).
`setMessageOnExpire()`	string	`""`	Imposta il testo del messaggio che viene visualizzato allo scadere del countdown.
`messageOnExpire()`	void	void	Se è impostato un messaggio, lo mostra e restituisce un handle per l’evento `actionOnExpire`. Questo metodo viene attivato quando `onExpiry(true)`

Ecco un po’ di codice di esempio per inserire il contatempo in una maschera e utilizzare l’evento actionOnExpire:

class test_countdown extends p4a_base_mask
{
 public function __construct()
 {
   parent::__construct();
   $this->setTitle("test Countdown");
   $this->build("P4A_jCountdown", "countdown")
    ->setStyleProperty("width","400px")
    ->setStyleProperty("float","none")
    ->setStyleProperty("margin","auto")    
    ->setDescription("test countdown")
    ->countdown->setUntil(time()+11)
    ->countdown->onExpiry(true)
    ->countdown->setMessageOnExpire("Il tempo e' scaduto!");
 
    $this->countdown->implement('actionOnExpire',$this,'show');
 
    $this->frame->anchorCenter($this->countdown);
  }
 
	public function show ()
	{
		$this->info("Questa e' una prova!");
		//Enable code below for looping
		//$this->countdown->setUntil(time()+11);
	}
 
}

~~Il pacchetto completo della maschera di esempio è scaricabile qui~~

Note:

L’impostazione di setLocale() non è in genere necessaria per il fatto che quando viene “costruito” il contatempo la regionalizzazione viene individuata automaticamente. Nel caso si volesse impostare questo parametro manualmente, si consiglia di non cambiarlo successivamente a run-time. Questo perché è stato scelto di caricare l’intero set di impostazioni per la regionalizzazione tramite codice javascript esterno, mediante files di libreria. Per questo metodo quindi, i cambiamenti a run-time generano codice non pulito, che sconsiglio, almeno fino a che non trovo il tempo di migliorare questa soluzione.
Come nella precedente versione, è consigliabile aggiungere un secondo quando si utilizza:->setUntil() e decrementare di un secondo quando si utilizza ->setSince(time())per evitare una non perfetta sincronizzazione fra il tempo in cui viene mostrato il widget e lo scattare del conteggio.
Infine è possibile rendere invisibile il widget, semplicemente con ->setVisible(false) e mantenere attivo il contatempo. Questo permette di utilizzare comunque l’handle per l’evento actionOnExpire anche senza visualizzare il widget.

Conclusioni:

Questi ultimi giorni sono stati davvero impietosi con il mio (già scarso) tempo libero, e non ho potuto sviluppare il codice come avrei voluto… spero di poterci dedicare ancora del tempo, perché mi sembra un progetto interessante e, spero utile a molti. Ci sono ancora alcune caratteristiche da integrare e miglioramenti da fare nel codice, spero nell’aiuto degli utenti! Nel frattempo cercherò anche di ampliare e migliorare la documentazione (già presente nel pacchetto).

Riferimenti ed approfondimenti:

jQuery Countdown
P4A – PHP for applications
P4A 3
development blog