テンプレート

テンプレートの構文

変数

以下ようにして変数を表示することができます:

Your payoff is {{ player.payoff }}.

テンプレートでは、以下の変数が使用できます:

  • player: 現在ページを見ているプレイヤー
  • group: 現在のプレイヤーが所属しているグループ
  • subsession: 現在のプレイヤーが所属しているサブセッション
  • participant: 現在のプレイヤーが所属している参加者
  • session: 現在のセッション
  • C
  • vars_for_template() で渡した変数

条件文 ("if")

注釈

oTree 3.x では、テンプレートに {{ }} と {% %} の 2 種類のタグを使用していました。しかし、 oTree 5 からは、 {% %} を使用する必要はなく、 {{ }} をどこでも使用することができます。以前の形式でも動作します。

'else' を付けた例:

Complex example:

ループ ("for")

{{ for item in some_list }}
    {{ item }}
{{ endfor }}

辞書型内のアイテムへのアクセス

Python のコードでは my_dict['foo'] でアクセスしますが、テンプレートでは {{ my_dict.foo }} でアクセスします。

コメント

{# this is a comment #}

{#
    this is a
    multiline comment
#}

できないこと

テンプレート言語は値を表示するだけのものです。演算 (+, *, /, -) や数値、リスト、文字列などの変更はできません。そのようなことをしたい場合には、 vars_for_template() を使用してください。

テンプレートの仕組み: 例

oTree のテンプレートは 2 つの言語が混在しています:

  • HTML (<this> や </this> のような山括弧を使います)
  • テンプレートタグ（{{ this }} のような中括弧を使用します)

この例では、テンプレートが次のようになっているとします:

<p>Your payoff this round was {{ player.payoff }}.</p>

{{ if subsession.round_number > 1 }}
    <p>
        Your payoff in the previous round was {{ last_round_payoff }}.
    </p>
{{ endif }}

{{ next_button }}

ステップ 1: oTree はテンプレートタグをスキャンし、 HTML を生成します ("サーバサイド")

oTree は、変数の現在の値を使って、上記のテンプレートタグを次のようなプレーンな HTML に変換します:

<p>Your payoff this round was $10.</p>

    <p>
        Your payoff in the previous round was $5.
    </p>

<button class="otree-btn-next btn btn-primary">Next</button>

ステップ 2: ブラウザが HTML タグをスキャンし、ウェブページを作成する ("クライアントサイド")

oTree サーバは、この HTML をユーザのコンピュータに送信し、ユーザのウェブブラウザがコードを読み取って、フォーマットされたウェブページとして表示します:

_images/template-example.png

そのため、ブラウザはテンプレートタグを直接読み取ることはありません。

キーポイント

もし、あるページが思い通りに表示されない場合は、上記のどのステップで間違っていたのか切り分けることができます。ブラウザで右クリックして "ページのソースを表示" を選択してください。 (注: 画面分割モードでは "ページのソースを表示" が機能しない場合があります。)

すると、生成された HTML (JavaScript や CSS も含む) を見ることができます。

  • HTML コードが期待通りに表示されない場合は、サーバ側で何か問題が発生しています。 vars_for_template やテンプレートタグに間違いがないか確認してください。
  • HTML コードの生成にエラーがなかった場合は、 HTML (または JavaScript) の構文に問題があると考えられます。問題のある部分の HTML をテンプレートタグなしでテンプレートに貼り直し、正しい出力が得られるまで編集してみてください。その後、テンプレートタグを元に戻して、再び動的にしてください。

画像 (静的ファイル)

画像、動画、サードパーティの JS/CSS ライブラリ、その他の静的ファイルをプロジェクトに使用する最も簡単な方法は、 Dropbox, Imgur, YouTube などのオンラインサービスを利用することです。

そして、その URL を <img> や <video> タグでテンプレートに記述します:

<img src="https://i.imgur.com/gM5yeyS.jpg" width="500px" />

また、プロジェクトに直接画像を保存することもできます。 (ただし、ファイルサイズが大きいとパフォーマンスに影響するので注意が必要です)。 oTree Studio には、画像アップロードツールがあります。 (テキストエディタを使用している場合は、 こちら を参照してください。) 画像を保存したら、次のようにすることで表示することができます:

<img src="{{ static 'folder_name/puppy.jpg' }}"/>

動的な画像表示

文脈に応じて異なる画像を表示する必要がある場合 (ラウンド毎に異なる画像を表示するなど)、 vars_for_template で使用する画像のパスを構築し、テンプレートに渡すことができます:

@staticmethod
def vars_for_template(player):
    return dict(
        image_path='my_app/{}.png'.format(player.round_number)
    )

そして、テンプレートの中では次のようにします:

<img src="{{ static image_path }}"/>

インクルード可能なテンプレート

多くのテンプレートに同じ内容をコピーペーストする場合は、インクルード可能なテンプレートを作成し、 {{ include_sibling }} で再利用するのがよいでしょう。

例えば、ゲームの説明がすべてのページで繰り返し表示される必要がある場合、 instructions.html というテンプレートを作成し、そこに説明を書く方法があります:

<div class="card bg-light">
    <div class="card-body">

    <h3>
        Instructions
    </h3>
    <p>
        These are the instructions for the game....
    </p>
    </div>
</div>

Then use {{ include_sibling 'instructions.html' }} to insert it anywhere you want.

注釈

{{ include_sibling }} is a new alternative to {{ include }}. The advantage is that you can omit the name of the app: {{ include_sibling 'xyz.html' }} instead of {{ include 'my_app/xyz.html' }}. However, if the includable template is in a different folder, you must use {{ include }}.

JavaScript, CSS

JavaScript/CSS コードの設置場所

JavaScript や CSS は <script></script> や <style></style> を使うことで、テンプレート内のどこにでも置くことができます。

たくさんのスクリプトやスタイルシートがある場合は、 content ブロックの外にある scripts や styles ブロックに入れることができます。これは必須ではありませんが、コードを整理し、正しい順序で読み込まれるようにすることができます (CSS、ページコンテンツ、JavaScriptの順)。

テーマのカスタマイズ

oTree 要素の見た目をカスタマイズしたい場合、以下のリストにある CSS セレクタをカスタマイズします:

要素 CSS/jQuery セレクタ
ページ本文 .otree-body
ページタイトル .otree-title
待機ページ (ダイアログ全体) .otree-wait-page
待機ページのダイアログタイトル .otree-wait-page__title (note: __, not _)
待機ページのダイアログ本文 .otree-wait-page__body
タイマー .otree-timer
次へボタン .otree-btn-next
フォームエラーの警告 .otree-form-errors

例えば、ページの幅を変更するには、ベースとなるテンプレートに以下のような CSS を記述します:

<style>
    .otree-body {
        max-width:800px
    }
</style>

より詳細な情報を得るためには、ブラウザで修正したい要素を右クリックし、 "検証" を選択します。すると、さまざまな要素が表示され、そのスタイルを変更することができます:

_images/dom-inspector.png

可能な限り、上記の公式セレクタのいずれかを使用してください。 _otree で始まるセレクタは使わないでください。また、 btn-primary や card のような Bootstrap のクラスは選択しないでください。

Python から JavaScript へのデータの受け渡し (js_vars)

テンプレート内の JavaScript コードにデータを渡すには、Pageに js_vars 関数を定義します:

@staticmethod
def js_vars(player):
    return dict(
        payoff=player.payoff,
    )

そして、テンプレートの中で、これらの変数を参照することができます:

<script>
    let x = js_vars.payoff;
    // etc...
</script>

Bootstrap

oTreeには、ウェブサイトのユーザーインターフェースをカスタマイズするための人気ライブラリである Bootstrap が搭載されています。

カスタムスタイル や、テーブル、アラート、プログレスバー、ラベルなどの 特定のコンポーネント を必要な場合に使用することができます。 ポップオーバー, モーダル, 折り畳み可能なテキスト などの要素を使って、動的なページを作ることもできます。

Bootstrap を使用するには、HTML の要素に class= 属性を追加します。

例えば、以下の HTML は "成功" のアラートを作成します:

<div class="alert alert-success">Great job!</div>

モバイルデバイス

Bootstrap は、スマートフォンやタブレットで見たときにモバイル対応のバージョンを表示しようとします。

Best way to test on mobile is to use Heroku. otree zipserver doesn't accept a 'port' argument. Also, devserver/zipserver seem to have issues with shutdown/reloading and freeing up the port.

グラフ

アプリにグラフを追加するには、任意の HTML/JavaScript ライブラリを使用できます。円グラフ、折れ線グラフ、棒グラフ、時系列グラフなどを描画するには、 HighCharts が適しています。

まず、HighCharts の JavaScript をインクルードします:

<script src="https://code.highcharts.com/highcharts.js"></script>

HighCharts の デモサイト にアクセスし、作りたい種類のグラフを探します。そして、 "Edit in JSFiddle" をクリックして、ソースコードのデータを書き換えて編集します。

そして、その JS と HTML をテンプレートにコピーペーストして、ページを読み込みます。グラフが表示されない場合は、JSコードがチャートを挿入しようとする <div> がHTMLに含まれていないことが原因かもしれません。

グラフが正しく読み込まれたら、 series や categories などのソースコードに書き込まれたデータを、動的に生成された変数に置き換えることができます。

例えば、以下のコードがあるとします:

series: [{
    name: 'Tokyo',
    data: [7.0, 6.9, 9.5, 14.5, 18.2, 21.5, 25.2, 26.5, 23.3, 18.3, 13.9, 9.6]
}, {
    name: 'New York',
    data: [-0.2, 0.8, 5.7, 11.3, 17.0, 22.0, 24.8, 24.1, 20.1, 14.1, 8.6, 2.5]
}]

これを以下のように変更できます:

series: js_vars.highcharts_series

ここで highcharts_series は js_vars で定義した変数です。

グラフが読み込まれない場合は、ブラウザの "ページのソースを表示" をクリックして、動的に生成したデータに何か問題がないか確認してください。

その他

to2, to1, or to0 フィルタを使って、数字を丸めることができます。例えば {{ 0.1234|to2}} とすれば 0.12 が表示されます。