ExpressionScript How-tos/ja

これまでの説明の概略

LimeSurveyのマニュアルを理解しているならば、LimeSurvey特有の用語を理解していることになります。続いて、アンケートを強化する方法として、式と変数について説明しました。さらに、構文の強調表示の種類と意味を取り扱い、構文エラーを修正する方法を学びました。

これらの基本的な概念が理解できたら、LimeSurvey内で式がどのように機能するか、例を使って見ていきましょう。

構文強調表示

次のスクリーンショットは実際の表示例ですが、ツールチップの値は表示されません。ツールチップは、太字の色の上にマウスを置くたびに表示される便利なボックスです。

この構文強調表示によって、複雑なものであっても簡単に正しい式を作成することができます。LimeSurveyチームは、式ビルダーGUIの開発を計画していますが、すでに提供されている構文強調表示を使用すれば、タイプミスをすばやく特定し修正することができます。また、ツールチップを使って、式が正しいかを検証することもできます（目的の変数を選択したかを確認するなど）。

それぞれの例には、3つの列があります。

1. Source - LimeSurveyの質問フィールドに入力する生のテキストです
2. Pretty Print - 入力したものと同等ですが、構文が強調表示されています
   • この強調表示では、式は黄褐色の背景で表示されますが、中括弧で囲まれていません。
   • EMは再帰的な置換をサポートしているため、強調表示に中括弧を表示すると構文エラーが発生します
3. Result - EMがソースを処理して生成した結果です
   • 適切に置換できるものすべて
   • エラーのある式はインラインで表示され、構文が強調表示されます。 エラーは赤い線のボックスで囲まれます。

適切な構文

You may find below examples of proper syntax:

1. 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
2. Question Attributes: shows that dot notation can access some properties of questions
3. Math: shows that basic and complex calculations are supported
4. TextProcessing: shows some of the available text-processing functions
5. Dates: shows two of the available date-related functions
6. Conditional: shows the usage of the if() function. The choices can be nested.
7. Tailored paragraph: you can completely customize a report based upon prior values
8. EM processes within strings: shows that it can do substitutions within strings. This example generates a tailored image name.
9. 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構文

Here are examples of common errors when typing EM expressions. Note that the tooltips provide additional information.

1. Inline Javascript that forgot to add spaces after curly brace
   • Since "document.write" appears right after a curly brace, EM thinks it is an expression, and red-boxes "document" and "write" since they are undefined variable and functions, respectively
2. Unknown/Misspelled variables, functions and operators
   • Here we forgot that we are using the variable name "gender" instead of "sex", but EM catches that error. It also red-boxes '++', since that is not a supported operator.
3. Warns if use = instead of eq, or perform value assignments
   • Note that the '=' and '+=' are in red text instead of black. If you hover the mouse over them, you will see warnings that you are assigning a value.
4. Wrong number of arguments for functions
   • if() takes 3 arguments, but it has been given 4, so hovering over the red-boxed "if" will explain the error and show the supported syntax
   • sum() takes an unlimited number of arguments, but we had a trailing comma before the closing parentheses, so that is red-boxed
5. Mismatched parentheses
   • This is one of the most common errors when writing expressions.
   • This shows two examples of missing closing parentheses, and one example of having one too many closing parentheses.
6. Unsuported syntax
   • If you use an operator or punctuation that EM does not support, it will red-box it.
7. Invalid assignments
   • Some variables are readWrite and can have their values changed. Others are read-only.
   • If you try to change the value of a read-only variable, you can't. EM will red-box the attempt.
   • If you try to assign a value to an equation or a string, you will also get an error

アクティブなツールチップを使用した構文強調表示の"実際に動く"例

ソース	整形表示	結果
ここでは、ツールチップを使った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

As it can be observed below, "Mr" and "Mrs" are tailored to what the respondent selects as answer to question "gender".

案内メールにおける"Dear {Mr}/{Mrs} Smith..."

トークンテーブルの属性を使用して、上記の例を案内メールに使用できます。電子メールの中で'Mr.'または'Mrs.'を使い分けるにはif()関数を使用します。

構文は、"if(test,do_if_true,do_if_false)"となります。

#	attribute	value
1	Last name	Smith
2	Email address	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つしかありません。

一方、余分な右かっこがある場合、次のように赤い枠で囲まれます。

実際に質問を編集しているときは、次のようになります。