ExpressionScript How-tos/ja

これまでの説明の概略

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

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

構文強調表示

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

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

In each of the examples, there are three columns:

1. Source - this is the raw text that you would enter into the LimeSurvey question field
2. Pretty Print - this is the syntax-highlighted equivalent of what you entered
   • Note that Expressions are shown with a tan background, but not surrounded by curly braces in this highlighting.
   • Since EM supports recursive substitution, showing curly braces in the highlighting would cause syntax errors
3. Result - this is the output generated when EM processes the source
   • Everything that can be properly substituted is
   • Expressions with errors are shown in-line, with syntax highlighting. Errors are surrounded by a red-lined box.

適切な構文

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

You may find below screenshots of representative questions. As you can see, EM syntax-highlights all fields that might contain tailoring. Here, you see examples of syntax-highlighting Relevance, the Equation question type, and substitutions within a question. You can also use substitutions within Help, Group header display, Welcome message, and End message.

In the next example, since the relevance is {numKids >= 2), the question will only be visible if the respondent reports that she has at least two children.

Below, you may observe that each variable has the .NAOK suffix attached to it. This is because of how EM supports cascading relevance. If you did not have .NAOK, then the sum would only be computed if the person said she has 4 children (e.g., if all of the variables are relevant). The usage of .NAOK means that we want to compute the sum even if all or some of the variables are irrelevant (e.g., "Not Applicable" (NA) is alright (OK)).

However, the .NAOK attribute only affects whether variables are passed into EM. If the respondent initially says she has 3 children, and enters ages for each, then changes her mind and says she has 2, we don't want to see the sum of the 3 entered values - since the third child is "not applicable" in our case anymore:

Each separate Expression is color coded with a tan background. As you can see, there are three separate Expressions here. The last one contains a message that is conditionally shown only if the person has more than one child.

Now, here are screenshots of the survey in action.

When you first visit the page, you see this. Note that is says "You have 0 children" instead of "You have 0 child".

If I change the value for number of children to 1, the display instantly changes to this, even though it is on the same page:

Now notice that the grammar is correct: "You have 1 child".

Now I change the value for number of children to 3, and the display instantly changes to this.

Notice that you now see the conditional message at the bottom:  "The sum of ages of your first 3 kids is 0.".

Now I'll enter ages for my imaginary children, and I get this display, summing up their ages:

Again, the score and display updates instantly as I enter the values, so you can use this to show a running total of an Assessment Score.

今度は、子供の数を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つしかありません。

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

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