FlowScript

Compatibilità:IdSurvey 5IdSurvey 6IdSurvey 7
XX

Le logiche di flusso in IdSurvey possono essere gestite con un linguaggio di programmazione chiamato FlowScript.

Il Flowscript si utilizza sia per il controllo di flusso che per impostare dei valori dinamici. È inoltre possibile eseguire del Flowscript dopo il salvataggio delle domande ad ogni pagina.

Elementi del linguaggio

Il linguaggio è composto da diversi elementi, dal più grande al più piccolo abbiamo:

Istruzione

Una istruzione rappresenta un ordine di fare qualcosa, come saltare ad una determinata pagina, andare fuori target, assegnare dei valori.

Condizione

Una condizione rappresenta un valore di verità che può essere vero o falso.

Espressione

Una espressione rappresenta un valore (stringa o numerico) che può essere assegnato ad una risposta o visualizzato all’utente.

Fattori

I fattori sono i valori da cui si costruisce il linguaggio, possono essere stringhe, numeri, valori del questionario ecc.

Punti di inserimento

Ci sono diversi punti del questionario in cui si possono inserire script. In ogni punto è richiesto uno specifico elemento del FlowScript:

  • Script di fine pagina (istruzioni)
  • Filtri (condizione)
  • Goto (goto condizionato)
  • Indice del ciclo (espressione)
  • Valore di default di una risposta aperta (espressione)
  • Valore nell’aggiorna campo nominativo (espressione)
Script di fine pagina

Tra le opzioni delle pagine c’è la possibilità di eseguire uno script. Questo script viene eseguito dopo il salvataggio delle domande e si possono pertanto utilizzare anche i valori della pagina appena risposta.

Filtri

I filtri degli elementi del questionario (sezioni, pagine, domande, risposte) sono delle condizioni che, se verificate, mostrano l’elemento a cui si riferiscono.

La sintassi è la seguente:

if( condizione )

Dove per condizione si intende una condizione del FlowScript.

Goto

Sulle opzioni di risposta è possibile impostare una condizione di salto, la cui sintassi è la seguente:

if( condizione ) goto (espressione, espressione ..)

Dove per condizione ed espressione si intendono  una condizione ed una espressione del flowscript. La condizione è facoltativa e oltre alla funzione goto si può utilizzare la funzione gotornd.

Indice del ciclo

È possibile iterare una sezione del questionario impostando un indice sulla sezione. La sintassi di questo indice è quella di una espressione del FlowScript.

Valore di default di una risposta aperta

Il valore di default di una risposta aperta può essere impostato come una espressione del FlowScript. Se il valore impostato compila correttamente in una espressione, verrà utilizzato il valore impostato, altrimenti si utilizzerà la stringa come è stata inserita.

Valore nell’aggiorna campo nominativo

Il valore nell’aggiorna campo nominativo può essere impostato come una espressione del FlowScript. Se il valore impostato compila correttamente in una espressione, verrà utilizzato il valore impostato, altrimenti si utilizzerà la stringa come è stata inserita.

La sintassi del FlowScript

La sintassi del linguaggio FlowScript è ispirata alla sintassi del C. Il linguaggio è molto intuitivo da scrivere, soprattutto per le espressioni più semplici. Questa caratteristica causa alcune particolarità quando si utilizza il linguaggio per espressioni complesse.

Istruzioni

Le istruzioni possibili sono:

  • Assegnazioni
  • Chiamate di funzioni
  • Alternative (if-then-else)
  • Iterazioni (while)

Ogni istruzione deve terminare con il simbolo di ;

Assegnazione

È possibile assegnare campi del nominativo e risposte con le istruzioni di assegnazione.

Esempi:

D1= 1;
Assegna 1 come risposta alla domanda D1

{Cognome}= Guglielminpietro;

Assegna ‘Guglielminpietro’ come cognome del nominativo.

Assegnazioni su cicli

In IdSurvey è possibile iterare sezioni del questionario (vedi cicli). Per assegnare una domanda su una iterazione particolare si utilizzano le parantesi quadre per specificare l’indice.

D1[2]= 2;

Chiamate di funzioni

Nel FlowScript è possibile chiamare funzioni che alterano il flusso del questionario, queste sono le funzioni setVariable, GoTo, GoToRnd e Ot.

Per esempio:

goto(P1);

gotornd(P1, P2, P3, Q1);

ot();

Alternative

L’istruzione alternativa (if-then-else) consente di eseguire delle istruzioni se la condizione è verificata e delle altre istruzioni in caso contrario.

La sintassi è la seguente:

if(condizione)
istruzione1;
else
istruzione2;

Esempio:

if( D1 == 1)
goto(P2);
else
gotornd(P3, P4, P5, Pfine);

Se le istruzioni da eseguire nel then o nell’else sono più di una è necessario racchiudere tutto il blocco di istruzioni tra parentesi graffe.

Esempio:

if( D1 == 1 && D2==1) {
{campo1}=1;
{campione}=SI;
}
else {
{campione}=NO;
ot();
}

Iterazioni

Il costrutto di iterazione ha la sintassi:

while(condizione) istruzione

È possibile sostituire l’istruzione nel corpo del while con un blocco di istruzioni racchiuse tra parentesi graffe. Per evitare stalli il ciclo while è limitato a 1000 iterazioni, dopo le quali il ciclo si interrompe.

Esempio:

while ({j}<= {i})
{
{totale}= {totale}+[P2.Q1][{j}];
{j}++;
}

Condizioni

Una condizione rappresenta un valore di verità che può essere vero o falso. Le condizioni sono utilizzate nei filtri degli elementi del questionario e possono essere usate per condizionare un salto. Per esempio:

D1 == 1;

Se l’espressione di sinistra di una condizione è una stringa libera (ovvero senza apici), questa viene interpretata come “codici di risposta della domanda D1”, ovvero è equivalente a

responsesCodeOf('D1') == 1;

Simboli di confronto

I simboli di confronto utilizzabili nelle espressioni sono:

  • == uguale
  • != diverso
  • < minore
  • > maggiore
  • <= minore uguale
  • >= maggiore uguale
Operatori logici

Le condizioni possono essere combinate tra loro utilizzando le parentesi e gli usuali operatori logici:

  • ! negazione
  • && e
  • || o

Per esempio

(D1== 1 ||D1==2)&&(D2==1||D2==2)

(!S0==1)||((D1== 1 ||D1==2)&&(D2==1||D2==2))

L’operatore && ha la precedenza sull’operatore ||. L’operatore unario ! ha la precedenza su tutti gli altri operatori.

Espressioni

I fattori possono essere combinati fra di loro con gli usuali operatori aritmetici in espressioni. Per esempio:

{campo16} + [D2] *7

[D1.1]+[D1.2]-[D1.3]

([D1.1]+[D1.2])*[D4]

Gli operatori aritmetici sono +-*/ e %, l’ultimo operatore rappresenta il modulo o “resto della divisione intera”. La moltiplicazione e la divisione (e quindi anche il modulo) hanno la precedenza sulle addizioni. Si possono usare le parentesi tonde per specificare le precedenze delle operazioni.

Somma e concatenazione

L’operatore + esegue la somma algebrica dei due fattori se entrambi sono dei numeri. Se uno dei due è una stringa non riconducibile ad un numero, l’operatore effettuerà la concatenazione.

Per esempio3+2 viene valutato come 5 mentre a+2 viene valutato come a2. Questo rende impossibile concatenare dei numeri tra di loro con il +, in questo caso utilizzare la funzione join

Fattori

I dati con cui è costruita ogni espressione del FlowScript sono chiamati fattori. Questi fattori possono essere:

  • Una stringa
  • Un valore relativo al questionario
  • Una funzione
  • Un operatore condizionale

Un fattore può anche essere una espressione fra parentesi, permettendo quindi di scrivere espressioni di complessità arbitraria.

Stringhe

Le stringhe sono sequenze di caratteri e numeri. Le stringhe sono racchiuse da apici semplici ““. Nel caso fosse necessario inserire un apice semplice all’interno della stringa è necessario farlo precedere dal carattere backslash “\”. Nel caso fosse necessario inserire un backslash è necessario farlo precedere da un altro backslash.

Esempi:

'questa è una stringa'

'questa è una \'stringa\' che contiene apici'

'questa è una stringa che contiene un \\ backslash'

Stringhe libere

Per rendere il linguaggio più semplice c’è la possibilità di inserire stringhe “libere”, ovvero stringhe senza spazi, senza usare gli apici.

In questo caso si può utilizzare solo un limitato gruppo di caratteri, nello specifico:

  • lettere dell’alfabeto inglese
  • cifre
  • il trattino basso o “underscore” _ (NON il segno meno)
  • il punto .

Questo gruppo di caratteri è esattamente il gruppo di caratteri che sono accettabili come codici di domande o risposte. Quindi ogni codice di domanda o di riposta può essere scritto omettendo gli apici. Si noti che le lettere accentate, lo spazio, i segni di punteggiatura, parentesi, lettere di alfabeti diversi dall’inglese e caratteri speciali NON fanno parte di questo elenco e NON possono essere utilizzati in una stringa libera, pertanto è necessario includere stringhe che contengono tali caratteri tra gli apici singoli.

Il segno meno o trattino “-” e il segno diviso o barra “/” non sono incluse nella lista, questo renderebbe fastidioso inserire date o numeri negativi, per cui sono previste specifiche eccezioni per questa categoria di stringhe.

Esempi:

{regione}=Lombardia;

{utente}='utente senior‘;

Date e numeri negativi

Le stringhe che rappresentano date e numeri negativi possono essere scritte senza gli apici se rispettano i seguenti formati:

Il numero negativo deve essere nel formato: “trattino” “cifre da 0 a 9”. La parte decimale è facoltativa. NON sono ammessi spazi all’interno dei numeri in formato libero.

Esempio: “-23” oppure “-23.77”

Le date devono essere nel formato ISO: Anno-Mese-Giorno

Esempio: “2017-12-10”

Valori relativi al questionario

In FlowScript è possibile richiamare valori del questionario per elaborarli o confrontarli. Detti valori sono:

  • Campi del nominativo
  • Campi dell’operatore
  • Risposte date alle domande

Campi del nominativo
I campi del nominativo si richiamano includendoli tra graffe ({}). Come identificativo dei campi sono ammessi gli stessi caratteri delle stringhe libere (lettere, numeri, punto e underscore).  Esempio: “{Nome}”, “{Indirizzo_di_residenza_della_mamma_al_quindicesimo_compleanno}”

I campi dell’operatore
I campi dell’operatore si richiamano includendoli tra cancelletti o graticci (#). Come identificativo dei campi sono ammessi gli stessi caratteri delle stringhe libere (lettere, numeri, punto e underscore).  Esempio: “#Nome#”, #Cognome#

Risposte date alle domande
I valori delle risposte da richiamare possono essere di vario tipo:

  • Codici di risposta
  • Valore inserito in una risposta aperta (testo, numerica, assistita, rating, slider, ecc.)
  • Testo inserito in “campo di testo dopo domanda”

I codici di risposta si richiamano semplicemente scrivendo il codice della domanda a cui si riferiscono alla sinistra di un confronto. Per esempio nel confronto “D1==1”  la stringa libera “D1” indica i codici di risposta alla domanda D1. Se serve richiamare i codici di risposta in un punto diverso dal confronto si usa la funzione responsescodeof()

Il valore inserito in una risposta aperta si richiama  includendo il codice della domanda a cui si riferisce tra parentesi quadre([]). Come codici domanda sono ammessi gli stessi caratteri delle stringhe libere (lettere, numeri, punto e underscore).

Esempio:

[P1.Q1]

Il testo inserito in “campo di testo dopo domanda” si richiama includendo il codice della domanda tra asterisco e pipe (*| |*). Come codici domanda sono ammessi gli stessi caratteri delle stringhe libere (lettere, numeri, punto e underscore).

Esempio:

*|D4.1|*

Funzioni

Un valore può essere ottenuto utilizzando una delle funzioni richiamabili dal linguaggio. I parametri delle funzioni devono essere separati da virgole e inclusi tra parentesi tonde, per esempio:

ContainsText(Q1,'mare')

Un parametro di una funzione può essere una espressione qualsiasi, inclusa un’altra funzione.

Le funzioni attualmente disponibili sono:

ContainsText
Permette di verificare la presenza di un determinato testo all’interno di una risposta aperta.

if(ContainsText (Q1,'mare')==1)

controlla se la risposta di testo della domanda Q1 contiene la parola “mare”.

CountCode
Permette di contare il numero di opzioni selezionate in una domanda a risposta multipla.

if(CountCode (Q1) >= 3)

controlla se alla domanda Q1 sono state selezionate 3 o più opzioni.

CountResponsesWithCode
Permette di contare il numero delle domande a cui si è risposto con un determinato codice risposta.

if(CountResponsesWithCode(Q1,Q2,Q3,Q4,Q5,Q6,99) >= 3)

controlla se è stato risposto codice 99 ad almeno 3 fra le domande Q1, Q2, Q3, Q4, Q5 e Q6.

CountResponsesWithText
Permette di contare il numero delle domande in cui si è risposto con un determinato testo o numero.

if(CountResponsesWithText (Q1,Q2,Q3,Q4,Q5,Q6,'mare') >= 3)

controlla se la parola “mare“ è presente in almeno 3 delle risposte di testo nelle domande Q1, Q2, Q3, Q4, Q5 e Q6.

CheckQuota
Permette di conoscere se una certa quota è aperta o chiusa.

if(CheckQuota ('Genitori') == 1)

controlla se la quota “Genitori” è chiusa

if(CheckQuota ('Genitori') == 0)

controlla se la quota “Genitori” è aperta

CompareDate
Confronta due date, per esempio:

compareDate({data_di_nascita}, '2010-10-01')

La funzione restituisce  -1 se la prima data è inferiore (precedente) alla seconda, 0 se sono uguali e 1 se la prima data è maggiore (successiva) della seconda.

GetVariable
La funzione getVariable permette di ottenere il valore di una variabile (sul nominativo o una domanda) costruendo dinamicamente il nome della variabile stessa. Per esempio:

getVariable('{data_di_nascita_figlio_'+{ifiglio}+'}')

Join
La funzione join permette di concatenare delle stringhe, per esempio join(10,02,12) restituisce la stringa 100212. Dato che di preferenza le stringhe che possono essere ricondotte a dei numeri vengono sommate dall’operatore +, la funzione join permette di concatenare questo tipo di stringhe.

Module
Restituisce la stringa CATI, CAWI o CAPI a seconda del modulo in cui ci troviamo.

Per esempio:
if(module()==cawi)
{campione}=A;

SetVariable
Permette di impostare il valore di una variabile costruendone il nome dinamicamente.

Per esempio:

setVariable('{data_di_nascita_figlio_'+{ifiglio}+'}', Antonio);

GoTo
Salta alla pagina specificata come parametro.

Per esempio goto(P1); salta alla pagina P1,  goto(P1, P2); salta alla pagina P1 e poi alla pagina P2.

NOTA BENE: I goto con un solo parametro sono “distruttivi”, significa che cancellano tutte le domande tra il punto di partenza e il punto di arrivo del salto, mentre i goto con più parametri sono “conservativi” nel senso che non cancellano nulla. Per effettuare un salto singolo “conservativo” utilizzare la sintassi goto(P1, ''), la stringa vuota dopo la P1 indica di non cancellare le pagine nel mezzo.

GoToRnd
Salta alle pagine specificate come parametri in maniera casuale, finendo sempre con la pagina specificata come ultimo parametro.

Per esempio   gotornd(P1, P2, P3); salta alla pagina P1 e poi alla pagina P2 oppure alla pagina P2 e poi alla pagina P1 andando comunque dopo alla pagina P3.

Ot
Manda il nominativo in corso di intervista fuori target.

Esempio:

if(D1==1) && (D2==3)
ot();

NOTA BENE: le funzioni setVariable, goto, gotornd e ot sono “speciali” in quanto invece di restituire un valore modificano il flusso del questionario. Per questo motivo dette funzioni non sono utilizzabili nei filtri, nel text-piping e nei valori di default delle risposte aperte.

Operatore condizionale

Come fattore è possibile utilizzare un operatore condizionale che lavora come un blocco if-then-else, la sintassi utilizza il punto di domanda e i due punti come nel linguaggio c per esempio:

(D1==1)?{codice_fiscale}:{partita_iva}

({numerofigli}>1)?'quanti anni hanno i tuoi figli':'quanti anni ha tuo figlio'

(module()==cawi)?'testo per cawi':'testo per altri moduli con operatore'

La sintassi è la seguente: (condizione)?espressione:espressione dove per condizione si intende una condizione del FlowScript e per espressione si intende una espressione del Flowscript.

Particolarità del linguaggio

Il FlowScript privilegia la velocità di scrittura e la semplicità delle espressioni a discapito dell’ortodossia del linguaggio. Questo causa alcune particolarità che  possono confondere gli utenti che hanno esperienza con altri linguaggi di programmazione.

Stringa libera o stringa, ci sono differenze?

In linea generale ogni stringa libera può anche essere scritta tra apici, l’eccezione alla regola è rappresentata dal codice di una domanda a sinistra di un operatore di confronto, il quale deve necessariamente essere una stringa libera.

Pertanto la sintassi D1==1 è equivalente a D1==’1′  dato che a destra dell’uguale ci si aspetta un valore, ma non è equivalente a ‘D1’==1, dato che la stringa con gli apici a sinistra indica che D1 va inteso come stringa D1 e non come i codici di risposta alla domanda D1.

Ricordando che la funzione responsesCodeOf recupera i codici di risposta, la sintassi D1==1 è equivalente a ResponsesCodeOf(‘D1’) == 1

Asimmetria dei confronti

Negli operatori di confronto delle condizioni (==, >, <, !=) i due operatori NON sono identici. L’operatore di destra è interpretato come stringa, mentre se l’operatore di sinistra è una stringa libera (ovvero senza apici) è interpretato come domanda.
Per esempio la condizione “D1==1” significa “verifica se alla domanda con codice D1 è stata data una risposta con codice 1”. Se inverto l’ordine degli operatori ottengo la condizione “1==D1” che significa “verifica se alla domanda con codice 1 è stata data una risposta con codice D1” che è radicalmente diverso.
Per cui bisogna sempre considerare che i confronti NON sono, in generale, invertibili.

Leave A Comment?