P4A3 framework: il widget Countdown rinnovato e con funzione timer

Widget p4a CountdownQuesto 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:
NomeTipoDefaultNote
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()stringnullImposta 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()stringnullSe 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()booleanfalseImposta 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()voidvoidSe è 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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: