v0.21

ビュー

はじめに

dframeworkにはカスタムビューエンジンが搭載されています。テンプレートを生のjavascript関数にコンパイルするstring to function評価モデルを採用しています。これにより一般的なタスクに便利なディレクティブを活用しながらテンプレート内に標準的なjavascriptを直接記述できます。

ビューの作成

ビューはviewsディレクトリに保存され.dファイル拡張子を使用する必要があります。ビューはドット記法を使用して参照されます。views/app/home/index.dにあるファイルはapp.home.indexとして参照されます。

1<!-- views/greetings/hello.d -->
2<html>
3 <body>
4 <h1>hello, {{ name }}!</h1>
5 </body>
6</html>

コントローラからはrender()ヘルパーを使用してビューを返します。

1export default class GreetingController {
2 async hello() {
3 return render('greetings.hello', { name: 'world' });
4 }
5}
IMPORTANT

`process`、`require`、`global`などの危険なjavascriptグローバル変数はビューデータに渡すことができません。エンジンはビューコンテキストを厳格に検証し改ざんが検出された場合はエラーをスローします。

データの表示

ビューに渡されたデータを表示するには変数を二重中括弧で囲みます。ビューエンジンはxss攻撃を防ぐために出力を自動的にエスケープします。

1hello, {{ user.name }}.
2the current timestamp is {{ Date.now() }}.

エスケープされていないhtmlをレンダリングする必要がある場合は{!! !!}構文を使用します。

1{!! user.bio_html !!}

@jsonディレクティブを使用してオブジェクトをjson文字列に変換できます。@jsonは非同期式のawaitもサポートしています。

1<script>
2 const userState = @json(user);
3 const remoteData = @json(await fetchStats());
4</script>

制御構造

ビューエンジンは一般的なjavascript制御構造のショートカットを提供します。

ifステートメント

1@if (user.isAdmin)
2 <button>admin panel</button>
3@elseif (user.isModerator)
4 <button>mod panel</button>
5@else
6 <span>standard user</span>
7@endif

ループ

1@foreach (users as user)
2 <li>{{ user.name }}</li>
3@endforeach
4
5@for (let i = 0; i < 10; i++)
6 <span>{{ i }}</span>
7@endfor

@foreachおよび@forelseループの内部ではループ変数$index(0始まりのインデックス)、$first(初回反復時にブール値true)、$last(最終反復時にブール値true)が自動的に利用可能です。

@forelseディレクティブは配列が空の場合のフォールバックを備えた配列ループの便利な記述方法です。

1@forelse (tracks as track)
2 <li>{{ track.title }}</li>
3@empty
4 <li>no tracks found.</li>
5@endforelse

レイアウトとインクルード

マスターレイアウトを定義し子ビューからそれを拡張できます。コンテンツを注入する場所に@yieldを指定し子ビューでそのコンテンツを提供するために@sectionを使用します。

1<!-- views/layouts/app.d -->
2<html>
3 <head>
4 <title>app</title>
5 </head>
6 <body>
7 <nav></nav>
8 <main>
9 @yield('content')
10 </main>
11 </body>
12</html>
1<!-- views/home.d -->
2@extends('layouts.app')
3
4@section('content')
5 <h1>welcome home</h1>
6@endsection

ネストされたセクションは最大再帰深度まで解決されます(デフォルトは30、設定のview.maxYieldDepthで設定可能)。

@includeディレクティブを使用してパーシャルをインクルードできます。ローカル開発環境では存在しないパーシャルを参照するとタイポを迅速に発見できるようにビュー候補を含む実用的なDiagnosticErrorがスローされます。本番環境では存在しないパーシャルは空の文字列として解決されます。

1@include('components.header')

javascriptの実行

ビューエンジンはjavascript関数に直接コンパイルされるためテンプレート内で任意のサーバー側コードを直接実行できます。1行のjavascriptには@js()ディレクティブを使用し複数行には@jsから@endjsまでのブロックを使用します。

1@js(const maxLimit = 50;)
2
3@js
4 let sortedUsers = users.sort((a, b) => b.score - a.score);
5 sortedUsers = sortedUsers.slice(0, maxLimit);
6@endjs
7
8@foreach (sortedUsers as user)
9 <li>{{ user.name }}</li>
10@endforeach

ローカライゼーション

@t()ディレクティブを使用して文字列を翻訳できます。フレームワークはリクエストコンテキストから現在のロケールを自動的に解決し対応する翻訳文字列を取得します。@t()は非同期のawait t()呼び出しにコンパイルされるためコンパイル後のビューは非同期として扱われます。

1<h1>@t('home.welcome_message')</h1>
2<p>@t('home.unread_count', { count: 5 })</p>

日本語ふりがな(ルビ)のサポート

dframeworkは@ruby()ディレクティブを使用した日本語のふりがな(ルビ)アノテーションの組み込みサポートを提供します。2つの引数(漢字と読み)を渡すか漢字[かんじ]表記の単一文字列を渡すことができます。awaitを使用した非同期式もサポートされています。

1<h1>@ruby("漢字", "かんじ")</h1>
2<p>@ruby("日本[にほん]語")</p>
3<p>@ruby(await fetchWord())</p>

ページネーション

ビューエンジンはモデルの.paginate()メソッドによって返されるフレームワークのPaginatorクラスと統合されています。ペジネーターは@foreachループ内で直接反復可能であり自動またはカスタムのhtmlページネーションコントロールを提供します。

1@foreach (users as user)
2 <div>{{ user.name }}</div>
3@endforeach
4
5<!-- renders standard pagination controls (standalone directive) -->
6@pagination(users)

あるいはエスケープなしの出力を使用してリンクを直接レンダリングすることもできます:

1{!! users.links() !!}

検索語やフィルターキーなどの既存のurlクエリパラメータは生成されたすべてのリンクで自動的に保持されます。

デフォルトではリンクはページ全体のナビゲーション用の標準アンカーとしてレンダリングされます。spa遷移を有効にするには第2引数としてtrueを渡します:

1<!-- enables spa navigation -->
2@pagination(users, true)

ページ全体の遷移ではなく特定のコンテナを更新するには第3引数としてcssセレクタを渡します:

1<!-- updates the #user-list container via spa -->
2@pagination(users, true, '#user-list')

カスタムページネーションhtml

@paginationブロック内にコンテンツを指定した場合エンジンはデフォルトのhtml生成をスキップしてカスタムマークアップをレンダリングします。

ブロック内ではカスタムコントロールを構築するために使用できる7つの変数がエンジンによって自動的に公開されます:

1@pagination(users)
2 <div class="custom-pagination">
3 <p>page {{ current }} of {{ last }} ({{ total }} users)</p>
4
5 @if (prev)
6 <a href="{{ prev }}" class="btn">previous</a>
7 @endif
8
9 @if (next)
10 <a href="{{ next }}" class="btn">next</a>
11 @endif
12 </div>
13@endpagination

フレームワークは2ページ以上存在する場合(last > 1)にのみブロックを評価します。1ページのみの場合は@paginationブロック全体がスキップされます。

自動フォーム処理

更新系メソッド(POST、PUTなど)を指定してhtmlの<form>を作成するとビューエンジンは隠しフィールド_csrfと現在のcsrfトークン値を自動的に注入します。フォーム内で手動でcsrfトークンを出力する必要はありません。

さらにエンジンはドキュメントの<head>内に<meta name="csrf-token">タグを注入するためajaxリクエストでトークンを取得できます。

ビューのコンパイル

local環境ではフレームワークはカスタムjitコンパイラを使用し元の.dファイルに直接マッピングされた詳細なエラートレースを提供します。

production環境ではビューは事前に高度に最適化された.dc(.d compiled)ファイルへaot(ahead of time)コンパイルされます。フレームワークは起動時にこれらの.dcファイルの暗号学的完全性を検証しテンプレートが改ざんされていないことを保証します。

コンパイル済みビューはapp.maxCompiledCacheSizeエントリ(デフォルトは500)を上限とするLRUキャッシュに保持されます。キャッシュされたビューをレンダリングすると最も最近使用された状態に更新されるため入れ替えが発生しても頻繁に使用されるビューは常駐し続けます。詳細は設定 > パフォーマンスチューニングキーを参照してください。