Actions

LS3.xの新しいテンプレートシステム

From LimeSurvey Manual

Revision as of 01:32, 13 May 2019 by Bravehorse (talk | contribs) (Created page with "aSurveyInfo.include_contentは、現在どのようなアクションが行われているか（質問表示、結果送信、すべてクリアなど）を示します。 ご...")
Other languages:

はじめに

このページでは、以下の方法について学習します。

  • LimeSurvey 3.0の新しいテーマシステムの使用
  • 継承による独自テーマの管理
  • テーマへの画像追加
  • アンケートとアンケートグループのテーマオプション管理

LimeSurvey 3では、Twig 1.29、Bootstrapに基づいた完全な新しいテンプレートエンジンシステムを導入し、テンプレートの継承とテンプレートオプションが利用可能になりました。これにより、古い置換キーワードシステムが完全にいらなくなり、フロントエンドHTMLの100％をカスタマイズすることができます。たとえば、古いテンプレートシステムでは、実行時に評価用HTMLに置き換えられるキーワード{ASSESSMENTS}がありました。テンプレートデザイナーは、JavaScriptを使用する以外にこのHTMLをカスタマイズする方法がありませんでした。今では、このHTMLを生成するためのロジック（Twigで書かれています）を含むassessmentments.twigというファイルがあります。こらのページでは、この新しいテンプレートエンジンの使用方法について説明します。

ここでは、Twigの仕組みは詳しく説明しません。これは非常に単純化されたPHPのようなもので、“サンドボックス”と呼ばれるシステムにより高度なセキュリティが提供されます（Theme Engine Coreコードの部分で詳しく説明します）。すでにPHPを知っていれば、習得するのは非常に簡単です。PHPを知らないとしても、習得するのはかなり簡単なはずです。Twig 1.Xのドキュメントをご覧ください。https://twig.symfony.com/

管理インタフェースを使用した編集

テンプレートリスト

管理ダッシュボードに、テンプレートリストにアクセスするためのボックスが追加されました。

RC3の新規インストール後のテンプレートリスト


リストは5つの列に分かれています。

  • テンプレートのプレビュー: テンプレートのルートにある“preview.png”という画像ファイルです。
  • マニフェストで指定されているテンプレートの“タイトル”（テンプレートのルートにあるconfig.xml）
  • テンプレートの説明: マニフェストに設定された文字列
  • テンプレートのタイプ: コアテンプレート（LimeSurvey提供）、ユーザーテンプレート（アップロードディレクトリに追加）、XMLテンプレート（データベースに読み込まれない）
  • 拡張: テンプレートが別のテンプレートを拡張する場合は、その名前がここに表示されます。
  • アクションボタン:
    • インストール: テンプレートのマニフェストを読み込んでデータベースに追加し、アンケートレベルで選択できるようにします。
    • アンインストール：データベース内のテンプレートの設定エントリーを削除します。
    • テンプレートエディター: テンプレートエディターにリダイレクトされます。
    • テンプレートオプション：テンプレートオプションのグローバル設定を行います。

テンプレートエディター

このドキュメントは、以前のバージョンのLSでテンプレートエディタを使用する方法をすでに知っていることを前提としています。


テンプレートエディターは元のものにできるだけ近づけて維持されています。コアテンプレートを開いても編集できません。“コピー”ボタンではなく、“拡張ボタン”があります。

テンプレートを拡張する
テンプレートを拡張する

テンプレート継承の考え方について

LS3では、テンプレートは別のテンプレートから継承できるようになり、別のテンプレートを“拡張”することができます。これは、テンプレートディレクトリーは最初は空で、元のものと異なるファイル（ビュー、スタイルシート、スクリプト、リソースなど）のみが保存されます。そうすることで、多くのテンプレートを維持することなく、多くのユーザー向けのテンプレートを簡単に作成できます。たとえば、独自の自家製テンプレートを持つとともに、ある会社向けのバージョン（ロゴ、そのスタイル、フッターなどに配置するWebサイトへのリンクなど）、さらに別の会社向けのバージョンを持つことができます。カスタムテンプレートのCSSまたはグローバルレイアウトを更新すると、それを継承するすべてのテンプレートが自動的に更新されます。テンプレートは他のテンプレートを拡張するテンプレートを拡張することができる、といった具合に、継承は再帰的になります。

LimeSurveyの主要なテンプレートを拡張すると、そのアップデートからのメリットを受けられるということでもあります。

ユーザーインターフェイスの新規性

LimeSurveyのMonochromeテンプレートを拡張するには、Templateリストに移動して、Monochromeテンプレートの“テンプレートエディター”ボタンをクリックします。次に、“拡張”をクリックして、新しい名前が“extends_monochrome”となっていることを確認します。

ファイル/ftpクライアントを使用してアップロードディレクトリに移動すると、新しいディレクトリupload/templates/extends_monochromeが作成されていることがわかります。これにはXMLファイルとディレクトリが含まれていますが、ほとんどのディレクトリは空です。ビューもCSSもJSもありません。しかし、このテンプレートはアンケートから正常なテンプレートとして選択することができ、monochromeテンプレートとまったく同じように見えます。

作成直後のテンプレートツリー（ディレクトリーとファイル）です。最初は空です。
作成直後のテンプレートツリー（ディレクトリーとファイル）です。最初は空です。
元のテンプレートのリソース（jpg、pngなど）は、テンプレートを拡張するときにコピーされます。これは、CSSファイルを元のテンプレートからローカルにコピーし、そのファイルを背景画像ステートメントなどで参照する場合、現在のテンプレートパスからそれらの画像にたどり着く必要があるからです。

extend_monochromeテンプレートのテンプレートエディタは次のようになります。

extends_monochromeテンプレートの編集
extends_monochromeテンプレートの編集



古いテンプレートエディターと大きな違いはありません。主なものを挙げます。  

  • ファイルリストにある継承というキーワード。これは、ファイルがテンプレートディレクトリーに存在せず、元のテンプレートのファイルが使用されることを意味します。


  • メインエディター（ACE editor ）には、選択したファイルの内容が表示されます。ファイルには、HTML、CSS、またはJSだけでなく、Twigステートメントも含まれています。これらのTwigステートメントは、以前はコアの深いところに位置していたテンプレートビューにいくつかのロジックをプッシュできるようになり、カスタマイズすることができます。
アンケートリストのtwigコードの例
アンケートリストのtwigコードの例


  • このため、トップメニューのドロップダウンセレクタで、より多くの画面タイプを利用できるようになりました。以前には利用もカスタマイズもできなかった‘アンケートリスト’、‘読み込み’、‘保存’、‘エラー’、‘登録’、‘評価’、‘回答の印刷’などのページがあります。
すべての画面でのカスタマイズ
すべての画面でのカスタマイズ


  • ファイルリストの一番下にある‘tip’リンクは、HTMLに画像をTwigで追加する方法を表示します。


  • ‘変更を保存’ボタンはローカルのテンプレートにコピーし、変更を保存するボタンになっています。

簡単な例: 画像の追加

ローカテンプレートにコピーして変更を保存するボタンは、ファイル内の何かを編集してそのボタンをクリックすると、ファイルを編集中のテンプレートにコピーして変更を保存します。
たとえば、layout_global.twigというファイルをクリックし、ブロックコンテンツ（{% block content %}）の直前にテキスト “TEST”を追加し、ボタンをクリックします。ファイルのラベルが “継承”から “ローカル”に変更され、ボタンが単純な変更を保存するボタンになっていることがわかります。

ボタンクリック直後
ボタンクリック直後


ファイルエクスプローラーを開いてupload/templates/extend_monochrome/views/ディレクトリーに移動すると、layout_global.twigというファイルが1つだけあり、その中に文字列“TEST”がそこにあることがわかります。

ファイルがテンプレートに表示された
ファイルがテンプレートに表示された



今、ランダムなテキストを追加する代わりに画像を追加します。TIPリンクをクリックすると、次のように表示されます。
.twigファイルで画像を使用するには、次のようにします。 {{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}
Twigのドキュメントを読むと（この時点ですでに読んでいるべきですが）、{{ function( ) }}によって関数の結果がスクリーンに表示されます。ここでは、その関数とはimaga()です。

詳しく知りたい場合は、ここからコード（RC3バージョン）を見ることができます。 RC3におけるimage()関数

コードを理解できない場合でも心配する必要はありません。どのように動作するのか知っている必要はありませんが、使う理由と使い方を理解していればいいのです。


次の2つの理由から、image()関数を使用する必要があります。

  • image関数はテンプレートを検索して画像を見つけます。作業中のテンプレートが別のテンプレートに拡張されていて、画像をローカルに挿入した場所にファイルをコピーしたものの、その画像がローカルテーマにコピーされていない場合であっても、テンプレート継承ツリーを検索して、その画像がどこにあるかを見つけます。
  • アセットマネージャーを使用するので、テンプレートのパフォーマンスを向上させます。詳細については、Yii Asset Managerのマニュアルを参照してください。http://www.yiiframework.com/wiki/148/understanding-assets/

テーマに画像を追加するには、

  • 右側のファイルアップローダーを使っていつものようにアップロードし、twigファイルの必要な場所に追加してください。

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

  • 画像の代替テキスト（スクリーンリーダーやHTML検証向け）を追加する場合は、次のようにします。

{{ image('./files/myfile.png'), ‘これが代替テキスト’ }}

  • クラス属性を追加し、そのクラスにidを追加する場合は、次のようにします。

{{ image('./files/myfile.png'), ‘これが代替テキスト’, {“class”: “a_nice_css_class”, “id”: “any_id”} }}

開発検討中の事項

  • エディター自体からカスタムプレビューファイルをアップロードできるようにする
  • ローカルファイルを削除し継承されたステートメントに戻るボタンを追加する
  • CSSファイルで使用されている画像のみをコピーする（コピーすべきファイルとしてマニフェストに記載します）
  • 現在のテンプレートを拡張したものがどのテンプレートかをわかるようにする（もしあれば）

テンプレートオプション

LS3のもう一つの目新しい点は、テンプレートのオプションページです。後で説明するように、テンプレート作成者は独自のオプションや独自の管理オプションページを作成することもできます。ここでは、コアテンプレートのオプションページの仕組みを簡単に見ていきます。グローバルレベルでテンプレートオプションにアクセスするには、テンプレートリストの“テーマオプション”をクリックします。

詳細オプション

Other languages:

テーマオプションタブを開くと、 簡単なオプションか高度なオプションのどちらかを使って編集するか選ぶことができます。“高度なオプション”は、データベースからメインのテーマ設定欄に直接アクセスできるフォームです。動作原理を理解するため、XMLファイルやスクラッチでテーマを作成することも理解しなければなりません。したがって、非常に複雑で上級者向けです。

それでも高度な設定の編集をしたければ、高度なオプションタブをクリックします。



  • Files css: テンプレートに含めるCSSファイル
  • Files js: テンプレートに含めるJSファイル
  • Files Print Css: テンプレートを印刷するときに読み込むCSSファイル
  • Options: テンプレートビューに必要なオプション（とその設定値）
  • CssFramework Name: 読み込むCSSフレームワークの名前。現時点では、Bootstrapか何も指定しないかとどちらかです。
  • Cssframework Css: コアのbootstrap.cssを、カスタマイズしたものに置き換えます。
  • Cssframework Js: コアのbootstrap.jsを、カスタマイズしたものに置き換えます。
  • Packages To Load: この設定により、LimeSurveyからコアのアセットパッケージを読み込ませることができます。

画面上部から、テーマのディレクトリーにファイルをアップロードすることができます。 これらのパラメーターは、テーマの全体的な外観を変えるために使用します。

  注意! : 意味がわからない値には手を出さないでください!


簡単オプション

簡単オプションページは、テンプレート自体から生成されます。これは、template/optionsディレクトリーにあるtwigファイルと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モード: 次のページをajax（高速）またはページリロード（デバッグ目的に適しています）経由でロードするかどうかを指定します。
  • 背景画像: 「Yes」に設定すると、pattern.pngという画像がロードされます（マスターのファイルセレクタに置き換えられます）
  • ボックスコンテナ: 「No」に設定すると、質問がボックスに含まれなくなります（スクリーンの幅よりも大きい大きな配列を使用することができます）
  • Brandlogo: 「no」に設定すると、アンケートの名前がトップバーに表示されます。「Yes」の場合は、ファイルディレクトリ内の画像の1つをロゴ画像として使用することができます。
  • 本体のアニメーション: 「yes」に設定すると、アンケートの本文がロードされたときに適用するアニメーションの1つを選択できます
  • 質問のアニメーション: 質問について同様
  • 警告のアニメーション: 警告について同様
  • Bootstrapテーマ: ここでは、ロードするブートストラップテーマを選択できます。Bootswatchは、次のサイトから来ています。https://bootswatch.com/3/


アニメーションに使用されるライブラリはanimate.cssです。https://daneden.github.io/animate.css/ もちろん、テンプレート提供者は独自のアニメーションライブラリを追加することもできますし、アニメーションライブラリをまったく追加しないこともできます。

monochromeのテンプレートは、管理ユーザーインターフェイスと同じブートストラップカラーテーマを使用します。これらはCSSフレームワークの置換システムを使用せず、CSSファイルを追加するだけです。つまり、テンプレート提供者がカスタムテーマを扱う別の方法を示しています。

継承システム

これまで、テンプレートを別のテンプレートに拡張できることがわかりました。テンプレート設定についても、別のテンプレート設定から継承することができます。つまり、個々のテンプレートについて以下のレベルで設定することができます。

  • グローバルレベル（テンプレートリストからアクセスできるもの）
  • アンケートグループレベル
  • アンケートレベル

各レベルのそれぞれのパラメータは、上位レベルから継承することができます。まず、アンケートグループレベルを見てみましょう。

アンケートグループレベル

LS3の重要な新規性の1つとして、アンケートグループシステムが挙げられます。さまざまなグループを作成してアンケートを整理できるようになりました。アクセスするには、アンケートリストに行き、アンケートグループタブをクリックします。

アンケートグループタブ


このリストには、2つの操作ボタンがあります。グループが空の場合は、削除できます。空でない場合は、編集することができます。編集ボタンをクリックすると、アンケートグループ設定ページが表示されます。

既定のアンケートグループの編集


このページの3番目のタブは、“このアンケートグループのテンプレートオプション”と呼ばれています。ここをクリックすると、テンプレートリストと同じテンプレートのリストが表示されますが、ここではオプションボタンのみが表示されます（テンプレートエディターにはメインリストからのみアクセスできます）。
既定のテンプレートのオプションをクリックすると、次のように表示されます。

アンケートグループでは、テンプレートオプションはデフォルトで継承される


  • Inherit everything（すべて継承）ということは、すべての設定がグローバル設定レベルから継承されることを意味します。
  • 高度なオプションページに行くと、すべてのフィールドが継承されて設定されていることがわかります。
  • 簡単オプションの"Inherit everything"で"いいえ"を選択すると、グローバルオプションページと非常によく似たページが再び表示されます。唯一の違いは、フィールドごとにはい、いいえ、または継承（inherit）に設定できることです。各セレクタに継承があります。
個々の設定は継承という値がある
アンケートグループは、別のグループの子になることができます。この場合、親から継承します。

アンケートレベル

アンケートを編集するときは、左のバーメニューに“テンプレートオプション”という新しいエントリーが表示されます。現在のアンケート用に選択されたテンプレートのオプションページに移動します。アンケートグループと同じ継承システムがありますが、この場合の継承は、アンケートが属するアンケートグループから設定値が継承されることを意味します。

アンケートレベルでのテンプレートオプション

ユースケースの例

たとえば、異なる企業（AとB）に1つのテンプレートを使用しているとします。お気に入りのオプションは、グローバルレベルで設定します（例：ajaxはon、本体のアニメーションはスライドイン、警告はパルス）。次に、各会社のアンケートグループを作成します。会社Aのアンケートグループは、この会社のすべてのアンケートをホストし、会社Bのアンケートグループは、会社Bのすべてのアンケートをホストします。このレベルでは、ロゴと背景のみを設定し、他のオプションは継承させます。これにより、グループAのすべてのアンケートでは、会社Aのロゴを使用し、グループBのすべてのアンケートは、会社Bのロゴを使用します。会社Aのあるアンケートで、トピックと関連して異なる背景を使用できます。アンケートレベルでオプションの背景を変更するだけです。B社の誰かが、パルスで表示される警告があまりにも目立ち、フェードインのようなスムーズなものを好む場合は、アンケートグループBレベルで警告のアニメーションを変更するだけで、このグループのすべてのアンケートでこのアニメーションが使用されるようになります。会社Aがロゴを変更した場合は、アンケートグループAのレベルで変更することができ、このグループのすべてのアンケートで新しいロゴが使用されます。

この例は、コアテーマの現在のオプションに基づいています。ただし、あなたがテンプレート提供者で、またtwigで少しスクリプトを作成できる場合は、独自のオプションを追加することももちろん可能です。たとえば、会社のウェブサイトや電話番号のようなデータを追加するためのオプション "info footer"を追加することができます。次に、A社に個別の電話番号を持つ部門がある場合、アンケートグループAに各部門ごとに1つのサブグループを作成できます。各サブグループは、このオプションで独自の電話番号を持つことができます。

テーマのカスタマイズに関するFAQ

ここでは、フォーラムで提起された質問に対する回答を紹介しており、テーマのカスタマイズに役立てることができます。

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要素のクラスの1つ）を使用します。

テーマにカスタムフォントを追加する

簡単な方法: Google Font CDNを使用する

Bootswatch Surveyテーマは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");

LatoフォントがCSSルールで使われています。 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ファイルに非常によく似た定義を使用し、テーマのcss/font-src/ フォルダーにNotoSans-Regular.ttfファイルをコピーします。

次に、そのフォントを上記のようにbody（または他の要素）に適用し、既定のフォントセレクターを削除します。

オプションに独自のフォントセレクターを作成する

今のところ、コアフォントセレクターを使ってオプションで独自のフォントを簡単に追加することはできません。最初に、エンドユーザーにカスタムパッケージをアップロードできるようにする必要があります（次の段落「Fruityフォントセレクターを理解する」を見てください。） 。
やり方は以下の通りです。

  • CDNまたはローカルサーバーを使用して、テーマに2つのフォント（my_custom_fontとmy_custom_other_font）を追加します。
  • 次に、cssファイルで、2つの新しいクラスを追加します。


.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 %}
                                        {% 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>


これでユーザーが2つのフォントを選択できるようになりました。

A look into the Fruity Font Selectorを理解する

将来的には、エンドユーザーがフォントパッケージを含む独自のアセットパッケージをアップロードできるようになる予定です。これにより、非常に簡単にフォントの任意のカスタマイズができるようになります。
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"テーブル）。option.jsファイルでは、簡単オプションのフォントセレクタの値は詳細設定タブフォーム内の値を変更するために使われます。https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

したがって、"アセットパッケージのアップロード"機能を利用できるようになると、既存のフォントパッケージをすべてスキャンしてセレクタに追加するスクリプトを簡単に追加できるようになります。

アンケート要素の配置と表示を制御するテーマオプションの追加

このチュートリアルでは、拡張テーマにオプションを追加してさまざまな場所にアンケート要素を表示する方法を示します。ここでは、2つの異なる場所にアンケートのタイトルを表示するためのテーマオプションを作成します。

わかりやすくするため、このチュートリアルは、LimeSurveyバージョン3.4.3の"bootswatch"テーマの拡張をベースとします。

カスタムテーマの作成

  1. 上記のように"bootswatch"テーマを拡張します。
  2. 上記のようにcustom.cssをローカルテンプレートにコピーします。

新たなテンプレートオプションの作成

  1. /themes/survey/bootswatch/options/の内容を/upload/themes/survey/yourThemeName/options/にコピーします。
  2. エディターで/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>
  3. /upload/themes/survey/yourThemeName/config.xmlを開き、"options"ブロックに2つのアイテムを以下のように追加します。 
        <options>
        <ajaxmode>on</ajaxmode>
        ...
        <surveyname1>on</surveyname1>
        <surveyname2>on</surveyname2>
    </options>
  4. これにより、テーマオプション画面に2つの新しいオプションが次のように追加されます。

ナビゲーションバーのアンケートタイトルの見た目を変更する

  1. 次の新しいディレクトリーを作成します。/upload/themes/survey/yourThemeName/views/subviews/header/
  2. /themes/survey/vanilla/views/subviews/header/nav_bar.twigをコピーし新しいディレクトリーにコピーします。
  3. /themes/survey/vanilla/views/subviews/header/nav_bar.twigを開き、"{# Logo option #}"を探します。その下で、 logo/survey-nameの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 %}
  4. /upload/themes/survey/yourThemeName/css/custom.cssに次のような記述を追加します。
    .navbar-brand {
    line-height: 60px;
    font-size: 32px;
}
  5. "Survey name in navbar"というテーマオプションを"Yes"にします。
  6. このようになります。

プログレスバーの下にあるアンケートタイトルの見た目を変更する

  1. 次の新しいディレクトリーを作成します。/upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews
  2. /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twigを新しいディレクトリーにコピーします。
  3. /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>
  4. /upload/themes/survey/yourThemeName/css/custom.cssに次のような記述を追加します。
    .navbar-brand {
    line-height: 60ph1.custom-survey-name {
	margin: 0;
	text-align: center;
}
  5. "Survey name below progress bar"というテーマオプションを"Yes"にします。
  6. このようになります。

ダウンロード

テーマをスクラッチで作成する

ドキュメントは準備中です。

取り急ぎ、いくつかのヒントを紹介します。

テーマの構造

ファイルとディレクトリー

スクラッチでテーマを作成するときは、Vanillaのfile/directory structure/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では、アクションによってインクルードするファイルを1つ作成します。アクションのリストを知りたい場合は、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

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x. Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

マニフェストconfig.xml

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.phpn turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

メタデータセクション

Nothing complex: just the main infos about your theme. It will be pushed in the table 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>


Few remarks:

  • name: will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
  • Title: will be used to display your theme name in the different lists. It can have special chars
  • description: will be used in the main list of survey theme. It can contains special chars, and even HTML code by using
  • extends: optional, it defines the parent themes. So if any file is not present in this theme (twig/js/css/jpg, etc) it will look for it in the parent theme


If you extended one of the the 3 core themes (Vanilla, Bootswatch, Fruity), you can change the "extends" value from one parent theme to the other. Of course, you'll have to reset the theme.



ファイルセクション

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme: 

    <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>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).


They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files). About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail


They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.


  • add : it will add the file to the theme, and to all its inherited theme
  • replace: it will replace the the file of its mother theme
  • remove: it will remove the file from any package, even the core package (since 3.14)
Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML


Few remarks on those keywords:


Inheritance tips

As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see: 

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

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

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.


When to use add, when to use replace, when can I just leave it to the parent theme?

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.


You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.


If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).


To make it clear, let's take the Fruity example. Here its css file section: 


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


If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.


So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.


So in general: if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy. if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration. if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result) if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.


Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.


You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions Template:RegisterTemplateCssFile('my style.css') and Template:RegisterTemplateScript('my script.js'). If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the Template:Image('my picture.jpg') function

removeキーワード

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files: 

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

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for 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',
        ),


Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css: 

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

Files you should not remove:

jquery-3.1.1.min.js : needed

jquery-migrate-3.0.0.min.js : needed

survey.js : needed

moment-with-locales.min.js : needed for date question type (and some other i think)

em_javascript.js : needed for all Expression Manager javascript

オプションセクション

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

追加情報

注記

注意: テーマのXMLファイルを編集する場合は、そのテーマが反映されるようにテーマをアンインストールしてから再びインストールする必要があります。

注意: これを避けるために、DBではなく強制的にXMLを使用することができます。config.phpでデバッグモードをオンにし、コメントアウトします。

'force_xmlsettings_for_survey_rendering' => true, // DBではなく強制的にXMLファイルを使用したい場合はコメントを外します（簡単なテーマ開発のため）。

注意: すべてがXMLから読み込まれるようになります（オプションなど）


注意: テーマエディターを使用せずにCSS/JSファイルを手動で編集し、かつデバッグモードがオフの場合は、アセットを強制的にフラッシュできるようになりました。 "全体設定"、"全般"タブで、"アセットキャッシュをクリアする"ボタンをクリックします。

NOTE: if you remove the section

Retrieved from "http://manual.limesurvey.org/index.php?title=New_Template_System_in_LS3.x/ja&oldid=142460"