ExpressionScript How-to
From LimeSurvey Manual
これまでの説明の概略
LimeSurveyのマニュアルを理解しているならば、LimeSurvey特有の用語を理解していることになります。続いて、アンケートを強化する方法として、式と変数について説明しました。さらに、構文の強調表示の種類と意味を取り扱い、構文エラーを修正する方法を学びました。
これらの基本的な概念が理解できたら、LimeSurvey内で式がどのように機能するか、例を使って見ていきましょう。
構文強調表示
次のスクリーンショットは実際の表示例ですが、ツールチップの値は表示されません。ツールチップは、太字の色の上にマウスを置くたびに表示される便利なボックスです。
この構文強調表示によって、複雑なものであっても簡単に正しい式を作成することができます。LimeSurveyチームは、式ビルダーGUIの開発を計画していますが、すでに提供されている構文強調表示を使用すれば、タイプミスをすばやく特定し修正することができます。また、ツールチップを使って、式が正しいかを検証することもできます(目的の変数を選択したかを確認するなど)。
それぞれの例には、3つの列があります。
- Source - LimeSurveyの質問フィールドに入力する生のテキストです
- Pretty Print - 入力したものと同等ですが、構文が強調表示されています
- この強調表示では、式は黄褐色の背景で表示されますが、中括弧で囲まれていません。
- EMは再帰的な置換をサポートしているため、強調表示に中括弧を表示すると構文エラーが発生します
- Result - EMがソースを処理して生成した結果です
- 適切に置換できるものすべて
- エラーのある式はインラインで表示され、構文が強調表示されます。 エラーは赤い線のボックスで囲まれます。
適切な構文
You may find below examples of proper syntax:
- Values: shows that known variables are color coded according to whether are set on the current page. Old-style INSERTANS:xxxx gets its own color-coding style
- Question Attributes: shows that dot notation can access some properties of questions
- Math: shows that basic and complex calculations are supported
- TextProcessing: shows some of the available text-processing functions
- Dates: shows two of the available date-related functions
- Conditional: shows the usage of the if() function. The choices can be nested.
- Tailored paragraph: you can completely customize a report based upon prior values
- EM processes within strings: shows that it can do substitutions within strings. This example generates a tailored image name.
- EM doesn't process curly braces like these: shows that if the curly braces are escaped, or there is a white space between the expression and the curly braces, EM ignores the expression.
エラーを含むEM構文
EM式を入力する際の一般的なエラーの例を次に示します。ツールチップによって追加情報が提供されます。
- 中括弧の後にスペースを追加し忘れたインラインJavascript
- "document.write"が中括弧の直後に表示されると、EMはそれを式と見なし、"document"と"write"はそれぞれ未定義の変数と関数と認識され、赤いボックス内に表示されます。
- 不明、またはスペルミスのある変数、関数、演算子
- ここでは、"sex"ではなく"gender"という変数名を誤って使用していても、EMはそのエラーをキャッチします。また、'++'はサポートされている演算子ではないため、赤いボックスで囲まれます。
- eqの代わりに=を使用したり、値を代入すると警告されます。
- '='と'+='は、黒ではなく赤のテキストで表示されています。その上にマウスカーソルを合わせると、値を代入している旨の警告が表示されます。
- 関数の引数の数の誤り
- if()は3つの引数を受け取りますが、4つ与えられているため、赤い枠で囲まれた"if"にカーソルを合わせると、エラーの説明とサポートされている構文が表示されます。
- sum()は引数の数に制限はありませんが、閉じ括弧の前にコンマがあるため、赤いボックスで囲まれています。
- 括弧の不一致
- これは、式を記述する際の最も一般的なエラーの1つです。
- ここでは、閉じ括弧が不足している例2つと、閉じ括弧が多すぎる例を示しています。
- サポートされていない構文
- EMがサポートしていない演算子や記号を使用すると、赤いボックスで囲まれます。
- 無効な代入
- 変数には、読み書き可能で値を変更できるもの、読み取り専用のものがあります。
- 読み取り専用変数の値を変更しようとしてもできません。この場合、EMは赤いボックスで表示します。
- 式または文字列に値を代入しようとしてもエラーが発生します。
アクティブなツールチップを使用した構文強調表示の"実際に動く"例
ソース | 整形表示 | 結果 |
---|---|---|
ここでは、ツールチップを使ったOK構文の例を示します。 こんにちは、{if(gender=='M','Mr.','Mrs.')} {surname}。現在、{date('g:i a',time())}です。数を合わせると{sum(numPets,numKids)}になるあなたの子供とペットがどこにいるかわかりますか。 | 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))} | 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)) | 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)) |
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' ] |
文言調整の例({INSERTANS:xxx}の拡張)
"Dear {Mr}/{Mrs} Smith..."
'Mr.'か'Mrs.'を使い分けるにはif()関数を使用します。
構文は、if(test,do_if_true,do_if_false)となります。
# | Code | Question | Type |
1 | gender | What is your gender? | Gender |
2 | example1 | Dear {if(gender=='M','Mr.','Mrs.')} Smith, ... | Long free text |
以下で確認できるように、"性別"に対する回答として回答者が選択したものに合わせ、"Mr"または"Mrs"になるように調整されています。
案内メールにおける"Dear {Mr}/{Mrs} Smith..."
トークンテーブルの属性を使用して、上記の例を案内メールに使用できます。電子メールの中で'Mr.'または'Mrs.'を使い分けるにはif()関数を使用します。
構文は、"if(test,do_if_true,do_if_false)"となります。
# | 属性 | 値 |
1 | 姓 | Smith |
2 | メールアドレス | test@test.com |
3 | ATTRIBUTE_2 | M |
案内メールのテキストは以下のとおりです。
Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},
あなたはアンケートに招待されました。
https:/...
電子メールは次のようになります。
計算/評価の例
実行時に評価値を計算し、その結果をアンケートデータに格納する
この例では、EMのすべての機能(出現条件、文言調整、式の質問タイプなど)を使用しています。
また、これらのすべてがJavaScript対応であることも示しています。したがって、ページにこれらの機能を導入すると、回答者が回答を設定したり変更したりすると、動的に変化します。
# | Code | Question | Type | Relevance |
1 | numKids | How many children do you have? | Numerical input | 1 |
2 | kid1 | How old is your first child? | Numerical input | numKids >= 1 |
3 | kid2 | How old is your second child? | Numerical input | numKids >= 2 |
4 | kid3 | How old is your third child? | Numerical input | numKids >= 3 |
5 | kid4 | How old is your fourth child? | Numerical input | numKids >= 4 |
6 | sumKidAges | {sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)} | Equation | 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,'.'),' ')} | Text display | 1 |
この例をダウンロードするには、次のリンクをクリックしてください。 Assessments_survey_example
以下は、代表的な質問のスクリーンショットです。ご覧のとおり、EM構文では、文言調整を含んでいそうなすべてのフィールドが強調表示されます。ここでは、出現条件、式の質問タイプ、および質問内の置換の例を示します。ヘルプ、グループヘッダーの表示、ようこそメッセージ、および終了メッセージ内で置き換えることもできます。
次の例では、出現条件は{numKids >= 2}であるため、回答者が少なくとも2人の子供がいると回答した場合にのみ表示されます。
また、各変数に.NAOK接尾辞を使用することに注意してください。これは、EMが入れ子の出現条件を実現するためのものです。もし.NAOKをつけない場合、4人の子供を持っていると回答した場合にのみ合計が計算されることになります(すべての変数が真の場合)。.NAOKを使用すると、変数のすべてまたは一部が偽であっても合計を計算することを意味します(すなわち"該当なし"(Not Applicable - NA)でも構わないということです)。
ただし、.NAOK属性は変数がEMに渡されるかどうかにのみ影響します。例えば、その人が最初に3人の子供がいると回答し、それぞれの年齢を入力した後、気が変わり、2人であると答えた場合、3人目の子供はもはや無関係なので、3つの入力値の合計は必要ありません。
それぞれの式は、黄褐色の背景で色分けされています。ご覧の通り、3つの別々の式があります。最後の式には、2人以上の子供がいる場合にのみ表示されるメッセージが入っています。
ここでは、実際のアンケートのスクリーンショットを示します。
最初にページにアクセスすると、これが表示されます。"0人の子どもがいます"ではなく、"0人の子どもたちがいます"となっていることに注意してください。
子どもの数を1に変更すると、同じページ上にあってもこのように表示が即座に変わります。
文法は正しいものになっています。 "You have 1 child".
今度は、子供の数の値を3に変更し、即座に表示を変更します。
次の条件付きメッセージが下部に表示されていることに注目してください。"The sum of ages of your first 3 kids is 0.(最初の3人の子供の年齢の合計は0です。)"
今、子供の年齢を入力し、その年齢を合計して、このように表示させるとします。
値を入力するとスコアと表示が即座に更新されるため、これを使用して評価スコアの合計を表示することができます。
今度は、子供の数を2に変更します。表示は次のように変わります。
3番目の子供には5.5の値を入力しましたが、レポートには最初の2人の子供の値が合計されるようになりました。
その理由は、第3の値は出現条件を満たさなくなり、EMはそのような値を無視するからです。
子供の数を3に戻すと、再び5.5という値が見えます。これにより、ページに入力した情報を失うことはありません。
ただし、次または前のページに移動すると、出現条件を満たさない値はすべてセッション内およびデータベース内でNULLになります。もし、子供の数を2と設定したまま次のページに行き、もとのページに戻り、実は3人の子供がいると回答すると、5.5という年齢を見ることはありません。
データを入力し、同じページ内で入力されたものが動的に変化するレポートを表示する
この例は、LimeSurvey内の文言調整プロセスを示します。
この例をダウンロードするには、下記のリンクをクリックします。 動的に変化するアンケートの例
これは、ページが最初にどのように見えるかを示しています。どの都市に住んでいるのか尋ねる質問だけがあります。
回答を入力し始めると、文言調整プロセスも開始されます。
回答を入力すると、ページの下部にある表が更新され、回答コードと回答の値が表示されます。
一般的なデバッグの例
ネストされたif()ステートメント(条件付きロジック)
EMは、条件付きロジックまたは文言調整を実行できるよう、関数"if(test,do_if_true,do_if_false)"をサポートしています。この関数は、"if { } else if { } else { }"と同等の処理を行うために入れ子にすることができます。EMは、括弧の数が合わないかどうかを通知します(たとえば、右括弧が消えているなど)か、または余計な右括弧があるかどうかを通知します。長く入れ子になったif文を作成し、保存し、構文エラーをチェックし、見つかった場合は修正してください。以下の例を一緒にチェックしてみましょう。
以下の質問のグループは、ここからアクセスできます。Tailoring survey example.lsg
まず何も入力していないときは、単に"Hello."と表示されます。
名前を入力すると、"Hello {name}."となります。
年齢を入力すると、就学前の子供であるかどうかに応じて調整されたメッセージが届きます。
学齢児童、10代の人、または大人。ここに匿名希望の10代の人がいます。
ここにグループのロジックファイルがあります。 "if-based"の質問に見られるように、年齢に基づいて入れ子になったif文があります。
名前を入力すると、"Hello {name}."となります。
赤いボックスで囲まれた"if"という言葉にカーソルを合わせると、"括弧の数が合わない"と表示されます。この例では、"already an adult!"の後ろに4つの閉じ括弧があるはずですが、3つしかありません。
一方、余分な右かっこがある場合、次のように赤い枠で囲まれます。
実際に質問を編集しているときは、次のようになります。