ExpressionScript – praktické návody
From LimeSurvey Manual
Prehľad doterajšieho výkladu
Ak ste doteraz sledovali štruktúru manuálu LimeSurvey, už poznáte terminológiu LimeSurvey. Ďalej sme sa venovali výrazom a premenným, aby ste sa naučili vylepšovať svoje prieskumy. V ďalšej časti sme prešli k typom a významu zvýrazňovania syntaxe, aby ste sa naučili opravovať syntaktické chyby.
Keď už máme tieto základné pojmy za sebou, môžeme prejsť k príkladom a vysvetleniu, ako výrazy v LimeSurvey fungujú.
Zvýrazňovanie syntaxe
Nasledujúce snímky obrazovky uvádzajú príklady, ale nezobrazujú hodnoty popisov (tooltipov). Popis je informačné okno, ktoré sa zobrazí, keď myšou prejdete nad akékoľvek farebné tučné slovo.
Vďaka tomuto zvýrazňovaniu syntaxe je veľmi jednoduché vytvárať správne výrazy, aj tie zložité. Hoci tím LimeSurvey plánuje vytvoriť grafické rozhranie Expression Builder, existujúce zvýrazňovanie syntaxe môžete využiť na rýchle nájdenie a opravu preklepov. Popisy môžete použiť aj na overenie správnosti svojich výrazov (napr. potvrdiť, že ste vybrali požadované premenné).
V každom z príkladov sú tri stĺpce:
- Zdroj – toto je surový text, ktorý by ste zadali do poľa otázky v LimeSurvey
- Pretty Print – toto je ekvivalent zadaného textu so zvýraznenou syntaxou
- Všimnite si, že výrazy sú zobrazené so svetlohnedým pozadím, ale pri tomto zvýraznení nie sú ohraničené zloženými zátvorkami.
- Keďže EM podporuje rekurzívnu substitúciu, zobrazenie zložených zátvoriek vo zvýraznení by spôsobilo syntaktické chyby
- Výsledok – toto je výstup vygenerovaný, keď EM spracuje zdroj
- Všetko, čo sa dá správne nahradiť, je nahradené
- Výrazy s chybami sa zobrazujú priamo v texte so zvýraznením syntaxe. Chyby sú ohraničené červeným rámčekom.
Správna syntax
Nižšie nájdete príklady správnej syntaxe:
- Hodnoty: ukazuje, že známe premenné sú farebne označené podľa toho, či sú nastavené na aktuálnej stránke.
- Atribúty otázky: ukazuje, že pomocou bodkovej notácie je možné pristupovať k niektorým vlastnostiam otázok
- Matematika: ukazuje, že sú podporované základné aj zložité výpočty
- TextProcessing: ukazuje niektoré z dostupných funkcií na spracovanie textu
- Dátumy: ukazuje dve z dostupných funkcií súvisiacich s dátumom
- Podmienka: ukazuje použitie funkcie if(). Voľby je možné vnárať.
- Prispôsobený odsek: správu môžete úplne prispôsobiť na základe predchádzajúcich hodnôt
- EM spracúva reťazce: ukazuje, že dokáže robiť substitúcie v reťazcoch. Tento príklad generuje prispôsobený názov obrázka.
- EM nespracúva zložené zátvorky, ako sú tieto: ukazuje, že ak sú zložené zátvorky escapované alebo je medzi výrazom a zloženými zátvorkami medzera, ES výraz ignoruje.
Syntax EM obsahujúca chyby
Tu sú príklady bežných chýb pri písaní výrazov ES. Všimnite si, že popisy poskytujú ďalšie informácie.
- Inline Javascript, v ktorom chýbajú medzery za zloženou zátvorkou
- Keďže „document.write“ sa nachádza hneď za zloženou zátvorkou, EM si myslí, že ide o výraz, a červeným rámčekom označí „document“ a „write“, pretože ide o nedefinovanú premennú, resp. funkciu
- Neznáme/nesprávne napísané premenné, funkcie a operátory
- Tu sme zabudli, že používame názov premennej „gender“ namiesto „sex“, ale EM túto chybu zachytí. Červeným rámčekom označí aj '++', pretože to nie je podporovaný operátor.
- Upozornenie, ak použijete = namiesto eq alebo vykonávate priradenie hodnôt
- Všimnite si, že '=' a '+=' sú červenou farbou namiesto čiernej. Ak nad ne prejdete myšou, zobrazia sa upozornenia, že priraďujete hodnotu.
- Nesprávny počet argumentov funkcií
- if() prijíma 3 argumenty, ale dostala 4, takže ak prejdete myšou nad „if“ označené červeným rámčekom, zobrazí sa vysvetlenie chyby a podporovaná syntax
- sum() prijíma neobmedzený počet argumentov, ale pred uzatváracou zátvorkou sme mali zbytočnú čiarku, preto je označená červeným rámčekom
- Nesúhlasiace zátvorky
- Toto je jedna z najčastejších chýb pri písaní výrazov.
- Zobrazujú sa dva príklady chýbajúcich uzatváracích zátvoriek a jeden príklad s jednou uzatváracou zátvorkou navyše.
- Nepodporovaná syntax
- Ak použijete operátor alebo interpunkciu, ktorú ES nepodporuje, označí ju červeným rámčekom.
- Neplatné priradenia
- Niektoré premenné sú readWrite a ich hodnoty je možné meniť. Iné sú len na čítanie.
- Ak sa pokúsite zmeniť hodnotu premennej určenej len na čítanie, nepodarí sa vám to. EM tento pokus označí červeným rámčekom.
- Ak sa pokúsite priradiť hodnotu rovnici alebo reťazcu, tiež sa zobrazí chyba
„Živé“ príklady zvýrazňovania syntaxe s aktívnymi popismi
| Zdroj | Zvýraznený zápis | Výsledok |
|---|---|---|
| Tu je príklad správnej syntaxe s popismi Dobrý deň {if(gender=='M','Mr.','Mrs.')} {surname}, teraz je {date('g:i a',time())}. Viete, kde sú vaše {sum(numPets,numKids)} deti a domáce zvieratá? | Tu je príklad správnej syntaxe s popismi Dobrý deň if(gender == 'M','Mr.','Mrs.') surname, teraz je date('g:i a',time()). Viete, kde sú vaše sum(numPets,numKids) deti a domáce zvieratá? | Tu je príklad správnej syntaxe s popismi Dobrý deň Mr. Smith, teraz je 6:07 am. Viete, kde sú vaše 3 deti a domáce zvieratá? |
| Tu sú bežné chyby, aby ste videli popisy Premenné použité pred ich deklarovaním: {notSetYet} Neznáma funkcia: {iff(numPets>numKids,1,2)} Neznáma premenná: {sum(age,num_pets,numKids)} Nesprávny počet parametrov: {sprintf()},{if(1,2)},{date()} Priradenie do premenných len na čítanie:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Nevyvážené zátvorky: {pow(3,4},{(pow(3,4)},{pow(3,4))} | Tu sú bežné chyby, aby ste mohli vidieť tooltipy Premenné použité pred ich deklaráciou: notSetYet Neznáma funkcia: iff(numPets > numKids,1,2) Neznáma premenná: sum(age,num_pets,numKids) Nesprávny počet parametrov: sprintf(),if(1,2),date() Priradenie do premenných len na čítanie:TOKEN:ATTRIBUTE_1+=10,name='Sally' Nevyvážené zátvorky: pow(3,4,(pow(3,4),pow(3,4)) | Tu sú bežné chyby, aby ste mohli vidieť tooltipy Premenné použité pred ich deklaráciou: notSetYet Neznáma funkcia: iff(numPets > numKids,1,2) Neznáma premenná: sum(age,num_pets,numKids) Nesprávny počet parametrov: sprintf(),if(1,2),date() Priradenie do premenných len na čítanie:TOKEN:ATTRIBUTE_1+=10,name='Sally' Nevyvážené zátvorky: pow(3,4,(pow(3,4),pow(3,4)) |
| Here is some of the unsupported syntax No support for '++', '--', '%',';': {min(++age, --age,age % 2);} Nor '|', '&', '^': {(sum(2 | 3,3 & 4,5 ^ 6)}} Nor arrays: {name[2], name['mine']} | Here is some of the unsupported syntax No support for '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Nor '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Nor arrays: name [ 2 ] ,name [ 'mine' ] | Here is some of the unsupported syntax No support for '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Nor '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Nor arrays: name [ 2 ] ,name [ 'mine' ] |
Príklady prispôsobenia
"Vážený {Mr}/{Mrs} Smith..."
Pomocou funkcie if() podmienene vyberte, či sa má zobraziť „Mr.“ alebo „Mrs.“.
Syntax je if(test,do_if_true,do_if_false).
| # | Kód | Otázka | Typ |
| 1 | gender | Aké je vaše pohlavie? | Pohlavie |
| 2 | example1 | Vážený {if(gender=='M','Mr.','Mrs.')} Smith, ... | Dlhý text |
Ako vidno nižšie, „Mr“ a „Mrs“ sa prispôsobujú tomu, čo respondent vyberie ako odpoveď na otázku „gender“.
"Vážený {Mr}/{Mrs} Smith..." v e-mailovej pozvánke
Vyššie uvedený príklad môžete použiť v e-mailovej pozvánke pomocou atribútov z tabuľky tokenov. Pomocou funkcie if() vyberte, či sa má v e-maile použiť „Mr.“ alebo „Mrs.“.
Syntax je „if(test,do_if_true,do_if_false)“.
| # | atribút | hodnota |
| 1 | Priezvisko | Smith |
| 2 | Emailová adresa | test@test.com |
| 3 | ATTRIBUTE_2 | M |
Text v e-mailovej pozvánke:
Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},
you have been invited to participate in a survey:
https:/...
Zobrazenie e-mailu:
Príklady výpočtov / hodnotenia
Výpočet hodnôt hodnotenia za behu a uloženie výsledkov do údajov prieskumu
Tento príklad využíva všetky funkcie EM vrátane relevantnosti, prispôsobenia a typu otázky Rovnica.
Ukazuje tiež, že všetky tieto funkcie podporujú JavaScript, takže ak ich máte na stránke, bude sa dynamicky meniť podľa toho, ako ľudia zadávajú a menia svoje odpovede.
| # | Kód | Otázka | Typ | Relevantnosť |
| 1 | numKids | Koľko detí máte? | Číselný vstup | 1 |
| 2 | kid1 | Koľko rokov má vaše prvé dieťa? | Číselný vstup | numKids >= 1 |
| 3 | kid2 | Koľko rokov má vaše druhé dieťa? | Číselný vstup | numKids >= 2 |
| 4 | kid3 | Koľko rokov má vaše tretie dieťa? | Číselný vstup | numKids >= 3 |
| 5 | kid4 | Koľko rokov má vaše štvrté dieťa? | Číselný vstup | numKids >= 4 |
| 6 | sumKidAges | {sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)} | Rovnica | 1 |
| 7 | kidSummary | You said that you have {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')} | Zobrazenie textu | 1 |
Ak si chcete stiahnuť tento príklad, kliknite na nasledujúci odkaz: Assessments_survey_example.
Nižšie nájdete snímky obrazovky reprezentatívnych otázok. Ako vidíte, EM zvýrazňuje syntax vo všetkých poliach, ktoré môžu obsahovať prispôsobenie. Tu vidíte príklady zvýraznenia syntaxe pre Relevantnosť, typ otázky Rovnica a substitúcie v rámci otázky. Substitúcie môžete použiť aj v Pomocníkovi, zobrazení hlavičky skupiny, Uvítacej správe a Záverečnej správe.
V nasledujúcom príklade je relevantnosť {numKids >= 2), takže otázka bude viditeľná iba vtedy, ak respondent uvedie, že má aspoň dve deti.
Nižšie môžete vidieť, že ku každej premennej je pripojená prípona .NAOK. Súvisí to s tým, ako EM podporuje kaskádovú relevantnosť. Bez .NAOK by sa súčet vypočítal iba vtedy, ak by respondent uviedol, že má 4 deti (t. j. ak by boli všetky premenné relevantné). Použitie .NAOK znamená, že chceme súčet vypočítať aj vtedy, keď sú všetky alebo niektoré premenné nerelevantné (t. j. „Not Applicable“ (NA) je v poriadku (OK)).
Atribút .NAOK však ovplyvňuje iba to, či sa premenné odovzdávajú do EM. Ak respondent najprv uvedie, že má 3 deti, zadá vek každého z nich a potom si to rozmyslí a uvedie, že má 2 deti, nechceme vidieť súčet troch zadaných hodnôt, pretože tretie dieťa už v našom prípade nie je „relevantné“:
Každý samostatný výraz je farebne označený béžovým pozadím. Ako vidíte, tu sú tri samostatné výrazy. Posledný z nich obsahuje správu, ktorá sa zobrazí podmienene, iba ak má respondent viac ako jedno dieťa.
Teraz sa pozrime na snímky obrazovky prieskumu v praxi.
Keď stránku prvýkrát navštívite, uvidíte toto. Všimnite si, že sa zobrazuje „You have 0 children“ namiesto „You have 0 child“.
Ak zmením hodnotu počtu detí na 1, zobrazenie sa okamžite zmení na toto, hoci sa nachádzam na tej istej stránke:
Teraz si všimnite, že gramatika je správna: „You have 1 child“.
Teraz zmením hodnotu počtu detí na 3 a zobrazenie sa okamžite zmení na toto.
Všimnite si, že dole sa teraz zobrazuje podmienená správa: „The sum of ages of your first 3 kids is 0.“.
Teraz zadám vek svojich vymyslených detí a dostanem toto zobrazenie so súčtom ich veku:
Skóre a zobrazenie sa opäť aktualizujú okamžite počas zadávania hodnôt, takže to môžete použiť na zobrazenie priebežného súčtu hodnotiaceho skóre (Assessment Score).
Teraz zmením hodnotu počtu detí na 2. Zobrazenie sa zmenilo na toto:
Všimnite si, že hoci som pre tretie dieťa zadal hodnotu 5,5, report teraz sčíta iba hodnoty prvých 2 detí.
Dôvodom je, že tretia hodnota je teraz nerelevantná a nerelevantné hodnoty EM aktívne ignoruje.
Ak by som počet detí zmenil späť na 3, opäť by som videl hodnotu 5,5, ktorú som zadal. Takže neprichádzam o žiadne informácie, ktoré na stránke zadám.
Ak však prejdem na Ďalšiu stránku alebo Predchádzajúcu stránku, všetky nerelevantné hodnoty sa v relácii aj v databáze vynulujú (NULL). Ak by som teda ponechal hodnotu 2, prešiel na ďalšiu stránku, vrátil sa späť a uviedol, že v skutočnosti mám 3 deti, už by som nevidel vek 5,5.
Zadávanie údajov a dynamicky sa meniaci report zadaného na tej istej stránke
Tento príklad predstavuje proces prispôsobenia (Tailoring) v LimeSurvey.
Ak si chcete stiahnuť tento príklad, kliknite na nasledujúci odkaz: Príklad prieskumu s dynamickými zmenami.
Takto vyzerá stránka na začiatku. Vidíte iba otázku, v ktorom meste bývate:
Hneď ako začnete zadávať odpoveď, spustí sa aj proces prispôsobenia:
Počas zadávania odpovedí sa tabuľka v dolnej časti stránky aktualizuje a zobrazuje kódy odpovedí a hodnoty vašich odpovedí.
Bežné príklady ladenia
Vnorené príkazy if() (podmienená logika)
EM podporuje funkciu "if(test,do_if_true,do_if_false)", pomocou ktorej môžete vytvárať podmienenú logiku alebo prispôsobenie. Túto funkciu je možné vnárať, čím získate ekvivalent konštrukcie "if { } else if { } else { }". EM vás upozorní, ak zátvorky nie sú vyvážené (napr. chýba zatváracia pravá zátvorka) alebo ak máte nadbytočné pravé zátvorky. Pri tvorbe dlhých vnorených príkazov if sa snažte zátvorky spočítať, príkaz uložte, skontrolujte syntaktické chyby a prípadné chyby opravte. Pozrime sa spolu na nasledujúci príklad.
Skupinu otázok použitú nižšie si môžete stiahnuť tu: Ukážka prispôsobenia prieskumu.lsg
Najprv, keď nie je zadané nič, zobrazí sa iba "Ahoj."
Ak zadáte meno, zobrazí sa "Ahoj {name}."
Ak zadáte vek, zobrazí sa prispôsobená správa v závislosti od toho, či ide o dieťa predškolského veku alebo nie:
Školský vek, tínedžer alebo dospelý. Tu je tínedžer, ktorý chce zostať anonymný:
Tu je súbor logiky skupiny. Ako vidíte pri otázke "if-based", obsahuje vnorené príkazy if založené na veku osoby.
Keď túto otázku pôvodne upravujete, pravdepodobne sa stane, že budete mať nesprávny počet zátvoriek. Takto to vyzerá, ak ich máte príliš málo:
Ak umiestnite kurzor myši nad slovo "if", ktoré je orámované červeným rámčekom, zobrazí sa "Parentheses not balanced". V tomto prípade by mali byť za textom "already an adult!" štyri zatváracie zátvorky, ale sú tam iba tri.
Ak máte naopak jednu pravú zátvorku navyše, bude orámovaná červeným rámčekom, takto:
Keď otázku skutočne upravujete, vyzerá takto:
