ExpressionScript 操作指南

先前內容回顧

如果您已依序閱讀 LimeSurvey 手冊的結構，表示您已經了解 LimeSurvey 術語。接著，我們介紹了運算式與變數，以學習如何強化您的問卷。在下一部分，我們說明了語法醒目提示的類型與含義，以學習如何修正語法錯誤。

掌握這些基本概念後，我們就可以透過範例來說明運算式在 LimeSurvey 中的運作方式。

語法醒目提示

以下截圖僅提供範例，並未顯示工具提示的內容。工具提示是一個資訊方塊，當您將滑鼠移到任何粗體彩色文字上時便會顯示。

有了語法醒目提示，即使是複雜的運算式，也能輕鬆撰寫出正確的內容。雖然 LimeSurvey 團隊計劃嘗試建立運算式產生器圖形介面，但您現在仍可利用現有的語法醒目提示快速找出並修正錯字。您也可以利用工具提示來驗證運算式的正確性（例如：確認您已選取所需的變數）。

每個範例中都有三個欄位：

1. 來源 - 這是您會輸入到 LimeSurvey 問題欄位中的原始文字
2. 美化顯示 - 這是您所輸入內容經語法醒目提示後的對應結果
   • 請注意，在此醒目提示中，運算式會以棕褐色背景顯示，但不會被大括號包圍。
   • 由於 EM 支援遞迴替換，若在醒目提示中顯示大括號，會造成語法錯誤
3. 結果 - 這是 EM 處理來源後所產生的輸出
   • 所有可正確替換的內容都會被替換
   • 含有錯誤的運算式會以語法醒目提示的方式顯示在行內。錯誤會以紅線方框框起。

正確的語法

您可以在下方找到正確語法的範例：

1. 數值：顯示已知變數會依其是否已在目前頁面設定而以不同顏色標示。
2. 問題屬性：顯示可使用點號表示法存取問題的某些屬性
3. 數學運算：顯示支援基本與複雜的計算
4. 文字處理：顯示部分可用的文字處理函數
5. 日期：顯示兩個可用的日期相關函數
6. 條件式：顯示 if() 函數的用法。選項可以巢狀嵌套。
7. 量身訂製的段落：您可以根據先前的值完全自訂報告
8. EM 在字串內處理：顯示可在字串內進行替換。此範例會產生量身訂製的圖片名稱。
9. EM 不會處理像這樣的大括號：顯示如果大括號經過跳脫，或運算式與大括號之間有空白，ES 會忽略該運算式。

含有錯誤的 EM 語法

以下是輸入 ES 運算式時常見錯誤的範例。請注意，工具提示會提供額外資訊。

1. 行內 Javascript 在大括號後忘記加上空格
   • 由於 "document.write" 緊接在大括號之後，EM 會將其視為運算式，並將 "document" 和 "write" 以紅框標示，因為它們分別是未定義的變數和函數
2. 未知或拼錯的變數、函數和運算子
   • 這裡我們忘了使用的變數名稱是 "gender" 而不是 "sex"，但 EM 偵測到了該錯誤。它也會將 '++' 以紅框標示，因為這不是支援的運算子。
3. 若使用 = 而非 eq，或執行賦值，會發出警告
   • 請注意，'=' 和 '+=' 顯示為紅色文字而非黑色。如果您將滑鼠移到它們上方，會看到您正在賦值的警告。
4. 函數的引數數量錯誤
   • if() 需要 3 個引數，但卻給了 4 個，因此將滑鼠移到以紅框標示的 "if" 上會說明錯誤並顯示支援的語法
   • sum() 可接受無限數量的引數，但我們在右括號前多了一個逗號，因此該處會以紅框標示
5. 括號不成對
   • 這是撰寫運算式時最常見的錯誤之一。
   • 此處顯示兩個缺少右括號的範例，以及一個多了一個右括號的範例。
6. 不支援的語法
   • 如果您使用了 ES 不支援的運算子或標點符號，它會以紅框標示。
7. 無效的賦值
   • 某些變數是可讀寫的，其值可以更改。其他則是唯讀的。
   • 如果您嘗試更改唯讀變數的值，將無法成功。EM 會以紅框標示該嘗試。
   • 如果您嘗試對方程式或字串賦值，也會出現錯誤

語法醒目提示與啟用工具提示的「即時」範例

來源	美化顯示	結果
以下是語法正確並附有工具提示的範例 您好 {if(gender=='M','Mr.','Mrs.')} {surname}，現在時間是 {date('g:i a',time())}。 您知道您的 {sum(numPets,numKids)} 個孩子和寵物在哪裡嗎？	以下是語法正確並附有工具提示的範例 您好 if(gender == 'M','Mr.','Mrs.') surname，現在時間是 date('g:i a',time())。 您知道您的 sum(numPets,numKids) 個孩子和寵物在哪裡嗎？	以下是語法正確並附有工具提示的範例 您好 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))}	以下是常見錯誤範例,方便您查看工具提示 在宣告之前使用的變數: 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))	以下是常見錯誤範例,方便您查看工具提示 在宣告之前使用的變數: 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 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' ]

調整範例

「親愛的 {Mr}/{Mrs} Smith...」

使用 if() 函數有條件地選擇顯示「Mr.」或「Mrs.」。

語法為 if(test,do_if_true,do_if_false)。

#	代碼	問題	類型
1	gender	您的性別是？	性別
2	example1	親愛的 {if(gender=='M','Mr.','Mrs.')} Smith，...	長篇的自由文本

如下所示，「Mr」和「Mrs」會依據受訪者對問題「gender」所選擇的答案而調整。

邀請郵件中的「親愛的 {Mr}/{Mrs} Smith...」

您可以利用 token 表中的屬性，將上述範例用於邀請郵件。使用 if() 函數來選擇郵件中應使用「Mr.」還是「Mrs.」。

語法為「if(test,do_if_true,do_if_false)」。

#	屬性	值
1	姓	Smith
2	電子郵件地址	test@test.com
3	ATTRIBUTE_2	M

邀請郵件中的文字：

親愛的 {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME}，

誠摯邀請您參與一項問卷：

https:/...

電子郵件查看：

計算／評估範例

在執行時計算評估值並將結果儲存於問卷資料中

此範例使用了 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,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')}	文字顯示	1

若要下載此範例，請點擊以下連結：Assessments_survey_example。

以下是具代表性問題的螢幕截圖。如您所見,EM 會以語法醒目提示所有可能包含客製化內容的欄位。此處示範了對相關性、方程式題型以及問題內替換的語法醒目提示。您也可以在說明、群組標題顯示、歡迎訊息和結束訊息中使用替換。

在下一個範例中,由於相關性為 {numKids >= 2),只有當受訪者表示她至少有兩個孩子時,才會顯示該問題。

在下方您可以看到,每個變數都附加了 .NAOK 後綴。這是因為 EM 支援串聯相關性。如果沒有 .NAOK,則只有在受訪者表示她有 4 個孩子時(即所有變數都相關時)才會計算總和。使用 .NAOK 表示即使所有或部分變數不相關,我們仍要計算總和(即「不適用」(NA)也可以(OK))。

不過,.NAOK 屬性只會影響變數是否被傳入 EM。如果受訪者起初表示她有 3 個孩子,並輸入了每個孩子的年齡,之後改變心意表示她有 2 個孩子,我們不希望看到這 3 個輸入值的總和,因為在此情況下第三個孩子已經是「不適用」:

每個獨立的運算式都以棕褐色背景標示。如您所見,這裡有三個獨立的運算式。最後一個包含一則訊息,只有在受訪者有一個以上的孩子時才會顯示。

以下是實際執行中的問卷螢幕截圖。

首次造訪該頁面時,您會看到如下畫面。請注意,畫面顯示的是「You have 0 children」,而不是「You have 0 child」。

如果我將孩子數量改為 1,即使仍在同一頁,顯示內容也會立即變成如下:

現在請注意文法已經正確:「You have 1 child」。

現在我將孩子數量改為 3,顯示內容會立即變成如下。

請注意,您現在會在底部看到條件訊息:「The sum of ages of your first 3 kids is 0.」。

現在我為我虛構的孩子輸入年齡,就會得到如下顯示,並加總他們的年齡:

同樣地,分數和顯示內容會在我輸入數值時立即更新,因此您可以用它來顯示評估分數的累計總和。

現在,我將孩子數量改為 2。顯示內容變成如下:

請注意,雖然我為第三個孩子輸入了 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 陳述式時，請嘗試計算括號的數量，儲存後檢查是否有語法錯誤，若有請加以修正。讓我們一起來看下面的範例。

下方使用的問題群組可從此處取得：量身訂製問卷範例.lsg

首先，在未輸入任何內容時，您只會看到「您好。」

如果您輸入姓名，畫面會顯示「您好 {name}。」

如果您輸入年齡，則會依據您是否為學齡前兒童，得到量身訂製的訊息：

學齡兒童、青少年或成人。以下是一位想要匿名的青少年：

以下是該群組的邏輯檔案。如您在「if-based」問題中所見，其中有依據該人年齡所設定的巢狀 if 陳述式。

在最初編輯此問題時，您很可能會在某個時候遇到括號數量錯誤的情況。以下是括號過少時會發生的狀況：

如果您將滑鼠移到以紅框圈起的 "if" 一字上，會顯示「Parentheses not balanced」（括號不成對）。在此例中，"already an adult!" 之後應有四個右括號，但只有三個。

反之，如果多了一個右括號，該括號會被紅框圈起，如下所示：

實際編輯該問題時，問題看起來如下：