ExpressionScript Engine - Quick start guide/it: Difference between revisions
From LimeSurvey Manual
Created page with "Nell'immagine seguente , per il calcolo di weightstatus su utilizzano espressioni "if()" annidate in modo da stabilire se la persona è sottopeso o gravemente obesa. L'equazio..." |
Maren.fritz (talk | contribs) No edit summary |
||
| (42 intermediate revisions by 3 users not shown) | |||
| Line 3: | Line 3: | ||
= | =Guida rapida= | ||
[https://www.limesurvey.org LimeSurvey] permette di configurare ulteriormente i sondaggi tramite l'utilizzo di ExpressionScript ( | [https://www.limesurvey.org LimeSurvey] permette di configurare ulteriormente i sondaggi tramite l'utilizzo di ExpressionScript (in breve, ES). | ||
Nota: "Nelle precedenti versioni, ExpressionScript era nominato Expression Manager (EM), o Gestore espressioni. Se in qualche sezione della documentazione appare il nome Expression Manager, tenere presente che è semplicemente il vecchio nome di ES. | |||
Nota: "Nelle precedenti versioni, ExpressionScript era nominato Expression Manager (EM), o Gestore espressioni. Se in qualche sezione della documentazione appare il nome Expression Manager, tenere presente che è semplicemente il vecchio nome di ES". | |||
ES consente di realizzare funzionalità avanzate, quali: | ES consente di realizzare funzionalità avanzate, quali: | ||
#'''Navigazione/Ramificazione''' – le risposte precedentemente inserite condizionano l’ordine in cui le domande successive sono poste ; | #'''Navigazione/Ramificazione''' – le risposte precedentemente inserite condizionano l’ordine in cui le domande successive sono poste; | ||
#'''Adattamento/Piping''' – cambiare dinamicamente il modo in cui le risposte sono declinate (ad esempio, adattare genere e numero delle parole riferendosi a risposte precedenti) e possibilità di generare report personalizzati e fornire punteggi di valutazione o altri valori personalizzati; | #'''Adattamento/Piping''' – cambiare dinamicamente il modo in cui le risposte sono declinate (ad esempio, adattare genere e numero delle parole riferendosi a risposte precedenti) e possibilità di generare report personalizzati e fornire punteggi di valutazione o altri valori personalizzati; | ||
#'''Convalida''' – | #'''Convalida''' – verificare che le risposte rispondano a determinati criteri, come l’appartenenza ad un intervallo numerico o la rispondenza a uno schema (ad esempio, un indirizzo e-mail o un numero telefonico devono avere un certo formato). | ||
Grazie a ES è disponibile una modalità intuitiva per specificare la logica di ciascuna di queste caratteristiche. È possibile costruire espressioni valide per praticamente ogni equazione matematica standard, anche contenente funzioni. | Grazie a ES, è disponibile una modalità intuitiva per specificare la logica di ciascuna di queste caratteristiche. È possibile costruire espressioni valide per praticamente ogni equazione matematica standard, anche contenente funzioni. | ||
ES contente l'utilizzo di 70 funzioni e può anche essere esteso per includerne di ulteriori. Le variabili possono essere chiamate con nomi facilmente leggibili e non solo con i [[SGQA_identifier|codici SGQA]]. | ES contente l'utilizzo di 70 funzioni e può anche essere esteso per includerne di ulteriori. Le variabili possono essere chiamate con nomi facilmente leggibili e non solo con i [[SGQA_identifier|codici SGQA]]. | ||
Le sezioni seguenti mostrano | Le sezioni seguenti mostrano le principali situazioni nelle quali può essere utilizzato EspressionScript. | ||
| Line 26: | Line 27: | ||
Alcuni sistemi di gestione per sondaggi utilizzano una logica di tipo "GoTo": ad esempio, se si sceglie l'opzione C per la Domanda 1, allora vai alla Domanda 5. | Alcuni sistemi di gestione per sondaggi utilizzano una logica di tipo "GoTo": ad esempio, se si sceglie l'opzione C per la Domanda 1, allora vai alla Domanda 5. | ||
Questo approccio è piuttosto limitato, perché implica difficoltà di convalida e soprattutto perché la struttura logica si rompe se le domande vengono riordinate. | Questo approccio è piuttosto limitato, perché implica difficoltà di convalida e soprattutto perché la struttura logica si "rompe" se le domande vengono riordinate. | ||
ES utilizza invece [https://it.wikipedia.org/wiki/Algebra_di_Boole equazioni booleane di rilevanza], con le quali sono specificate tutte le condizioni che una domanda deve rispettare per essere valida. Se la domanda ha "rilevanza", allora essa viene mostrata; altrimenti, è "non applicabile" e | ES utilizza invece [https://it.wikipedia.org/wiki/Algebra_di_Boole equazioni booleane di rilevanza], con le quali sono specificate tutte le condizioni che una domanda deve rispettare per essere valida. Se la domanda ha "rilevanza", allora essa viene mostrata; altrimenti, è "non applicabile", il testo non viene mostrato e nel database delle risposte è salvato il valore NULL. | ||
<div class='simplebox'> '''Nota''' Si tratta di qualcosa di simile a quanto può essere fatto dall' | <div class='simplebox'> '''Nota:''' Si tratta di qualcosa di simile a quanto può essere fatto dall'[[Setting conditions|Editor delle condizioni]] ma ES permette di specificare facilmente criteri molto più complessi e potenti; inoltre, permette di usare il nome della variabile invece dei codici SGQA.</div> | ||
| Line 35: | Line 36: | ||
Per comprendere meglio il concetto di rilevanza, | Per comprendere meglio il concetto di rilevanza, concentriamoci sul seguente sondaggio che calcola l'indice di massa corporea (BMI) degli intervistati. Per scaricarlo, fai clic sul seguente link: [[Media:LS3_em_tailoring.zip|Esempio di sondaggio sull'indice di massa corporea]]. | ||
L'equazione di rilevanza è mostrata nella colonna "Relevance", dopo il nome della variabile (che è scritto in verde). Come si può vedere, la rilevanza di weight, weight_units, height and height_units vale in tutti i casi 1 (che è il valore di default), | L'equazione di rilevanza è mostrata nella colonna "Relevance", dopo il nome della variabile (che è scritto in verde). Come si può vedere, la rilevanza di weight, weight_units, height and height_units vale in tutti i casi 1 (che è il valore di default). Siccome '1' sta per TRUE (vero), tutte queste domande sono sempre mostrate. L'equazione di rilevanza per il BMI, invece, è {!is_empty(height) and !is_empty(weight)}: questo significa che il BMI sarà calcolato solo se chi risponde al sondaggio ha inserito un valore sia per height ("altezza") che per weight ("peso"); in tal modo si evita di eseguire una divisione per zero con conseguente messaggio di errore. | ||
Anche la domanda "Report" è mostrata solo se sono state fornite risposte a tutte e quattro le domande principali (height, height_units, weight, weight_units). | Anche la domanda "Report" è mostrata solo se sono state fornite risposte a tutte e quattro le domande principali (height, height_units, weight, weight_units). | ||
| Line 68: | Line 68: | ||
Nota bene: non si utilizzano le parentesi graffe quando si inserisce una equazione di rilevanza. | <div class="simplebox"> [[File:help.png]] '''Nota bene:''' non si utilizzano le parentesi graffe quando si inserisce una equazione di rilevanza.</div> | ||
| Line 74: | Line 74: | ||
Concentriamoci ora su un altro esempio: un semplice sondaggio di censimento. Per scaricarlo, fai clic sul seguente link: [[Media:LS3_group_relevance.zip|Esempio di sondaggio di censimento]]. | |||
La prima pagina | La prima pagina chiede quante persone vivono con l'utente e salva tale valore nella variabile "cohabs". La pagina è mostrata solo se hai almeno un convivente. Anche le variabili p2name, p2age. p2sum sono mostrate solamente se la domanda precedente a ciascuna di esse contiene una risposta. | ||
| Line 82: | Line 82: | ||
Anche | Anche per i gruppi di domanda si può impostare un criterio di rilevanza: ES combina rilevanza a livello di gruppo e a livello di domanda. '''Le domande di un gruppo sono mostrate se il gruppo è complessivamente rilevante. Al suo interno, a loro volta, sono mostrate solo le domande rilevanti.''' | ||
Si veda lo screenshot per la modifica della rilevanza a livello di gruppo per ''Cohabitant 2'': | Si veda lo screenshot per la modifica della rilevanza a livello di gruppo per ''Cohabitant 2'': | ||
| Line 90: | Line 90: | ||
Nota bene: non si utilizzano le parentesi graffe quando si inserisce una equazione di rilevanza. | <div class="simplebox"> [[File:help.png]] '''Nota bene:''' non si utilizzano le parentesi graffe quando si inserisce una equazione di rilevanza.</div> | ||
==Adattamento/Piping== | ==Adattamento/Piping== | ||
| Line 97: | Line 96: | ||
Con ES si possono realizzare facilmente adattamenti condizionali semplici o complessi. In alcuni casi è sufficiente una semplice sostituzione come ad esempio: "Ha scritto di aver acquistato il <nowiki>[</nowiki>Prodotto Tal dei Tali]. Cosa le piace di più di esso?" | Con ES si possono realizzare facilmente adattamenti condizionali semplici o complessi. In alcuni casi è sufficiente una semplice sostituzione come ad esempio: "Ha scritto di aver acquistato il <nowiki>[</nowiki>Prodotto Tal dei Tali]. Cosa le piace di più di esso?" | ||
In altri casi invece si vuole declinare un sostantivo, come in "<nowiki>[</nowiki>Sig./Sig.ra] <nowiki>[</nowiki> | In altri casi invece si vuole declinare un sostantivo, come in "<nowiki>[</nowiki>Sig./Sig.ra] <nowiki>[</nowiki>Cognome], è disponibile a compilare il nostro questionario?". in questo ultimo caso, ovviamente si desidera utilizzare Sig. o Sig.ra a seconda del genere di chi risponde. Sono possibili anche sostituzioni più complesse, ad esempio basate su calcoli matematici. ES rende possibili tutti questi tipi di adattamento. | ||
| Line 109: | Line 108: | ||
In questo esempio, weightkg è definito da {if(weightunits == "kg", weight, weight * 0.453592)}. La fuzione "if()" significa che se chi risponde inserisce il peso in chilogrammi si deve usare il valore così com'è, altrimenti (nel caso usi il peso in libbre) si deve moltiplicare per 0.453592 in modo da convertirlo in chilogrammi. Un simile approccio è previsto per la variabile heightm variable, che permette di convertire l'altezza della persona in metri (altezza in centimetri diviso 100) anche nel caso in cui sia stata inserita in pollici(1 metro=3.28084 pollici). | In questo esempio, weightkg è definito da {if(weightunits == "kg", weight, weight * 0.453592)}. La fuzione "if()" significa che se chi risponde inserisce il peso in chilogrammi si deve usare il valore così com'è, altrimenti (nel caso usi il peso in libbre) si deve moltiplicare per 0.453592 in modo da convertirlo in chilogrammi. Un simile approccio è previsto per la variabile heightm variable, che permette di convertire l'altezza della persona in metri (altezza in centimetri diviso 100) anche nel caso in cui sia stata inserita in pollici (1 metro=3.28084 pollici). | ||
Il valore dell'Indice di Massa Corporea BMI è dato da {weightkg / (heightm * heightm)}. | Il valore dell'Indice di Massa Corporea BMI è dato da {weightkg / (heightm * heightm)}. | ||
| Line 121: | Line 120: | ||
Dalla schermata di modifica della domanda, si vede che: | |||
# | #le espressioni di adattamento devono essere rinchiuse tra parentesi graffe. | ||
# | #Le espressioni possono essere lunghe diverse righe, come in questo caso, per semplificare la lettura della logica condizionale. | ||
| Line 129: | Line 128: | ||
=== | ===Domande personalizzate, Risposte e Report=== | ||
<div class="simplebox">[[File:help.png]] ''' | <div class="simplebox">[[File:help.png]] '''Nota bene:''' L'adattamento dinamico potrebbe non funzionare se le opzioni di risposta sono incluse alll'interno di tag <nowiki><select></nowiki>, come ad esempio nel caso delle caselle a discesa. Questo dipende dal fatto che i testi generati dinamicamente sono inseriti all'interno di un tag <nowiki><span></nowiki>, non consentito all'interno dei tag <nowiki><option></nowiki> del tag <nowiki><select></nowiki> .</div> | ||
Il report sull'indice di massa corporea si presenta come segue: | |||
| Line 140: | Line 139: | ||
L'immagine seguente mostra la schermata di edit per la stessa domanda: | |||
| Line 146: | Line 145: | ||
Qualsiasi testo incluso tra parentesi graffe è trattato come se fosse una espressione; inoltre, nell'immagine precedente la sintassi appare evidenziate. Se nel testo ci sono errori di battitura (ad esempio, errori nel nome di variabili o funzioni), EspressionScript evidenzia l'errore. | |||
* heightunit.shown | Nel nostro esempio in basso: | ||
* "rnd()" | * heightunit.shown è una variabile non definita (dovrebbe essere heightunits.shown) e | ||
* "rnd()" è una funzione non definita (il cui nome corretto è "round()"). | |||
In | In entrambi i casi, gli errori sono evidenziati da un rettangolo rosso che li rende facili da individuare e correggere. | ||
| Line 156: | Line 156: | ||
Si possono pertanto creare rapidamente report complessi, come ad esempio tabulati contenenti valori inseriti dagli utenti o consigli personalizzati. | |||
Si tenga sempre bene a mente che le espressioni devono essere rinchiuse tra parentesi graffe: solo così LimeSurvey è in grado di stabilire quale parte di una domanda è testo libero e quale deve essere gestita da ExpressionScript. | |||
== | ==Convalida== | ||
ES | La maggior parte delle opzioni avanzate per le risposte è controllata da ES. Parliamo di verifiche come numero minimo e massimo di risposte, di valori indivuduali, di somma dei valori inseriti e di verifica della corrispondenza dei valori inseriti con formati obbligatori. | ||
Qualsiasi valore sia inserito in questi campi è trattato come una espressione, pertanto è possibile completare i criteri di convalida "minimo-massimo" con relazioni condizionali complesse rispetto ad altre risposte. | |||
In | In tutti i casi di questo tipo, dal momento che gli attributi avanzati delle domande sono trattati per definizione come espressione, non si devono utilizzare le parentesi graffe nella loro definizione. | ||
La pagina [[ExpressionScript sample surveys|sample surveys]] contiene molti esempi funzionanti che includono diversi esempi di espressioni di convalida.. | |||
= | =ExpressionScript - presentazione= | ||
Per saperne di più su ExpressionScript e su come utilizzare diverse espressioni per migliorare il tuo sondaggio, fai clic sul seguente [https://manual.limesurvey.org/ExpressionScript_-_Presentation link]. | |||
Latest revision as of 15:33, 2 August 2023
Guida rapida
LimeSurvey permette di configurare ulteriormente i sondaggi tramite l'utilizzo di ExpressionScript (in breve, ES).
Nota: "Nelle precedenti versioni, ExpressionScript era nominato Expression Manager (EM), o Gestore espressioni. Se in qualche sezione della documentazione appare il nome Expression Manager, tenere presente che è semplicemente il vecchio nome di ES".
ES consente di realizzare funzionalità avanzate, quali:
- Navigazione/Ramificazione – le risposte precedentemente inserite condizionano l’ordine in cui le domande successive sono poste;
- Adattamento/Piping – cambiare dinamicamente il modo in cui le risposte sono declinate (ad esempio, adattare genere e numero delle parole riferendosi a risposte precedenti) e possibilità di generare report personalizzati e fornire punteggi di valutazione o altri valori personalizzati;
- Convalida – verificare che le risposte rispondano a determinati criteri, come l’appartenenza ad un intervallo numerico o la rispondenza a uno schema (ad esempio, un indirizzo e-mail o un numero telefonico devono avere un certo formato).
Grazie a ES, è disponibile una modalità intuitiva per specificare la logica di ciascuna di queste caratteristiche. È possibile costruire espressioni valide per praticamente ogni equazione matematica standard, anche contenente funzioni.
ES contente l'utilizzo di 70 funzioni e può anche essere esteso per includerne di ulteriori. Le variabili possono essere chiamate con nomi facilmente leggibili e non solo con i codici SGQA.
Le sezioni seguenti mostrano le principali situazioni nelle quali può essere utilizzato EspressionScript.
Alcuni sistemi di gestione per sondaggi utilizzano una logica di tipo "GoTo": ad esempio, se si sceglie l'opzione C per la Domanda 1, allora vai alla Domanda 5. Questo approccio è piuttosto limitato, perché implica difficoltà di convalida e soprattutto perché la struttura logica si "rompe" se le domande vengono riordinate. ES utilizza invece equazioni booleane di rilevanza, con le quali sono specificate tutte le condizioni che una domanda deve rispettare per essere valida. Se la domanda ha "rilevanza", allora essa viene mostrata; altrimenti, è "non applicabile", il testo non viene mostrato e nel database delle risposte è salvato il valore NULL.
Per comprendere meglio il concetto di rilevanza, concentriamoci sul seguente sondaggio che calcola l'indice di massa corporea (BMI) degli intervistati. Per scaricarlo, fai clic sul seguente link: Esempio di sondaggio sull'indice di massa corporea.
L'equazione di rilevanza è mostrata nella colonna "Relevance", dopo il nome della variabile (che è scritto in verde). Come si può vedere, la rilevanza di weight, weight_units, height and height_units vale in tutti i casi 1 (che è il valore di default). Siccome '1' sta per TRUE (vero), tutte queste domande sono sempre mostrate. L'equazione di rilevanza per il BMI, invece, è {!is_empty(height) and !is_empty(weight)}: questo significa che il BMI sarà calcolato solo se chi risponde al sondaggio ha inserito un valore sia per height ("altezza") che per weight ("peso"); in tal modo si evita di eseguire una divisione per zero con conseguente messaggio di errore. Anche la domanda "Report" è mostrata solo se sono state fornite risposte a tutte e quattro le domande principali (height, height_units, weight, weight_units).
Nota: L'immagine in alto è generata dalla funzionalità File della logica dell'indagine, che permette di verificare la possibile presenza di errori di sintassi prima di attivare il sondaggio.
La rilevanza è mostrata e modificabile
- a livello di domanda
- a livello di gruppo
Visualizzare e modificare la rilevanza a livello di domanda
La seguente equazione calcola l'Indice di massa corporea. Viene mostrata solamente se la persona inserice la propria altezza e il proprio peso.
Questa è la pagina di modifica per la domanda "BMI".
Nota bene: non si utilizzano le parentesi graffe quando si inserisce una equazione di rilevanza.
Visualizzare e modificare la rilevanza a livello di gruppo
Concentriamoci ora su un altro esempio: un semplice sondaggio di censimento. Per scaricarlo, fai clic sul seguente link: Esempio di sondaggio di censimento.
La prima pagina chiede quante persone vivono con l'utente e salva tale valore nella variabile "cohabs". La pagina è mostrata solo se hai almeno un convivente. Anche le variabili p2name, p2age. p2sum sono mostrate solamente se la domanda precedente a ciascuna di esse contiene una risposta.
Anche per i gruppi di domanda si può impostare un criterio di rilevanza: ES combina rilevanza a livello di gruppo e a livello di domanda. Le domande di un gruppo sono mostrate se il gruppo è complessivamente rilevante. Al suo interno, a loro volta, sono mostrate solo le domande rilevanti.
Si veda lo screenshot per la modifica della rilevanza a livello di gruppo per Cohabitant 2:
Nota bene: non si utilizzano le parentesi graffe quando si inserisce una equazione di rilevanza.Adattamento/Piping
Con ES si possono realizzare facilmente adattamenti condizionali semplici o complessi. In alcuni casi è sufficiente una semplice sostituzione come ad esempio: "Ha scritto di aver acquistato il [Prodotto Tal dei Tali]. Cosa le piace di più di esso?" In altri casi invece si vuole declinare un sostantivo, come in "[Sig./Sig.ra] [Cognome], è disponibile a compilare il nostro questionario?". in questo ultimo caso, ovviamente si desidera utilizzare Sig. o Sig.ra a seconda del genere di chi risponde. Sono possibili anche sostituzioni più complesse, ad esempio basate su calcoli matematici. ES rende possibili tutti questi tipi di adattamento.
Equazioni Condizionali
L'esempio sull'Indice di Massa Corporea mostra come sia possibile calcolare tale indice per una persona anche nel caso in cui altezza e peso siano indicati con diverse unità di misura (centimetri/pollici e chilogrammi/libbre).
In questo esempio, weightkg è definito da {if(weightunits == "kg", weight, weight * 0.453592)}. La fuzione "if()" significa che se chi risponde inserisce il peso in chilogrammi si deve usare il valore così com'è, altrimenti (nel caso usi il peso in libbre) si deve moltiplicare per 0.453592 in modo da convertirlo in chilogrammi. Un simile approccio è previsto per la variabile heightm variable, che permette di convertire l'altezza della persona in metri (altezza in centimetri diviso 100) anche nel caso in cui sia stata inserita in pollici (1 metro=3.28084 pollici).
Il valore dell'Indice di Massa Corporea BMI è dato da {weightkg / (heightm * heightm)}.
Per finire, il report adatta il messaggio di risposta ai dati inseriti (ad es., "Ha detto di essere alto 2 metri e di pesare 70 kg.").
Nell'immagine seguente , per il calcolo di weightstatus su utilizzano espressioni "if()" annidate in modo da stabilire se la persona è sottopeso o gravemente obesa. L'equazione chiarisce la logica di funzionamento:
Dalla schermata di modifica della domanda, si vede che:
- le espressioni di adattamento devono essere rinchiuse tra parentesi graffe.
- Le espressioni possono essere lunghe diverse righe, come in questo caso, per semplificare la lettura della logica condizionale.
Domande personalizzate, Risposte e Report
Nota bene: L'adattamento dinamico potrebbe non funzionare se le opzioni di risposta sono incluse alll'interno di tag <select>, come ad esempio nel caso delle caselle a discesa. Questo dipende dal fatto che i testi generati dinamicamente sono inseriti all'interno di un tag <span>, non consentito all'interno dei tag <option> del tag <select> .Il report sull'indice di massa corporea si presenta come segue:
L'immagine seguente mostra la schermata di edit per la stessa domanda:
Qualsiasi testo incluso tra parentesi graffe è trattato come se fosse una espressione; inoltre, nell'immagine precedente la sintassi appare evidenziate. Se nel testo ci sono errori di battitura (ad esempio, errori nel nome di variabili o funzioni), EspressionScript evidenzia l'errore.
Nel nostro esempio in basso:
- heightunit.shown è una variabile non definita (dovrebbe essere heightunits.shown) e
- "rnd()" è una funzione non definita (il cui nome corretto è "round()").
In entrambi i casi, gli errori sono evidenziati da un rettangolo rosso che li rende facili da individuare e correggere.
Si possono pertanto creare rapidamente report complessi, come ad esempio tabulati contenenti valori inseriti dagli utenti o consigli personalizzati.
Si tenga sempre bene a mente che le espressioni devono essere rinchiuse tra parentesi graffe: solo così LimeSurvey è in grado di stabilire quale parte di una domanda è testo libero e quale deve essere gestita da ExpressionScript.
Convalida
La maggior parte delle opzioni avanzate per le risposte è controllata da ES. Parliamo di verifiche come numero minimo e massimo di risposte, di valori indivuduali, di somma dei valori inseriti e di verifica della corrispondenza dei valori inseriti con formati obbligatori. Qualsiasi valore sia inserito in questi campi è trattato come una espressione, pertanto è possibile completare i criteri di convalida "minimo-massimo" con relazioni condizionali complesse rispetto ad altre risposte.
In tutti i casi di questo tipo, dal momento che gli attributi avanzati delle domande sono trattati per definizione come espressione, non si devono utilizzare le parentesi graffe nella loro definizione.
La pagina sample surveys contiene molti esempi funzionanti che includono diversi esempi di espressioni di convalida..
ExpressionScript - presentazione
Per saperne di più su ExpressionScript e su come utilizzare diverse espressioni per migliorare il tuo sondaggio, fai clic sul seguente link.