ExpressionScript How-tos/ja

これまでの説明の概略

ここまで、LimeSurveyマニュアルを読めば、LimeSurveyの用語を理解したことになります。次に、アンケートを強化する方法として、式と変数について説明しました。次の段階では、構文強調表示の種類と意味を扱い、構文エラーを修正する方法を学習しました。

これらの基本的な概念をカバーしながら、事例を使ってLimeSurvey内で式がどのように機能するかを説明します。

構文強調表示

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

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

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

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

適切な構文

適切な構文の例を以下に示します。

1. 値: 既知の変数が現在のページに設定されているかどうかに応じて色分けされていることを示します。旧式のINSERTANS:xxxxは独自のカラーコーディングスタイルを持っています。
2. 質問属性: ドット記法により質問のプロパティにアクセスできることを示します。
3. 数学: 基本的な計算と複雑な計算がサポートされていることを示します。
4. テキスト処理: テキスト処理機能が利用できることを示します。
5. 日付: 利用可能な日付関連関数のうちの2つを示します。
6. 条件: if()関数の使用法を示します。入れ子にすることもできます。
7. 文言調整された段落: 先行する値に基づいてレポートをカスタマイズすることができます。
8. 文字列内のEM処理: 文字列内で置換を実行できることを示します。この例では置換により画像名を生成しています。
9. EMは中括弧を処理しない: 中括弧がエスケープされているか、式と中括弧の間に空白がある場合、EMはその式を無視します。

エラーを含むEM構文

EM式を入力する際の一般的なエラーの例を次に示します。ツールチップは追加的な情報を提供します。

1. インラインJavascriptで中括弧の後に空白を追加していない。
   • EMは、中括弧の直後に"document.write"が現れると式であると考えるため、"document"と"write"がそれぞれ未定義の変数、関数となり、赤色のボックスで表示される。
2. 未知/間違った変数、関数、演算子
   • ここでは、"sex"（性別）の代わりに"gender"という変数名を使用していることを忘れていますが、EMはそのエラーをキャッチします。また、'++'についても、サポートしていない演算子として赤色のボックスで表示されます。
3. eqの代わりに=を使っていたり、代入を行っている場合の警告
   • '='と'+='は黒ではなく赤いテキストで表示されています。文字の上にマウスを置くと、値を代入しようとしているという警告が表示されます。
4. 関数の引数の数が間違っている
   • if()は3つの引数を取りますが、4つ与えられているので、赤いボックスの "if"にカーソルを合わせるとエラーが説明され、サポートされている構文が表示されます。
   • sum()は引数の数に制限はありませんが、閉じ括弧の前にコンマがついているので、赤色のボックスで表示されます。
5. 括弧の不一致
   • 式を書く時の最も一般的なエラーの一つです。
   • 閉じ括弧が欠落している例を2つ、閉じ括弧が多すぎる例を1つを示しています。
6. サポートされていない構文
   • EMがサポートしていない演算子または句読点を使用すると、赤いボックスになります。
7. 無効な代入
   • 変数は値が書き換え可能なものもありますが、読み取り専用のものもあります。
   • 読み取り専用変数の値を変更しようとしても実行できません。EMは赤枠で囲みます。
   • 式または文字列に値を代入しようとしてもエラーが発生します。

アクティブなツールチップを使用した構文ハイライトの"ライブ"の例

ソース	整形表示	結果
ここでは、ツールチップを使ったOK構文の例を示します。 こんにちは、{if(gender=='M','Mr.','Mrs.')} {surname}。現在、{date('g:i a',time())}です。数を合わせると{sum(numPets,numKids)}になるあなたの子供とペットがどこにいるかわかりますか。	ここでは、ツールチップを使ったOK構文の例を示します。 こんにちは、if(gender == 'M','Mr.','Mrs.') surname。現在、date('g:i a',time())です。数を合わせるとsum(numPets,numKids)になるあなたの子供とペットがどこにいるかわかりますか。	ここでは、ツールチップを使ったOK構文の例を示します。 こんにちは、Mr. Smith。現在、6:07 amです。数を合わせると3になるあなたの子供とペットがどこにいるかわかりますか。
ここでは、ツールチップが表示される一般的なエラーの例を示します。 宣言する前に変数を使用する: {notSetYet} 未知の関数: {iff(numPets>numKids,1,2)} 未知の変数: {sum(age,num_pets,numKids)} 過った # パラメーター: {sprintf()},{if(1,2)},{date()} 読み取り専用の変数への代入:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} 括弧の不一致: {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)です。

#	コード	質問	タイプ
1	gender	性別は？	性別
2	example1	Dear {if(gender=='M','Mr.','Mrs.')} Smith, ...	テキスト表示

使用ビュー:

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

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

構文は、if(test,do_if_true,do_if_false)です。

#	属性	値

案内メールのテキスト:

Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},

あなたはアンケートに招待されました。

http:/...

電子メールビュー:

計算 / 評価の例

実行時に評価値を計算し、その結果をアンケートデータに格納する

この例では、EMのすべての機能（出現条件、文言調整、式の質問タイプなど）を使用しています。

また、これらのすべてがJavaScript対応であることも示しています。したがって、ページにこれらの機能を導入すると、回答者が回答を設定したり変更したりすると、動的に変化します。

#	コード	質問	タイプ	出現条件
1	numKids	子どもは何人いますか。	数値入力	1
2	kid1	一番目の子どもは何歳ですか。	数値入力	numKids >= 1
3	kid2	二番目の子どもは何歳ですか。	数値入力	numKids >= 2
4	kid3	三番目の子どもは何歳ですか。	数値入力	numKids >= 3
5	kid4	四番目の子どもは何歳ですか。	数値入力	numKids >= 4
6	sumKidAges	{sum(kid1.NAOK,kid2,NAOK,kid3.NAOK,kid4.NAOK)}	式	1
7	kidSummary	{numKids}人の{if(numKids==1,'子ども','子どもたち')}がいると回答しました。{if(numKids>1,implode(' ','上から',min(numKids,4),'人までの年齢の合計は',sumKidAges,'です。'),' ')}	テキスト表示	1

To download this example, please click on the following link: Assessments_survey_example.

代表的な質問のスクリーンショットです。ご覧のとおり、EM構文では、文言調整を含んでいそうなすべてのフィールドが強調表示されます。ここでは、出現条件、式の質問タイプ、および質問内の置換の例を示します。ヘルプ、グループヘッダーの表示、ようこそメッセージ、および終了メッセージ内で置き換えることもできます。

この質問では、出現条件は{numKids >= 2}であるため、回答者が少なくとも2人の子供がいると回答した場合にのみ表示されます。

また、各変数に.NAOK接尾辞を使用することに注意してください。これは、EMが入れ子の出現条件を実現するためのものです。もし.NAOKをつけない場合持、4人の子供を持っていると回答した場合にのみ合計が計算されることになります（すべての変数が真の場合）。.NAOKを使用すると、変数のすべてまたは一部が偽であっても合計を計算することを意味します（すなわち"該当なし"（Not Applicable - NA）でも構わないということです）。

ただし、.NAOK属性は変数がEMに渡されるかどうかにのみ影響します。その人が最初に3人の子供がいると回答し、それぞれの年齢を入力した後、気が変わり、2人であると答えた場合、3つの入力値の合計は必要ありません。次の例で確認してください。

それぞれの式は、黄褐色の背景で色分けされています。ご覧の通り、3つの別々の式があります。最後の式には、2人以上の子供がいる場合にのみ表示されるメッセージが入っています。

ここでは、実際のアンケートのスクリーンショットを示します。

最初にページにアクセスすると、これが表示されます。"0人の子どもがいます"ではなく、"0人の子どもたちがいます"となっていることに注意してください。

子どもの数を1に変更すると、同じページ上にあってもこのように表示が即座に変わります。

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.

Now, I change the value for the number of children to 2. The display has changed to this:

Notice that although I had entered a value of 5.5 for the third child, the report now only sums the values of my first 2 children.

The reason for this is that the 3rd value is now irrelevant, and irrelevant values are actively ignored by EM.

If I were to change the number of kids back to 3, I would see the value of 5.5 I entered again. So, I don't lose any information I enter on the page.

However, if I navigate to the Next or Previous page, all irrelevant values will be NULLed out in the session and in the database. So, if I were to keep the value at 2, go to the next page, and then come back and state that I actually have 3 kids, I would no longer see the age of 5.5.

Enter data and see a dynamically changing report of what was entered on the same page

This example presents the Tailoring process within LimeSurvey.

To download this example, click on the following link: Dynamic changes survey example.

Here is what the page looks like initially. You only see the question asking what city you live in:

Once you start to enter an answer, the tailoring process is also starting:

As you enter answers, the table at the bottom of the page is updated to show the answer codes and values of your responses.

一般的なデバッグの例

ネストされたif()ステートメント（条件付きロジック）

EM supports the function "if(test,do_if_true,do_if_false)" so that you can perform conditional logic or tailoring. This function can be nested to do the equivalent of "if { } else if { } else {  }". EM will let you know if the parentheses are not balanced (e.g., you are missing a closing right parenthesis), or if you have any extra right parentheses. You should try to count the parentheses as you compose long nested if statements, save it, check for syntax errors, and fix them if any are found. Let's check together the below example.

以下の質問のグループは、ここからアクセスできます。Tailoring survey example.lsg

まず何も入力していないときは、単に"Hello."と表示されます。

名前を入力すると、"Hello {name}."となります。

年齢を入力すると、就学前の子供であるかどうかに応じて調整されたメッセージが届きます。

学齢児童、10代の人、または大人。ここに匿名希望の10代の人がいます。

ここにグループのロジックファイルがあります。 "if-based"の質問に見られるように、年齢に基づいて入れ子になったif文があります。

質問を編集している最中、括弧の数を間違える可能性があります。括弧が少ない場合はこのようになります。

赤いボックスで囲まれた"if"という言葉にカーソルを合わせると、"括弧の数が合わない"と表示されます。この例では、"already an adult!"の後ろに4つの閉じ括弧があるはずですが、3つしかありません。

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

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