This page is a translated version of the page New Template System in LS3.x and the translation is 100% complete.

簡介

請注意:在舊版 LimeSurvey 中,用來定義問卷外觀(包括顏色、字型、版面配置)及(部分)行為的檔案稱為「範本」。基於新的見解,現在這些檔案稱為「佈景主題」,而「範本」則保留給範例問卷使用。

在本頁中,您將學到如何:

使用 LimeSurvey 3.0 的新佈景主題系統。
使用繼承來管理您自己的佈景主題。
在佈景主題中新增圖片
管理問卷及問卷組的佈景主題選項

LimeSurvey 3 引入了全新的佈景主題引擎系統,以 Twig 1.29 和 Bootstrap 為基礎,並支援佈景主題繼承與佈景主題選項。它完全移除了舊有的取代關鍵字系統,因此現在前端 HTML 100% 都可以自訂。例如,在舊的佈景主題系統中,有一個關鍵字 {ASSESSMENTS},會在執行時被評估的 HTML 取代,佈景主題設計者無法自訂這段 HTML(除非使用 JavaScript)。現在則有一個名為 assessments.twig 的檔案,其中包含產生這段 HTML 的邏輯(以 Twig 撰寫)。在這些頁面中,我們將說明如何使用這個新的佈景主題引擎。

我們不會在此詳述 Twig 的運作方式。它是一種非常簡化的 PHP,並透過「沙盒」系統提供高度的安全性(我們將在佈景主題引擎核心程式碼的部分詳細說明)。如果您已經了解 PHP,就能非常輕鬆地掌握它;如果您不懂 PHP,學習起來也應該相當容易。請參閱 Twig 1.X 文件: https://twig.symfony.com/

使用管理介面進行編輯

佈景主題清單

在管理控制台上,現在有一個用來存取佈景主題清單的方塊:

清單分為 5 欄:

佈景主題的預覽:這只是位於佈景主題根目錄、名為「preview.png」的圖片檔
佈景主題的「標題」,如資訊清單(位於佈景主題根目錄的 config.xml)中所指定
佈景主題的說明:在其資訊清單中設定的字串
佈景主題的類型:核心佈景主題(隨 LimeSurvey 提供)、使用者佈景主題(新增於 upload 目錄)、XML 佈景主題(未載入資料庫)
延伸:如果該佈景主題延伸自另一個佈景主題,其名稱會顯示在此
一些動作按鈕:
- 安裝:會載入佈景主題的資訊清單,將其新增至資料庫,並可在問卷層級選用
- 解除安裝:會刪除資料庫中該佈景主題的設定項目
- 佈景主題編輯器:會將您導向佈景主題編輯器
- 佈景主題選項:會帶您進入佈景主題選項的全域設定

佈景主題編輯器

本文件假設您已經知道如何使用舊版 LS 中的佈景主題編輯器。

佈景主題編輯器已盡可能保持與原版相近。因此,開啟核心佈景主題時,您無法編輯它。但現在取代「複製」按鈕的是「延伸」按鈕。

佈景主題繼承概念速覽

在 LS3 中,佈景主題現在可以繼承自另一個佈景主題,也就是「延伸」另一個佈景主題。這表示該佈景主題的目錄幾乎是空的,只會包含與原始佈景主題不同的檔案(檢視、樣式表、腳本、資源等)。如此一來,您就能輕鬆為不同的使用者建立一系列佈景主題,而無需維護大量不同的佈景主題。例如:您可以有一個自製的佈景主題,然後為某間公司製作一個版本(含其標誌、樣式,或許在頁尾加上其網站連結等),再為另一間公司製作另一個版本,依此類推。之後若您更新自訂佈景主題的 CSS 或整體版面配置,所有繼承自它的佈景主題都會自動更新。請注意,繼承是遞迴的:一個佈景主題可以延伸另一個本身也延伸自其他佈景主題的佈景主題,依此類推。

這也表示,如果您延伸 LimeSurvey 的其中一個核心佈景主題,您仍然可以享有它的更新。

使用者介面的新功能

若要延伸 LimeSurvey 的 Monochrome 佈景主題,請前往佈景主題清單,點選 Monochrome 佈景主題的「佈景主題編輯器」按鈕。接著點選「延伸」,並確認新名稱「extends_monochrome」。

如果您現在(使用檔案或 FTP 用戶端)前往 upload 目錄,會看到已建立一個新目錄:upload/themes/extends_monochrome 其中包含一個 XML 檔案和數個目錄,但大部分目錄都是空的。它沒有檢視,也沒有 CSS 或 JS。不過,您仍然可以像選擇一般佈景主題一樣在問卷中選擇此佈景主題,其外觀會與 Monochrome 佈景主題完全相同。

延伸佈景主題時,原始佈景主題的資源(jpg、png 等)會一併複製。這是因為如果您將原始佈景主題的 CSS 檔案複製到本機,而該檔案引用了這些檔案(例如在 background-image 敘述中),它就需要在目前的佈景主題路徑中找到這些圖片。

extends_monochrome 佈景主題的佈景主題編輯器如下所示:

它與舊的佈景主題編輯器沒有太大差異。以下列出主要的不同之處:

檔案清單上的關鍵字 inherited。這表示該檔案不在佈景主題目錄中,將使用原始佈景主題的檔案。

主編輯器( ACE editor )會顯示所選檔案的內容。這些檔案不僅包含 HTML、CSS 或 JS,還包含 Twig 敘述。這些 Twig 敘述讓我們能夠將過去深藏於核心中的部分邏輯移到佈景主題檢視中,現在這些邏輯都可以自訂了。

因此,頂端選單的下拉式選單中現在有更多可用的畫面類型。您會注意到諸如「問卷清單」、「載入」、「儲存」、「錯誤」、「註冊」、「評估」、「列印答案」等頁面,這些頁面以前無法使用,或是無法真正自訂。

檔案清單底部的「tip」連結會告訴您在 HTML 中以 Twig 方式新增圖片的做法

「儲存更改」按鈕會變成 複製到本機佈景主題並儲存變更 按鈕

快速範例:新增圖片

複製到本機佈景主題並儲存變更 按鈕的功能正如其名:如果您編輯檔案內的任何內容,然後點選該按鈕,它會將檔案複製到您正在編輯的佈景主題,並儲存您的變更。
例如:點選檔案 layout_global.twig,然後在區塊 content( {% block content %})之前加入文字「TEST」,再點選該按鈕。您會看到檔案的標籤從「inherited」變成「local」,而現在該按鈕只是一個普通的 儲存更改 按鈕。

如果您開啟檔案總管並前往目錄 upload/themes/extends_monochrome/views/,會看到其中只有一個檔案,即 layout_global.twig,而且字串「TEST」就在其中。

現在我們不加入隨機文字,而是新增一張圖片。如果您點選 tip 連結,它會告訴您:
在 .twig 檔中使用圖片: {{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}
如果您已閱讀過 Twig 文件(此時您應該已經讀過),就會知道 {{ function( ) }} 會在畫面上輸出函式的結果。在這裡,該函式是 image( )。

如果您好奇它做了什麼,可以在這裡的程式碼中找到(RC3 版本):RC3 中的 image() 函式

如果您看不懂程式碼,不用擔心,您不需要知道它如何運作,只需要知道為什麼要使用它以及如何使用它。

您應該使用 image() 函式,原因有兩個:

image 函式會在佈景主題中逐層尋找圖片。如果您正在處理的佈景主題延伸自另一個佈景主題,而您將檔案複製到本機並在其中插入了圖片,但該圖片並未複製到本機佈景主題,它會沿著佈景主題繼承樹尋找該圖片所在的位置。
它會使用資源管理器(asset manager),因此能提升佈景主題的效能。如需更多相關資訊,請參閱 Yii Asset Manager 文件:http://www.yiiframework.com/wiki/148/understanding-assets/

因此,若要在佈景主題中新增圖片:

只要像平常一樣使用右側的檔案上傳器上傳圖片,然後在任何 twig 檔案中,將它新增到您想要的位置:

{{ image('./files/myfile.png') }}

如果您想為圖片新增替代文字(供螢幕閱讀器及 HTML 驗證使用),請加入:

如果您想新增 class 屬性及 id:

{{ image('./files/myfile.png'), ‘my alternative text’, {“class”: “a_nice_css_class”, “id”: “any_id”} }}

我們的待辦事項

讓使用者可以直接從編輯器上傳自訂的預覽檔案
新增一個按鈕,用來刪除本機檔案並恢復為繼承狀態
只複製 CSS 檔案中使用到的圖片(在資訊清單中將它們列為要複製的檔案)
提示目前的佈景主題延伸自哪個佈景主題(如果有的話)

佈景主題選項

LS3 的另一項新功能是佈景主題選項頁面。我們稍後會看到,佈景主題作者可以建立自己的選項,甚至是自己的管理選項頁面。在這裡,我們將快速了解核心佈景主題的選項頁面如何運作。若要存取全域層級的佈景主題選項:請在佈景主題清單中點選「佈景主題選項」

進階選項

開啟佈景主題選項標籤頁時，您可以選擇編輯其簡易選項或進階選項。「進階選項」只是一個單純的表單，讓您可以存取資料庫中主要的佈景主題設定欄位。若要了解其運作方式，您還應閱讀有關 XML 檔案以及從頭建立佈景主題的內容。因此，它相當複雜，專為進階使用者而設計。

不過，如果您確實想要編輯進階設定，請點選進階選項標籤頁

檔案 CSS:應加入到範本的 CSS 檔案;
Js 文件:應加入到範本的 JS 檔案;
檔案列印 CSS:列印範本時要載入的 CSS 檔案;
選項:此欄位包含應傳遞給範本檢視的選項(及其值);
CssFramework Name:要載入的 CSS 框架名稱。目前僅支援 Bootstrap 或不使用;
Cssframework Css:您可以在此欄位中以自訂版本取代核心 bootstrap.css;
Cssframework Js:您可以在此欄位中以自訂版本取代核心 boostrap.js;
要載入的套裝:您可以透過此設定載入 LimeSurvey 的一些核心資源套件。

您會注意到頂端有一個上傳輸入欄位,可讓您將檔案上傳到佈景主題的檔案目錄中。這些參數可用來變更佈景主題的整體外觀。

警告! : 除非您清楚自己在做什麼,否則請勿更動這些值!

簡易選項

簡易選項頁面來自範本本身。它是透過一個 twig 檔案和佈景主題 /options 目錄中的一些 JavaScript 製作而成: https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (連結已失效)

這個頁面在不同的佈景主題之間可以完全不同,我們強烈鼓勵佈景主題提供者打造自己的外觀與風格。

簡易選項頁面只是填入進階表單的輸入欄位。您可以在簡易頁面中開啟或關閉某項設定,然後觀察進階表單中的相關輸入欄位如何隨之變更。例如,在預設範本的簡易選項中,如果您將 Bootswatch 佈景主題變更為「Darkly」,然後點選進階選項的索引標籤(即使尚未儲存),您會看到欄位「Cssframework Css」從以下內容變更

{"replace": [["css/bootstrap.css","css/flatly.css"]]}
變更為
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
以下是核心佈景主題的各項簡易選項:

Ajax mode: 下一頁要透過 Ajax 載入(速度較快),還是透過重新載入頁面(較利於除錯)
背景圖片: 若設為「是」,將載入名為 pattern.png 的圖片(在 Master 版本中將改為檔案選擇器)
Box container: 若設為「否」,問題將不會包含在方框內(如此即可使用超過螢幕寬度的大型陣列)
Brandlogo: 若設為「否」,最上列會顯示問卷名稱;否則,您可以從檔案目錄中選擇一張圖片作為標誌圖片。
在正文上加上動畫: 若設為「是」,您可以選擇在載入問卷正文時套用的動畫
為問題加上動畫: 問題的設定方式相同
Animate alerts: 提示訊息的設定方式相同
Bootstrap theme: 在此可選擇要載入的 Bootstrap 佈景主題,這些主題來自 Bootswatch https://bootswatch.com/3/

動畫所使用的函式庫為 animate.css: https://daneden.github.io/animate.css/ 當然,佈景主題提供者也可以加入自己的動畫函式庫,或完全不使用動畫函式庫。

Monochrome 佈景主題使用與管理介面相同的 Bootstrap 色彩主題。它們並未使用 CSS 框架替換系統,而是單純新增一個 CSS 檔案。因此,這也為佈景主題提供者示範了另一種處理自訂佈景主題的方式。

繼承系統

在前面的部分中,我們已經了解佈景主題可以擴充另一個佈景主題。佈景主題的設定也可以繼承自另一個佈景主題的設定。也就是說,對於特定的佈景主題,您可以在以下層級進行設定:

全域層級(即我們剛剛看到、可從佈景主題清單存取的設定)
問卷群組層級
最後是問卷層級。

特定層級中的每個參數都可以繼承自上一層級:問卷群組繼承。首先,讓我們來看看問卷群組層級。

問卷群組層級

事實上,LS3 的另一項重大新功能就是問卷群組系統。您現在可以建立不同的群組來整理您的問卷。要存取該功能,請前往問卷清單,然後點選問卷組分頁:

在此清單中有兩個操作按鈕。若群組是空的,您可以將其刪除;否則,您一律可以編輯它。點選編輯按鈕後,即可進入問卷群組的設定頁面:

此頁面的第三個分頁稱為“此問卷群組的範本選項”。點選後,您會看到與佈景主題清單相同的佈景主題清單,只是這裡只會顯示選項按鈕(佈景主題編輯器只能從主清單進入)。
現在,若您點選預設範本的選項,將會看到以下畫面:

繼承全部 表示所有設定都將繼承自全域設定層級。
若您前往進階選項頁面,會看到所有欄位都設為繼承。
若您在簡易選項中將“繼承全部”設為“否”,您會再次看到與全域選項頁面非常相似的頁面。唯一的差別在於,每個欄位都可以設為是、否或繼承;而且每個下拉式選單都有一個 繼承' 值。

問卷群組可以是另一個群組的子群組。在這種情況下,它將繼承其父群組的設定。

問卷層級

編輯問卷時,您會在左側選單中看到一個新項目「佈景主題選項」。它會帶您前往目前問卷所選佈景主題的選項頁面。您會看到與問卷群組相同的繼承系統,但這次「繼承」表示該設定將繼承自該問卷所屬的問卷群組。

使用案例範例

假設您為不同公司(A 和 B)使用同一個佈景主題。您在全域層級設定好您偏好的選項(例如:啟用 Ajax、正文使用滑入動畫、提示使用脈衝動畫)。接著,您為每間公司建立一個問卷群組:為公司 A 建立一個問卷群組,用來存放該公司的所有問卷;並為公司 B 建立一個問卷群組,用來存放公司 B 的所有問卷。在這個層級,您只需設定標誌和背景,其他選項則保留為繼承。如此一來,群組 A 中的所有問卷都會使用公司 A 的標誌,群組 B 中的所有問卷則使用公司 B 的標誌。對於公司 A 的其中一份問卷,您可以依問卷主題使用不同的背景:只需在問卷層級的選項中變更背景即可。如果公司 B 的人表示脈衝提示過於強烈,希望改用較柔和的淡入效果,您只需在問卷群組 B 層級變更提示動畫,該群組中的所有問卷便會改用此動畫。如果公司 A 更換了標誌,您可以在問卷群組 A 層級進行變更,該群組中的所有問卷都會使用新的標誌。

這些範例是以核心佈景主題目前的選項為基礎。當然,如果您是佈景主題提供者,或是會一點 Twig 腳本,您也可以新增自己的選項。例如,您可以新增一個「頁尾資訊」選項,在其中加入公司網站或求助電話等資料。接著,如果公司 A 有不同的部門,且各有不同的電話號碼,您只需在問卷群組 A 中為每個部門建立一個子群組。每個子群組在這些選項中都可以有各自的電話號碼。

佈景主題自訂常見問題

此處整理了論壇中曾被提出的一些問題的解答,或許能幫助您自訂佈景主題。

自訂 CSS/JS:處理資源管理器(「為什麼我的變更沒有生效?」)

如果您嘗試使用慣用的編輯器直接編輯程式碼來更新佈景主題的 CSS/JS,可能會驚訝地發現您的變更並未生效。

自 2.50 版起,LS 使用 Yii 資源管理器: Yii 資源說明文件

它會將佈景主題的 CSS/JS 檔案移至 tmp/ 子目錄下,並使用隨機字串命名的資料夾(例如:"tmp/1ef64ml/")。因此,如果您變更了 css/js 檔案並通知資源管理器,這些檔案會被複製到一個名稱不同的新子目錄,使用者瀏覽器的快取也就會隨之更新,從而看到新的 css/js。否則,他們就必須自行清除瀏覽器快取。

以下是啟用資源管理器時,標頭中的 CSS 連結:

如您所見,它們全都指向 tmp/ 子資料夾。

以下是停用資源管理器時,標頭中的 CSS 連結:

如您所見,它們指向佈景主題的實際檔案。

當然,如果資源管理器不知道您已變更了檔案,舊 tmp/ 目錄中的舊檔案將維持不變,您的變更也就永遠不會生效。

因此,當您編輯佈景主題的 CSS/JS 時,有以下幾種做法:

您可以使用 LS 佈景主題編輯器: 它會處理資源管理器,您不必擔心任何事
您可以開啟除錯模式: 這會關閉資源管理器,因此會呼叫佈景主題實際的 css/js 檔案(但這樣一來,每次載入都必須重新整理瀏覽器快取)
您可以重新整理資源快取: 前往全域設定 -> 一般 -> 清除資源快取

使用佈景主題編輯器來編輯自訂 CSS 是目前最好的解決方案。

使用佈景主題編輯器有助於您了解新佈景主題引擎的架構。此外,如果您要自訂 fruity,請留意 CSS 的優先順序:大多數定義都使用選擇器 ".fruity"(body 元素的其中一個類別)

為我的佈景主題加入自訂字型

簡單的方法:使用 Google Font CDN

Bootswatch 問卷佈景主題使用 Google Font CDN。讓我們來看看它是如何運作的: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");

接著透過 CSS 規則使用 Lato 字型: https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72

body {
  ...
 font-family: "Lato";
 ...
}

您可以用這種方式在自訂佈景主題中使用任何 Google 字型。當然,您應該從佈景主題的選項中移除字型選擇器。請刪除 options.twig 中的這幾行: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

使用本機字型

當然,您也可以下載字型檔案,並從本機伺服器而非 Google CDN 使用它們(對隱私較有利)。以下是我們 noto 字型的本機版本,可作為如何操作的範例: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css

@font-face {
  font-family: 'Noto Sans';
  font-weight: 300;
  font-style: normal;
  src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...

您可以在佈景主題的 css 檔案中使用非常類似的定義,然後將檔案 NotoSans-Regular.ttf 複製到佈景主題的 css/font-src/ 資料夾中。

接著,如上所述將該字型套用到您的 body(或任何其他元素),並移除預設的選項字型選擇器。

在選項中建立您自己的字型選擇器

目前，您無法輕易使用核心字型選擇器在選項中新增您自己的字型。我們必須先讓終端使用者能夠上傳自訂套件（請參閱下一段：Fruity 字型選擇器剖析）。
操作方式如下：

使用 CDN 或本機伺服器，在您的佈景主題中新增兩種字型（my_custom_font 和 my_custom_other_font）
然後，在您的 css 檔案中新增兩個新的類別：

.font-my_custom_font {
 font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
 font-family: 'my_custom_other_font';
}

在佈景主題的 XML 檔案中，新增字型選項（預設值為 my_custom_font）：

    <options>
        ....
        <font>my_custom_font</font>
    </options>

在 option.twig 中加入下列程式碼以新增字型選擇器（目前尚未測試，若無法運作，請到論壇反應）：

            
            <div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
                <hr/>
            </div>
            <div class='row action_hide_on_inherit'>
                <div class='col-sm-12'>
                    <div class='panel panel-default'>
                        <div class='panel-heading'>{{ "My custom fonts" | t }}</div>
                        <div class='panel-body'>
                            <div class='form-group row'>
                                <label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
                                <div class='col-sm-12'>
                                    <select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
                                    {% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
                                        {% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
                                    {% endif %}
                                   <optgroup  label="{{ "My Custom fonts" | t }}">
                                   <option class="font-my_custom_font"     value="custom_font"   data-font-package=""  >Custom</option>
                                  <option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package=""  >Other</option>
                                  </optgroup>
                                   
                                    </select>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>
            </div>

現在，您的使用者應該可以在這兩種字型之間做選擇了。

Fruity 字型選擇器剖析

未來，我們將讓終端使用者能夠上傳自己的資源套件，包括字型套件，讓字型的各種自訂變得非常容易。
若要瞭解 Yii 套件：
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

LimeSurvey 套件定義在不同的檔案中。字型套件定義於此： https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
例如，Noto 字型套件定義於此： https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53

    'font-noto' => array(
        'devBaseUrl' => 'assets/fonts/',
        'basePath' => 'fonts',
        'css' => array(
            'noto.css',
        ),
    ),

它所包含的 noto.css 檔案位於此： https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
請注意檔案末尾的 css 類別 ".font-noto" 的定義：

@font-face {
  font-family: 'Noto Sans';
  ...
}
...
.font-noto{
    font-family: 'Noto Sans';
}

然後，在 Vanilla 佈景主題中，透過新增 noto 套件並將字型選項設為 noto 來使用 noto 字型：
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

        <packages>
             ....
            <add>font-noto</add>
        </packages>

https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58

    <options>
        ....
        <font>noto</font>
    </options>

接著，body 的字型類別會使用此值來定義： https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76

<body class=" ...  font-{{  aSurveyInfo.options.font }} ... " ... >

當然，XML 檔案只包含佈景主題設定的預設值。實際上，這些值是以 json 字串的形式定義並讀取於資料庫中（資料表 "template_configuration"（問題：是 "template_" 還是 "theme_"？））。option.js 檔案僅使用簡易選項中字型選擇器的值，來變更進階分頁表單中的值： https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

因此，當「上傳資源套件」功能推出後，只要新增一個掃描所有現有字型套件的指令碼，就能輕鬆將它們加入選擇器中。

新增佈景主題選項以控制問卷元素的位置與顯示

本教學將說明如何在擴充的佈景主題中新增選項，以便在不同位置顯示問卷元素。在此範例中，我們將建立佈景主題選項，讓問卷標題顯示於兩個不同的位置。

為求簡單，本教學以 LimeSurvey 3.4.3 版中 "bootswatch" 佈景主題的擴充為基礎。

建立自訂佈景主題

如上所述，擴充 "bootswatch" 佈景主題。
如上所述，將 custom.css 複製到本機佈景主題。

建立新的佈景主題選項

將 /themes/survey/bootswatch/options/ 的內容複製到 /upload/themes/survey/yourThemeName/options/。

在編輯器中開啟 /upload/themes/survey/yourThemeName/options/options.twig，找到 "{# Bootstrap Bootswatch theme #}"。在其上層 <div class='row'> 元素的正前方，加入以下內容：

		{# Custom survey name in navbar #}
		<div class='row'>
			<div class='col-sm-12 col-md-6'>

				<div class='form-group row'>
					<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
					<div class='col-sm-12'>
						<div class="btn-group" data-toggle="buttons">
							<label class="btn btn-default">
								<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
								Yes
							</label>
							<label class="btn btn-default">
								<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
								No
							</label>
						</div>
					</div>
				</div>
			</div>
		</div>
		<div class='row'>
			<hr/>
		</div>

		{# Custom survey name below progress bar #}
		<div class='row'>
			<div class='col-sm-12 col-md-6'>

				<div class='form-group row'>
					<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
					<div class='col-sm-12'>
						<div class="btn-group" data-toggle="buttons">
							<label class="btn btn-default">
								<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
								Yes
							</label>
							<label class="btn btn-default">
								<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
								No
							</label>
						</div>
					</div>
				</div>
			</div>
		</div>
		<div class='row'>
			<hr/>
		</div>

開啟 /upload/themes/survey/yourThemeName/config.xml，並在 "options" 區塊中新增兩個項目，使其如下所示：

    <options>
        <ajaxmode>on</ajaxmode>
        ...
        <surveyname1>on</surveyname1>
        <surveyname2>on</surveyname2>
    </options>

這樣應該會在佈景主題選項畫面中出現兩個新選項，如下所示：

導覽列中問卷標題的修改版檢視

建立新目錄 /upload/themes/survey/yourThemeName/views/subviews/header/。
將 /themes/survey/vanilla/views/subviews/header/nav_bar.twig 複製到該新目錄。

開啟 /themes/survey/vanilla/views/subviews/header/nav_bar.twig,找到「{# Logo option #}」。在其下方修改標誌/問卷名稱的 IF 陳述式,使其如下所示:

		{# Logo option #}
        {% if( aSurveyInfo.options.brandlogo == "on") %}
            <div class="{{ aSurveyInfo.class.navbarbrand }} logo-container"  {{ aSurveyInfo.attr.navbarbrand }}  >
                {{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
            </div>
        {% endif %}
        {% if( aSurveyInfo.options.surveyname1 == "on") %}
            <div class="{{ aSurveyInfo.class.navbarbrand }}"  {{ aSurveyInfo.attr.navbarbrand }} >
                {{ aSurveyInfo.name }}
            </div>
        {% endif %}

將類似以下的內容新增至 /upload/themes/survey/yourThemeName/css/custom.css:
```
.navbar-brand {
    line-height: 60px;
    font-size: 32px;
}
```
將「Survey name in navbar」佈景主題選項切換為「是」
您應該會看到如下畫面:

進度條下方問卷標題的修改版檢視

建立新目錄 /upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews。
將 /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig 複製到該新目錄。

開啟 /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig,並為問卷名稱新增 <h1> 元素,使其如下所示:

<div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>
 
    {# Custom survey name #}
    {% if( aSurveyInfo.options.surveyname2 == "on") %}
    	<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
    {% endif %}
 
    {# Group Name #}
    {{ include('./subviews/survey/group_subviews/group_name.twig') }}
 
    {# Group Description #}
    {{ include('./subviews/survey/group_subviews/group_desc.twig') }}
 
    {#
        PRESENT THE QUESTIONS
 
        This is the main part. It will render each question for this group
     #}
 
    <!-- PRESENT THE QUESTIONS -->
    {% for  aQuestion in aGroup.aQuestions %}
         {{ include('./subviews/survey/question_container.twig') }}
    {% endfor %}
 
    <!-- Hidden inputs -->
    {% if aGroup.show_last_group == true %}
        <input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
    {% endif %}
 
    {% if aGroup.show_last_answer == true %}
        <input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
    {% endif %}
</div>

將類似以下的內容新增至 /upload/themes/survey/yourThemeName/css/custom.css:

.navbar-brand {
    line-height: 60ph1.custom-survey-name {
	margin: 0;
	text-align: center;
}

將「Survey name below progress bar」佈景主題選項切換為「是」
您應該會看到如下畫面:

下載

延伸佈景主題範例:Media:Test_survey_names.zip

從頭建立佈景主題

文件即將推出。

目前僅提供一些小技巧。

佈景主題結構

檔案與目錄

從頭建立佈景主題時,您不需要遵循 Vanilla 的檔案/目錄結構/css/js。必要的 css/js 由核心新增(如有需要,您仍可將其移除)

您的佈景主題唯一必須具備的檔案是版面配置檔案:

layout_global.twig :呈現填寫問卷的頁面
layout_survey_list.twig :呈現問卷清單(若此佈景主題設為預設)
layout_errors.twig :用於呈現阻礙問卷顯示的錯誤。(錯誤的問卷 ID、預覽群組中的空群組等)
layout_user_forms.twig:呈現使用者表單,例如:憑證(問卷參與者)與註冊。
layout_print.twig :用於將問卷列印為 PDF
layout_printanswers.twig:列印答案

這些檔案的內容,以及它們是否包含其他檔案,完全由您決定。 Vanilla 中的所有其他檔案與目錄都純屬選用,您可以依自己的方式自由組織程式碼。

如果您閱讀前端呈現程式碼,會發現這些檔案名稱直接出現在其中,這就是它們必不可少的原因。

例如:https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462

內容

在 Vanilla 的 layout_global.twig 中,您會看到我們使用名為「include_content」的變數來決定要顯示的內容 https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

                    {% set sViewContent =  './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
                    {% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}

aSurveyInfo.include_content 會告訴您目前正在進行什麼操作:顯示問題?顯示送出結果?顯示全部清除?等等如您所見,在 vanilla 中,我們為每個操作建立一個要包含的檔案。因此,若想知道操作清單,只需查看 vanilla 的目錄 views/subviews/content,並去掉「twig」副檔名: https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

clearall.twig
firstpage.twig
load.twig
mainrow.twig
main.twig
optin.twig
optout.twig
outerframe.twig
printanswers.twig
quotas.twig
register.twig
save.twig
submit_preview.twig
submit.twig
userforms.twig

如果您已為 LimeSurvey 2.x 版本建立過佈景主題,會發現其中大多數對應於 LimeSurvey 2.x 的舊 pstpl 檔案。同樣地,您的佈景主題並沒有義務在此目錄中以這些名稱建立這些檔案。例如,您也可以直接在 layout_global.twig 中加入一個大型 switch,為每個操作提供所需的 HTML。

資訊清單 config.xml

佈景主題的資訊清單包含您佈景主題的主要資訊。安裝佈景主題時,資訊清單的內容會載入資料庫的兩個不同資料表:template 與 template_configuration。因此,每次修改佈景主題的資訊清單時,您都必須解除安裝後重新安裝(或僅重設)。由於開發佈景主題時這個過程相當麻煩,您可以強制直接使用 XML 檔案,而不是資料庫項目。為此,請在 config.php 中開啟除錯模式,並將 'force_xmlsettings_for_survey_rendering' 設為 true。

中繼資料區段

不複雜:只是關於您佈景主題的主要資訊。它會被寫入 templates_configuration 資料表

    <metadata>
        <name>the_name_of_your_theme</name>
        <title>The Title of your theme</title>
        <creationDate>16/10/2017</creationDate>
        <author>Your Name</author>
        <authorEmail>your@email.org</authorEmail>
        <authorUrl>http://www.yourwebsite.org</authorUrl>
        <copyright>Your Copyright </copyright>
        <license>Licence of your theme</license>
        <version>version of your theme</version>
        <apiVersion>3</apiVersion>
        <description>Description of your theme</description>
        <extends>parent_theme</extends>
    </metadata>

幾點說明:

name:將作為資料庫中的鍵值,因此必須是唯一的,且不應包含任何特殊字元(不可有空格)。請注意,大小寫將不被區分
Title:用於在各種清單中顯示您的佈景主題名稱。可以包含特殊字元
description:將用於問卷佈景主題主清單中。可以包含特殊字元,甚至可使用 HTML 程式碼
extends:選用,用於定義父佈景主題。因此,如果此佈景主題中缺少任何檔案(twig/js/css/jpg 等),系統會在父佈景主題中尋找

如果您延伸了三個核心佈景主題之一(Vanilla、Bootswatch、Fruity),可以將「extends」的值從一個父佈景主題改為另一個。當然,您必須重設佈景主題。

檔案區段

這是很重要的一個區段。它會以 JSON 陣列的形式寫入 template_configuration 資料表的 files_css、files_js、files_print_css 欄位。

例如:Material Premium 佈景主題的檔案區段:

    <files>
        <css>
            <add>css/bootstrap-material-design.css</add>
            <add>css/ripples.min.css</add>
            <replace>css/ajaxify.css</replace>
            <replace>css/theme.css</replace>
            <replace>css/custom.css</replace>
            <remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
        </css>
        <js>
            <replace>scripts/theme.js</replace>
            <replace>scripts/ajaxify.js</replace>
            <add>scripts/material.js</add>
            <add>scripts/ripples.min.js</add>
            <replace>scripts/custom.js</replace>
        </js>
        <print_css>
            <add>css/print_theme.css</add>
        </print_css>
    </files>

此區段中的所有 CSS/JS 檔案都會在問卷啟動時載入(在 ajax 模式下。若 ajax 模式關閉,則每一頁當然都會重新載入所有檔案)。

它們會被加入以佈景主題名稱命名的 Yii Asset 套件中。因此,當資源管理器開啟時(除錯模式關閉),這些檔案會與佈景主題的其餘部分一起複製到 tmp 目錄(因此您可以在 CSS 與 JS 中使用相對路徑來存取圖片檔案)。關於 Yii 的資源管理器:https://www.yiiframework.com/wiki/148/understanding-assets 關於 Yii 的套件:http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

它們會使用繼承系統。這表示如果您將 CSS/JS 檔案加入某個佈景主題,但該佈景主題中並不存在此檔案,引擎會查找此佈景主題的所有上層佈景主題,並使用找到的第一個。因此,如果使用者透過佈景主題編輯器延伸您的佈景主題,所有這些檔案都會被他的佈景主題繼承。這些關鍵字就是指此繼承系統。

add :它會將檔案新增至佈景主題及其所有繼承的佈景主題
replace:它會取代其上層佈景主題的檔案
remove:它會從任何套件中移除該檔案,甚至包括核心套件(自 3.14 起)

請記住,您可以在 config.php 中設定 'force_xmlsettings_for_survey_rendering',讓設定從 XML 而非資料庫讀取(無需重設)。這將使測試 XML 檔案的修改更加容易,並避免您在每次修改 XML 時都得解除安裝/重新安裝佈景主題。

關於這些關鍵字的幾點說明:

繼承提示

如前所述,"add" 關鍵字可以指向位於某個父佈景主題中的檔案。因此,您可以在此區段中 "add" 一個檔案,即使該檔案不在您的佈景主題中,而是位於其某個父佈景主題中。引擎會搜尋其所有父佈景主題,並使用找到的第一個檔案。如果找不到該檔案,且在設定中已啟用除錯模式、在全域設定中已啟用前端 JS 除錯模式,主控台中會顯示警告訊息。例如:如果我們在 my_theme 中新增:<add>css/unexisting.css</add>,在主控台中會看到:

 (¯`·._.·(¯`·._.· Theme Configuration Error  ·._.·´¯)·._.·´¯) 

Can't find file 'css/unexisting.css' defined in theme 'my_theme'

如果除錯模式已關閉,則完全不會顯示任何錯誤。引擎會直接忽略錯誤的 add 陳述式。

何時使用 add、何時使用 replace、何時可以直接交由父佈景主題處理?

首先:add 和 replace 其實是同一個關鍵字。您可以使用其中任何一個,引擎的處理方式完全相同。兩者之所以有所區分,是為了讓閱讀者了解您的意圖。

您無法新增與母佈景主題同名的檔案:它一律會取代原檔案。例如:如果有一個檔案 "my_mother_theme/foo.css",而您在子佈景主題中新增了一個名為 "foo.css" 的檔案,則只有 "daughter_theme/foo.css" 會被加入佈景主題。如果您想保留 "my_mother_theme/foo.css",請為 "daughter_theme/foo.css" 選擇其他名稱,例如 "daughter_theme/bar.css"。因此,關鍵字 "add" 可以當作 "replace" 關鍵字使用。

原因在於:這樣可以讓繼承佈景主題的自動產生更為簡單,直接複製檔案區段即可運作(延伸檔案時無需將 "add" 改名為 "replace")。

為了說明清楚,讓我們以 Fruity 為例。以下是它的 CSS 檔案區段:

        <css>
            <add>css/variations/sea_green.css</add>
            <replace>css/animate.css</replace>
            <replace>css/theme.css</replace>
            <replace>css/custom.css</replace>
        </css>

如果您查看 Fruity 中的 custom.css 檔案,會發現它與 Vanilla 的完全相同。我們可以刪除 Fruity 內的 custom.css 檔案,這樣就會載入 Vanilla 的檔案。我們也可以從 Fruity 的資訊清單中移除陳述式 <replace>custom.css</replace>,這樣就會使用 Vanilla 的陳述式,並載入 Vanilla 的 custom.css。

那麼,為什麼我們還要在 Fruity 的資訊清單中使用陳述式 <replace>custom.css</replace> 呢?答案很簡單:因為我們希望終端使用者能夠延伸 Fruity 佈景主題,在其本機佈景主題中修改該檔案,並從其繼承的佈景主題載入修改後的檔案。要理解這一點,只要延伸 Fruity 並查看延伸後的佈景主題即可。延伸後的佈景主題甚至沒有 custom.css 檔案,因此會使用 Fruity 的檔案。但是:如果使用者在延伸的佈景主題中建立了這個檔案(在佈景主題編輯器中點選 "延伸"),則會從其佈景主題載入該檔案。

總結來說: 如果您從頭建立一個不延伸任何佈景主題的佈景主題,只要使用 add 陳述式來新增您的 CSS/JS 檔案即可,非常簡單。如果您建立的佈景主題延伸自另一個佈景主題,且不希望使用者能夠延伸母佈景主題的 CSS/JS 檔案:請不要在資訊清單中使用 add 陳述式。檔案仍會從母佈景主題的設定中載入。如果您建立的佈景主題延伸自另一個佈景主題,且想要取代母佈景主題的某個檔案:請使用 replace 關鍵字(add 關鍵字會有相同的結果)。如果您建立的佈景主題延伸自另一個佈景主題,且您不取代某個 CSS/JS 檔案,但希望使用者能夠延伸該檔案:請在資訊清單中對該檔案使用 "replace" 陳述式。即使您並未取代該檔案,在資訊清單中使用 replace 關鍵字,即表示允許使用者在需要時這麼做。

只有最後這種情況需要稍微動腦筋才能理解,其他所有情況都很簡單。

您也可以直接在 Twig 程式碼中註冊 CSS 和 JS 檔案。這些檔案只會在請求該 Twig 檔案時才會載入。如果您希望使用者能夠透過佈景主題編輯器繼承這些 JS/CSS 檔案,請記得使用函式 Template:RegisterTemplateCssFile('my style.css') 和 Template:RegisterTemplateScript('my script.js')。如果不使用這些函式,您的佈景主題可能仍可運作,但其繼承功能將會失效。其邏輯與 Template:Image('my picture.jpg') 函式相同。

remove 關鍵字

remove 關鍵字自 3.14 版起才可使用。透過它,您可以從任何套件中移除任何 CSS 檔案,甚至是核心套件。Material Premium 佈景主題便使用它來移除 Awesome Bootstrap Checkbox 的檔案:

<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>

因此您應該使用與套件中檔案完全相同的語法(例如:僅使用 "awesome-bootstrap-checkbox.css" 而不含資料夾路徑將無法運作)。您可以在 /application/config/packages.php 和 config/third_party.php 中找到核心套件及其檔案的完整清單。例如,針對 awesome-bootstrap-checkbox.css: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

        'css'=> array(
            'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
        ),

另一種找出 remove 標籤中應使用的確切名稱的方法,是開啟資產管理員(關閉除錯模式,或在設定中將 'use_asset_manager'=>true)。接著,應使用的路徑就是 tmp 目錄中隨機目錄之後的部分。例如,針對 awesome-bootstrap-checkbox.css:

<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />

不應移除的檔案:

jquery-3.1.1.min.js :必要

jquery-migrate-3.0.0.min.js :必要

survey.js :必要

moment-with-locales.min.js :日期問題類型所需(我想其他一些功能也需要)

em_javascript.js :所有 ExpressionScript JavaScript 所需

選項區段

此區段與您佈景主題的選項有關。它會以 JSON 陣列的形式,用來填入資料表 template_configuration 的 "options" 欄位。

進一步資訊

可用函式

一些注意事項

注意:如果您編輯了佈景主題的 XML 檔案,必須解除安裝後再重新安裝該佈景主題,變更才會生效。

注意:為避免此情況,您可以強制使用 XML 而非資料庫。請在 config.php 中開啟除錯模式,並取消註解以下內容:

'force_xmlsettings_for_survey_rendering' => true, // 若要強制使用 XML 檔案而非資料庫(方便開發佈景主題),請取消此行註解

請注意:所有內容(包括選項等)都將從 XML 載入

注意:如果您手動編輯 CSS/JS 檔案(未使用佈景主題編輯器),且除錯模式已關閉,現在可以強制清除資源檔。請在「全域設定」的「一般」索引標籤中,按一下「清除資源快取」按鈕。

注意:如果您移除該區段

主要章節

LS3.x 的新範本系統

From LimeSurvey Manual

簡介