Návody k ExpressionScript
From LimeSurvey Manual
Přehled dosud vysvětleného
Pokud jste dosud sledovali strukturu příručky k LimeSurvey, již znáte terminologii LimeSurvey. Poté jsme se věnovali výrazům a proměnným, abyste se naučili, jak svá šetření vylepšit. V další části jsme přešli k typům a významům zvýraznění syntaxe, abyste se naučili opravovat syntaktické chyby.
Po osvojení těchto základních pojmů můžeme přejít k příkladům a vysvětlení, jak výrazy v LimeSurvey fungují.
Zvýraznění syntaxe
Následující snímky obrazovky uvádějí příklady, ale nezobrazují hodnoty popisků (tooltipů). Tooltip je informativní okénko, které se zobrazí, když najedete myší na libovolné tučné barevné slovo.
Díky zvýraznění syntaxe je velmi snadné vytvářet správné výrazy, i ty složité. Přestože tým LimeSurvey plánuje vytvořit grafické rozhraní pro tvorbu výrazů, můžete již nyní využít stávající zvýraznění syntaxe k rychlému nalezení a opravě překlepů. Pomocí tooltipů můžete také ověřit správnost svých výrazů (např. potvrdit, že jste vybrali požadované proměnné).
V každém z příkladů jsou tři sloupce:
- Source (Zdroj) - jde o nezpracovaný text, který byste zadali do pole otázky v LimeSurvey
- Pretty Print (Formátovaný výpis) - jde o ekvivalent zadaného textu se zvýrazněnou syntaxí
- Všimněte si, že výrazy jsou zobrazeny na světle hnědém pozadí, ale při tomto zvýraznění nejsou obklopeny složenými závorkami.
- Protože EM podporuje rekurzivní substituci, zobrazení složených závorek ve zvýraznění by způsobilo syntaktické chyby.
- Result (Výsledek) - jde o výstup vygenerovaný, když EM zpracuje zdroj
- Dosadí se vše, co lze správně dosadit
- Výrazy s chybami jsou zobrazeny přímo v textu se zvýrazněnou syntaxí. Chyby jsou obklopeny červeně orámovaným polem.
Správná syntaxe
Níže najdete příklady správné syntaxe:
- Values (Hodnoty): ukazuje, že známé proměnné jsou barevně odlišeny podle toho, zda jsou nastaveny na aktuální stránce.
- Question Attributes (Atributy otázky): ukazuje, že pomocí tečkové notace lze přistupovat k některým vlastnostem otázek
- Math (Matematika): ukazuje, že jsou podporovány základní i složité výpočty
- TextProcessing (Zpracování textu): ukazuje některé z dostupných funkcí pro zpracování textu
- Dates (Data): ukazuje dvě z dostupných funkcí pro práci s daty
- Conditional (Podmínka): ukazuje použití funkce if(). Volby lze vnořovat.
- Tailored paragraph (Přizpůsobený odstavec): zprávu můžete zcela přizpůsobit na základě předchozích hodnot
- EM processes within strings (EM zpracovává uvnitř řetězců): ukazuje, že lze provádět substituce uvnitř řetězců. Tento příklad generuje přizpůsobený název obrázku.
- EM doesn't process curly braces like these (EM nezpracovává složené závorky, jako jsou tyto): ukazuje, že pokud jsou složené závorky escapovány nebo je mezi výrazem a složenými závorkami mezera, ES výraz ignoruje.
Syntaxe EM obsahující chyby
Zde jsou příklady běžných chyb při psaní výrazů ES. Všimněte si, že tooltipy poskytují další informace.
- Vložený JavaScript, u kterého se zapomnělo přidat mezery za složenou závorku
- Protože „document.write“ následuje bezprostředně za složenou závorkou, EM si myslí, že jde o výraz, a červeně orámuje „document“ a „write“, protože jde o nedefinovanou proměnnou, respektive funkci
- Neznámé nebo chybně napsané proměnné, funkce a operátory
- Zde jsme zapomněli, že používáme název proměnné „gender“ místo „sex“, ale EM tuto chybu zachytí. Červeně orámuje také '++', protože to není podporovaný operátor.
- Varuje, pokud použijete = místo eq nebo provádíte přiřazení hodnot
- Všimněte si, že '=' a '+=' jsou červeným textem místo černého. Když na ně najedete myší, zobrazí se varování, že přiřazujete hodnotu.
- Nesprávný počet argumentů funkcí
- if() přijímá 3 argumenty, ale byly zadány 4, takže po najetí myší na červeně orámované „if“ se zobrazí vysvětlení chyby a podporovaná syntaxe
- sum() přijímá neomezený počet argumentů, ale před uzavírací závorkou je nadbytečná čárka, proto je orámována červeně
- Nespárované závorky
- Toto je jedna z nejčastějších chyb při psaní výrazů.
- Zde jsou dva příklady chybějících uzavíracích závorek a jeden příklad jedné nadbytečné uzavírací závorky.
- Nepodporovaná syntaxe
- Pokud použijete operátor nebo interpunkci, kterou ES nepodporuje, bude orámována červeně.
- Neplatná přiřazení
- Některé proměnné jsou typu readWrite a jejich hodnoty lze měnit. Jiné jsou pouze pro čtení.
- Pokud se pokusíte změnit hodnotu proměnné pouze pro čtení, nepodaří se to. EM tento pokus orámuje červeně.
- Pokud se pokusíte přiřadit hodnotu rovnici nebo řetězci, také se zobrazí chyba.
"Živé" ukázky zvýraznění syntaxe s aktivními popisky
| Source | Pretty Print | Result |
|---|---|---|
| Here is an example of OK syntax with tooltips Hello {if(gender=='M','Mr.','Mrs.')} {surname}, it is now {date('g:i a',time())}. Do you know where your {sum(numPets,numKids)} children and pets are? | Here is an example of OK syntax with tooltips Hello if(gender == 'M','Mr.','Mrs.') surname, it is now date('g:i a',time()). Do you know where your sum(numPets,numKids) children and pets are? | Here is an example of OK syntax with tooltips Hello Mr. Smith, it is now 6:07 am. Do you know where your 3 children and pets are? |
| Here are common errors so you can see the tooltips Variables used before they are declared: {notSetYet} Unknown Function: {iff(numPets>numKids,1,2)} Unknown Variable: {sum(age,num_pets,numKids)} Wrong # parameters: {sprintf()},{if(1,2)},{date()} Assign read-only-vars:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Unbalanced parentheses: {pow(3,4},{(pow(3,4)},{pow(3,4))} | Zde jsou časté chyby, na kterých si můžete prohlédnout popisky Proměnné použité dříve, než jsou deklarovány: notSetYet Neznámá funkce: iff(numPets > numKids,1,2) Neznámá proměnná: sum(age,num_pets,numKids) Chybný počet parametrů: sprintf(),if(1,2),date() Přiřazení do proměnných jen pro čtení:TOKEN:ATTRIBUTE_1+=10,name='Sally' Nevyvážené závorky: pow(3,4,(pow(3,4),pow(3,4)) | Zde jsou časté chyby, na kterých si můžete prohlédnout popisky Proměnné použité dříve, než jsou deklarovány: notSetYet Neznámá funkce: iff(numPets > numKids,1,2) Neznámá proměnná: sum(age,num_pets,numKids) Chybný počet parametrů: sprintf(),if(1,2),date() Přiřazení do proměnných jen pro čtení:TOKEN:ATTRIBUTE_1+=10,name='Sally' Nevyvážené závorky: 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' ] |
Příklady přizpůsobení
"Vážený {Mr}/{Mrs} Smith..."
Pomocí funkce if() podmíněně zvolte, zda se má zobrazit „Mr.“ nebo „Mrs.“.
Syntaxe je if(test,do_if_true,do_if_false).
| # | Kód | Otázka | Typ |
| 1 | gender | Jaké je Vaše pohlaví? | Pohlaví |
| 2 | example1 | Vážený(á) {if(gender=='M','Mr.','Mrs.')} Smith, ... | Dlouhý text |
Jak je vidět níže, „Mr“ a „Mrs“ se přizpůsobují odpovědi, kterou respondent zvolí v otázce „gender“.
"Vážený {Mr}/{Mrs} Smith..." v e-mailové pozvánce
Výše uvedený příklad můžete použít v e-mailové pozvánce pomocí atributů z tabulky tokenů. Pomocí funkce if() zvolte, zda se má v e-mailu použít „Mr.“ nebo „Mrs.“.
Syntaxe je „if(test,do_if_true,do_if_false)“.
| # | Atribut | Hodnota |
| 1 | Příjmení | Smith |
| 2 | E-mailová adresa | test@test.com |
| 3 | ATTRIBUTE_2 | M |
Text v e-mailové pozvánce:
Vážený(á) {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},
byli jste pozváni k účasti v průzkumu:
https:/...
Zobrazení e-mailu:
Příklady výpočtů / hodnocení
Výpočet hodnot hodnocení za běhu a uložení výsledků do dat průzkumu
Tento příklad využívá všechny funkce EM, včetně relevance, přizpůsobení a typu otázky Rovnice.
Ukazuje také, že všechny tyto funkce podporují JavaScript, takže pokud je na stránce použijete, bude se stránka dynamicky měnit podle toho, jak lidé zadávají a mění své odpovědi.
| # | Kód | Otázka | Typ | Relevance |
| 1 | numKids | Kolik máte dětí? | Číselný vstup | 1 |
| 2 | kid1 | Kolik let je Vašemu prvnímu dítěti? | Číselný vstup | numKids >= 1 |
| 3 | kid2 | Kolik let je Vašemu druhému dítěti? | Číselný vstup | numKids >= 2 |
| 4 | kid3 | Kolik let je Vašemu třetímu dítěti? | Číselný vstup | numKids >= 3 |
| 5 | kid4 | Kolik let je Vašemu čtvrtému dítěti? | Číselný vstup | numKids >= 4 |
| 6 | sumKidAges | {sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)} | Rovnice | 1 |
| 7 | kidSummary | Uvedli jste, že máte {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')} | Zobrazení textu | 1 |
Chcete-li si tento příklad stáhnout, klikněte na následující odkaz: Assessments_survey_example.
Níže najdete snímky obrazovky ukázkových otázek. Jak vidíte, EM zvýrazňuje syntaxi všech polí, která mohou obsahovat přizpůsobení. Zde vidíte příklady zvýraznění syntaxe u relevance, u typu otázky Rovnice a u substitucí uvnitř otázky. Substituce můžete používat také v nápovědě, v zobrazení záhlaví skupiny, v uvítací zprávě a v zakončovacím sdělení.
V dalším příkladu je relevance {numKids >= 2), takže otázka bude viditelná pouze tehdy, pokud respondent uvede, že má alespoň dvě děti.
Níže můžete vidět, že ke každé proměnné je připojen suffix .NAOK. Souvisí to s tím, jak EM podporuje kaskádovou relevanci. Bez .NAOK by se součet vypočítal pouze v případě, že by dotazovaný uvedl, že má 4 děti (tj. pokud jsou všechny proměnné relevantní). Použití .NAOK znamená, že chceme součet vypočítat, i když jsou všechny nebo některé proměnné nerelevantní (tj. „Not Applicable“ (NA), neboli nepoužitelné, je v pořádku (OK)).
Atribut .NAOK však ovlivňuje pouze to, zda jsou proměnné předány do EM. Pokud respondent nejprve uvede, že má 3 děti, zadá věk každého z nich, pak si to rozmyslí a uvede, že má 2 děti, nechceme zobrazit součet všech 3 zadaných hodnot, protože třetí dítě už v našem případě není „použitelné“:
Každý samostatný výraz je barevně označen béžovým pozadím. Jak vidíte, jsou zde tři samostatné výrazy. Poslední z nich obsahuje zprávu, která se podmíněně zobrazí pouze v případě, že má dotazovaný více než jedno dítě.
Nyní se podívejme na snímky obrazovky průzkumu v praxi.
Když stránku poprvé navštívíte, uvidíte tento obraz. Všimněte si, že se zobrazuje „You have 0 children“ místo „You have 0 child“.
Pokud změním hodnotu počtu dětí na 1, zobrazení se okamžitě změní na toto, přestože jsme stále na stejné stránce:
Nyní si všimněte, že gramatika je správná: „You have 1 child“.
Nyní změním hodnotu počtu dětí na 3 a zobrazení se okamžitě změní na toto.
Všimněte si, že dole nyní vidíte podmíněnou zprávu: „The sum of ages of your first 3 kids is 0.“.
Nyní zadám věk svých smyšlených dětí a zobrazí se součet jejich věku:
Skóre i zobrazení se opět aktualizují okamžitě při zadávání hodnot, takže to můžete využít k zobrazení průběžného součtu skóre hodnocení.
Nyní změním hodnotu počtu dětí na 2. Zobrazení se změnilo na toto:
Všimněte si, že přestože jsem u třetího dítěte zadal hodnotu 5,5, přehled nyní sčítá pouze hodnoty prvních 2 dětí.
Důvodem je, že třetí hodnota je nyní nerelevantní a nerelevantní hodnoty EM aktivně ignoruje.
Pokud bych počet dětí změnil zpět na 3, opět bych viděl zadanou hodnotu 5,5. Neztratím tedy žádné informace, které na stránce zadám.
Pokud však přejdu na stránku Další stránka nebo Předchozí stránka, všechny nerelevantní hodnoty budou v sezení i v databázi nastaveny na NULL. Pokud bych tedy ponechal hodnotu 2, přešel na další stránku, pak se vrátil a uvedl, že mám ve skutečnosti 3 děti, věk 5,5 bych již neviděl.
Zadávejte data a sledujte dynamicky se měnící přehled zadaných údajů na stejné stránce
Tento příklad představuje proces přizpůsobení (tailoring) v LimeSurvey.
Chcete-li si tento příklad stáhnout, klikněte na následující odkaz: Příklad průzkumu s dynamickými změnami.
Takto stránka vypadá na začátku. Vidíte pouze otázku, ve kterém městě žijete:
Jakmile začnete zadávat odpověď, spustí se také proces přizpůsobení:
Jak zadáváte odpovědi, tabulka v dolní části stránky se aktualizuje a zobrazuje kódy odpovědí a hodnoty vašich odpovědí.
Běžné příklady ladění
Vnořené příkazy if() (podmíněná logika)
EM podporuje funkci "if(test,do_if_true,do_if_false)", pomocí které můžete provádět podmíněnou logiku nebo přizpůsobení. Tuto funkci lze vnořovat, čímž získáte ekvivalent konstrukce "if { } else if { } else { }". EM vás upozorní, pokud závorky nejsou vyvážené (např. chybí uzavírací pravá závorka) nebo pokud máte nějaké závorky navíc. Při vytváření dlouhých vnořených příkazů if se snažte závorky počítat, výraz uložte, zkontrolujte syntaktické chyby a případné chyby opravte. Projděme si společně následující příklad.
Skupinu otázek použitou níže si můžete stáhnout zde: Příklad průzkumu s přizpůsobením.lsg
Nejprve, když není zadáno nic, uvidíte pouze „Ahoj.“
Pokud zadáte jméno, zobrazí se „Ahoj {name}.“
Pokud zadáte věk, zobrazí se přizpůsobená zpráva v závislosti na tom, zda jste dítě předškolního věku, nebo ne:
Školní věk, teenager nebo dospělý. Zde je teenager, který chce zůstat anonymní:
Zde je logický soubor skupiny. Jak vidíte u otázky „if-based“, obsahuje vnořené příkazy if založené na věku dané osoby.
Když tuto otázku poprvé upravujete, je pravděpodobné, že v určitém okamžiku budete mít nesprávný počet závorek. Zde je vidět, co se stane, pokud jich máte příliš málo:
Pokud najedete myší na slovo „if“, které je orámováno červeným rámečkem, zobrazí se „Parentheses not balanced“ (Závorky nejsou vyvážené). V tomto případě by za textem „already an adult!“ měly být čtyři uzavírací závorky, ale jsou pouze tři.
Pokud naopak máte pravou závorku navíc, bude orámována červeným rámečkem, například takto:
Když otázku skutečně upravujete, vypadá takto:
