Valutazioni (Ratings)
Introduzione
Il modulo Ratings (Valutazioni) permette agli sviluppatori di moduli di aggiungere
in modo semplice valutazioni e votazioni alle voci dei vari moduli. Questo modulo
non ha una chiamata diretta, ma è un programma di utilità chiamato
all'interno di altri moduli per espandere la loro funzionalità.
Funzioni API
Le API del modulo contengono le seguenti funzioni:
display
display fornisce una stringa in uscita per visualizzare la valutazione
corrente di una certa voce. Le variabili usate da questa funzione sono:
modname - il nome del modulo sottoposto a valutazione
itemid - la voce del modulo che viene valutata
ratingtype - il tipo di valutazione (opzionale)
style - lo stile di visualizzazione della valutazione (opzionale).
Può assumere le seguenti forme:
percentage - valutazione in forma percentuale
outoffive - valutazione da 1 a 5
outoffivestars - valutazione da 1 a 5 usando le stelline
outoften - valutazione da 1 a 10
outoftenstars - valutazione da 1 a 10 usando le stelline
Questa funzione restituisce una stringa si output se la valutazione è
definita nel sistema, altrimenti ritorna void.
ask
ask fornisce una stringa in uscita che chiede una valutazione di una qualche
voce definita. Le variabili usate dalla funzione sono:
modname - il nome del modulo del quale si chiede una valutazione
itemid - la voce del modulo del quale si chiede una valutazione
ratingtype - il tipo di valutazione (opzionale)
returnurl - l'URL da restituire dopo aver ottenuto la valutazione
style - lo stile in cui è presentata la richiesta di valutazione
(opzionale). Vedere sopra gli stili disponibili.
Questa funzione ritorna una stringa adeguata se l'utente è autorizzato
a valutare, altrimenti ritorna void.
Esempi
L'esempio seguente mostra come usare le funzioni fornite da queste API. L'esempio
mostra l'uso delle API col modulo degli articoli 'News' e usa la variabile sid
come identificativo della voce da valutare.
// Mostrare le valutazioni per un articolo
if (pnModLoad('Ratings')) {
$rating = pnModFunc('Ratings',
'user',
'display',
array('modname' => 'News',
'itemid' => $sid));
if (isset($rating)) {
$output->Text('Valuta questo articolo: ');
$output->SetInputState(_PNH_VERBATIMINPUT);
$output->Text($rating);
$output->SetInputState(_PNH_PARSEINPUT);
}
$askrating = pnModFunc('Ratings',
'user',
'ask',
array('modname' => 'News',
'itemid' => $sid,
'returnurl' => pnModURL('News',
'user',
'display',
array('sid' => $sid))));
$output->SetInputState(_PNH_VERBATIMINPUT);
$output->Text($askrating);
$output->SetInputState(_PNH_PARSEINPUT);
}
Autorizzazioni
Le autorizzazioni del modulo Ratings sono le seguenti:
Componente
La componente è semplicemente 'Ratings::'
Instanza
L'istanza è 'NomeModulo:TipoValutazione:IDVoce'. La descrizione dei
termini:
NomeModulo - il nome del modulo come è stato passato nel
modname alle funzioni display e ask dette sopra
TipoValutazione - il tipo di valutazione usato, come passato nel
ratingtype alle funzioni display e ask dette sopra.Se
non viene passato un vlore, allora sarà 'default'
IDVoce - l'ID specifico della voce del modulo che viene valutata,
come passata nel itemid alle funzioni display e ask dette
sopra.
L'utente deve almeno avere permessi di lettura per vedere la valutazione
di una voce, e alme no permesso di ocmmentare per poter valutare una voce (articolo,
commento, ecc.).
Configurazione
Il modulo ha due variabili di configurazione, quì sotto descritte:
defaultstyle
Questa variabile descrive lo stile di visualizzazione quando non viene fornito
uno stile specifico dal modulo chiamante. Può assumere uno degli stili
di valutazione descritti sopra.
seclevel
Questa variabile descrive il livello di sicurezza applicabile alle valutazioni
allo scopo di evitare che un utente possa imbrogliare nelle valutazioni. Maggiore
è il livello di sicurezza, più sarà difficile per l'utente
valutare più volte la stessa voce, ma maggiore sarà il lavoro di
Envolution per assicurare che l'utente non cerchi di valutare e votare più
volte la stessa voce.