テンプレートエンジンを使う ========================== > Note|注意: この節はまだ執筆中です。 デフォルトでは、Yii は PHP をテンプレート言語として使いますが、[Twig](http://twig.sensiolabs.org/) や [Smarty](http://www.smarty.net/) などの他のレンダリングエンジンをサポートするように Yii を構成することが出来ます。 `view` コンポーネントがビューのレンダリングに責任を持っています。 このコンポーネントのビヘイビアを構成することによって、カスタムテンプレートエンジンを追加することが出来ます。 ```php [ 'components' => [ 'view' => [ 'class' => 'yii\web\View', 'renderers' => [ 'tpl' => [ 'class' => 'yii\smarty\ViewRenderer', //'cachePath' => '@runtime/Smarty/cache', ], 'twig' => [ 'class' => 'yii\twig\ViewRenderer', 'cachePath' => '@runtime/Twig/cache', // twig のオプションの配列 'options' => [ 'auto_reload' => true, ], 'globals' => ['html' => '\yii\helpers\Html'], 'uses' => ['yii\bootstrap'], ], // ... ], ], ], ] ``` 上記のコードにおいては、Smarty と Twig の両者がビューファイルによって使用可能なものとして構成されています。 しかし、これらのエクステンションをプロジェクトで使うためには、`composer.json` ファイルも修正して、これらのエクステンションを含める必要があります。 ``` "yiisoft/yii2-smarty": "*", "yiisoft/yii2-twig": "*", ``` 上のコードを `composer.json` の `require` セクションに追加します。 変更をファイルに保存した後、コマンドラインで `composer update --prefer-dist` を実行することによってエクステンションをインストールすることが出来ます。 Twig ---- Twig を使うためには、`.twig` という拡張子を持つファイルにテンプレートを作成しなければなりません (別のファイル拡張子を使っても構いませんが、それに対応してコンポーネントの構成を変更しなければなりません)。 通常のビューファイルと違って、Twig を使うときは、コントローラで `$this->render()` を呼ぶときに拡張子を含めなければなりません。 ```php return $this->render('renderer.twig', ['username' => 'Alex']); ``` ### テンプレートの構文 Twig の基礎を学ぶための最善のリソースは、[twig.sensiolabs.org](http://twig.sensiolabs.org/documentation) にある公式ドキュメントです。 それに追加して、下記に説明する Yii 固有の拡張構文があります。 #### メソッドとファンクションの呼び出し 結果が必要な場合は、次の構文を使ってメソッドや関数を呼び出すことが出来ます。 ``` {% set result = my_function({'a' : 'b'}) %} {% set result = myObject.my_function({'a' : 'b'}) %} ``` 結果を変数に代入する代りに echo したい場合は、こうします。 ``` {{ my_function({'a' : 'b'}) }} {{ myObject.my_function({'a' : 'b'}) }} ``` 結果を必要としない場合は、`void` ラッパーを使うべきです。 ``` {{ void(my_function({'a' : 'b'})) }} {{ void(myObject.my_function({'a' : 'b'})) }} ``` #### オブジェクトのプロパティを設定する `set` と呼ばれる特別な関数を使って、オブジェクトのプロパティを設定することが出来ます。 例えば、テンプレート中の下記のコードはページタイトルを変更します。 ``` {{ set(this, 'title', 'New title') }} ``` #### 名前空間とクラスをインポートする 追加のクラスと名前空間をテンプレートの中でインポートすることが出来ます。 ``` 名前空間のインポート: {{ use('/app/widgets') }} クラスのインポート: {{ use('/yii/widgets/ActiveForm') }} エイリアス化してクラスをインポート: {{ use({'alias' : '/app/widgets/MyWidget'}) }} ``` #### 他のテンプレートを参照する `include` と `extends` 文によるテンプレートの参照には二つの方法があります。 ``` {% include "comment.twig" %} {% extends "post.twig" %} {% include "@app/views/snippets/avatar.twig" %} {% extends "@app/views/layouts/2columns.twig" %} ``` 最初の場合では、現在のテンプレートのパスからの相対的なパスでビューを探します。 `comment.twig` と `post.twig` は、現在レンダリングされているテンプレートと同じディレクトリで探されます。 第二の場合では、パスエイリアスを使います。 `@app` のような全ての Yii のエイリアスがデフォルトで利用できます。 #### ウィジェット このエクステンションは、ウィジェットを簡単に使えるように、ウィジェットの構文を関数呼び出しに変換します。 ``` {{ use('yii/bootstrap') }} {{ nav_bar_begin({ 'brandLabel': 'My Company', }) }} {{ nav_widget({ 'options': { 'class': 'navbar-nav navbar-right', }, 'items': [{ 'label': 'Home', 'url': '/site/index', }] }) }} {{ nav_bar_end() }} ``` 上記のテンプレートでは、`nav_bar_begin`、`nav_bar_end` また `nav_widget` は、二つの部分から構成されます。 最初の部分は、小文字とアンダースコアに変換されたウィジェットの名前です。 `NavBar` は `nav_bar`、`Nav` は `nav` に変換されます。 第二の部分の `_begin`、`_end` および `_widget` は、ウィジェットのメソッド `::begin()`、`::end()` および `::widget()` と同じものです。 もっと汎用的な `Widget::end()` を実行する `widget_end()` も使うことが出来ます。 #### アセット アセットは次の方法で登録することが出来ます。 ``` {{ use('yii/web/JqueryAsset') }} {{ register_jquery_asset() }} ``` 上記のコードで、`register` は、アセットを扱うことを指定し、`jquery_asset` は、既に `use` でインポート済みの `JqueryAsset` クラスに翻訳されます。 #### フォーム フォームは次のようにして構築することが出来ます。 ``` {{ use('yii/widgets/ActiveForm') }} {% set form = active_form_begin({ 'id' : 'login-form', 'options' : {'class' : 'form-horizontal'}, }) %} {{ form.field(model, 'username') | raw }} {{ form.field(model, 'password').passwordInput() | raw }}
{{ active_form_end() }} ``` #### URL URL を構築するのに使える二つの関数があります。 ```php {{ post.title }} {{ post.title }} ``` `path` は相対的な URL を生成し、`url` は絶対的な URL を生成します。 内部的には、両者とも、[[\yii\helpers\Url]] を使っています。 #### 追加の変数 Twig のテンプレート内では、次の変数が常に定義されています。 - `app` - `\Yii::$app` オブジェクト - `this` - 現在の `View` オブジェクト ### 追加の構成 Yii Twig エクステンションは、あなた自身の構文を定義して、通常のヘルパクラスをテンプレートに導入することを可能にしています。 構成のオプションを見ていきましょう。 #### グローバル アプリケーション構成の `globals` 変数によって、グローバルなヘルパや変数を追加することが出来ます。 Yii のヘルパとあなた自身の変数を定義することが出来ます。 ```php 'globals' => [ 'html' => '\yii\helpers\Html', 'name' => 'Carsten', 'GridView' => '\yii\grid\GridView', ], ``` いったん構成してしまえば、テンプレートの中で以下のようにグローバルを使用することが出来ます。 ``` Hello, {{name}}! {{ html.a('ログインしてください', 'site/login') | raw }}. {{ GridView.widget({'dataProvider' : provider}) | raw }} ``` #### 関数 追加の関数を次のようにして定義することが出来ます。 ```php 'functions' => [ 'rot13' => 'str_rot13', 'truncate' => '\yii\helpers\StringHelper::truncate', ], ``` テンプレートでは、次のようにして使うことが出来ます。 ``` `{{ rot13('test') }}` `{{ truncate(post.text, 100) }}` ``` #### フィルタ 追加のフィルタをアプリケーション構成の `filters` オプションによって追加することが出来ます。 ```php 'filters' => [ 'jsonEncode' => '\yii\helpers\Json::encode', ], ``` テンプレートの中では、次の構文を使ってフィルタを適用することが出来ます。 ``` {{ model|jsonEncode }} ``` Smarty ------ Smarty を使うためには、`.tpl` という拡張子を持つファイルにテンプレートを作成しなければなりません (別のファイル拡張子を使っても構いませんが、それに対応してコンポーネントの構成を変更しなければなりません)。 通常のビューファイルと違って、Smarty を使うときは、コントローラで `$this->render()` を呼ぶときに拡張子を含めなければなりません。 ```php return $this->render('renderer.tpl', ['username' => 'Alex']); ``` ### テンプレートの構文 Smarty のテンプレートの構文を学ぶための最善のリソースは、[www.smarty.net](http://www.smarty.net/docs/ja/) にある公式ドキュメントです。 それに追加して、下記に説明する Yii 固有の拡張構文があります。 #### オブジェクトのプロパティを設定する `set` と呼ばれる特別な関数を使って、ビューとコントローラの一般的なプロパティを設定することが出来ます。 現在サポートされているプロパティは、`title`、`theme` および `layout` です。 ``` {set title="My Page"} {set theme="frontend"} {set layout="main.tpl"} ``` タイトルについては、専用のブロックもあります。 ``` {title}My Page{/title} ``` #### メタタグを設定する メタタグは次のようにして設定することが出来ます。 ``` {meta keywords="Yii,PHP,Smarty,framework"} ``` `description` のためには専用のブロックもあります。 ``` {description}Smarty エクステンションについて説明するページです{/description} ``` #### オブジェクトのメソッドを呼び出す 場合によっては、オブジェクトのメソッドを呼び出す必要があるでしょう。 #### スタティックなクラスをインポートし、ウィジェットを関数およびブロックとして使用する 追加のスタティックなクラスをテンプレートの中でインポートすることが出来ます。 ``` {use class="yii\helpers\Html"} {Html::mailto('eugenia@example.com')} ``` 必要であれば、カスタムエイリアスを設定することも出来ます。 ``` {use class="yii\helpers\Html" as="Markup"} {Markup::mailto('eugenia@example.com')} ``` このエクステンションは、ウィジェットを簡単に使えるように、ウィジェットの構文を関数呼び出しまたはブロックに変換します。 通常のウィジェットについては、次のように関数を使うことが出来ます。 ``` {use class='@yii\grid\GridView' type='function'} {GridView dataProvider=$provider} ``` ActiveForm のように `begin` および `end` メソッドを持つウィジェットについては、ブロックを使うほうが良いでしょう。 ``` {use class='yii\widgets\ActiveForm' type='block'} {ActiveForm assign='form' id='login-form' action='/form-handler' options=['class' => 'form-horizontal']} {$form->field($model, 'firstName')}
{/ActiveForm} ``` 特定のウィジェットを多用する場合は、それをアプリケーション構成の中で宣言して、テンプレートから `{use class` の呼び出しを削除するのが良いアイデアです。 ```php 'components' => [ 'view' => [ // ... 'renderers' => [ 'tpl' => [ 'class' => 'yii\smarty\ViewRenderer', 'widgets' => [ 'blocks' => [ 'ActiveForm' => '\yii\widgets\ActiveForm', ], ], ], ], ], ], ``` #### 他のテンプレートを参照する `include` と `extends` 文によるテンプレートの参照には、主として二つの方法があります。 ``` {include 'comment.tpl'} {extends 'post.tpl'} {include '@app/views/snippets/avatar.tpl'} {extends '@app/views/layouts/2columns.tpl'} ``` 最初の場合では、現在のテンプレートのパスからの相対的なパスでビューを探します。 `comment.tpl` と `post.tpl` は、現在レンダリングされているテンプレートと同じディレクトリで探されます。 第二の場合では、パスエイリアスを使います。 `@app` のような全ての Yii のエイリアスがデフォルトで利用できます。 #### CSS、JavaScript およびアセットバンドル JavaScript と CSS のファイルを登録するためには、次の構文を使うことが出来ます。 ``` {registerJsFile url='http://maps.google.com/maps/api/js?sensor=false' position='POS_END'} {registerCssFile url='@assets/css/normalizer.css'} ``` JavaScript と CSS をテンプレートに直接書きたい場合は、便利なブロックがあります。 ``` {registerJs key='show' position='POS_LOAD'} $("span.show").replaceWith('
'); {/registerJs} {registerCss} div.header { background-color: #3366bd; color: white; } {/registerCss} ``` アセットバンドルは次のようにして登録することが出来ます。 ``` {use class="yii\web\JqueryAsset"} {JqueryAsset::register($this)|void} ``` ここではメソッド呼び出しの結果が必要ないので `void` 修飾子を使っています。 #### URL URL を構築するのに使える二つの関数があります。 ```php {$post.title} {$post.title} ``` `path` は相対的な URL を生成し、`url` は絶対的な URL を生成します。 内部的には、両者とも、[[\yii\helpers\Url]] を使っています。 #### 追加の変数 Smarty のテンプレート内では、次の変数が常に定義されています。 - `app` - `\Yii::$app` オブジェクト - `this` - 現在の `View` オブジェクト #### 構成情報のパラメータにアクセスする アプリケーションにおいて `Yii::$app->params->something` によって取得できるパラメータは、次のようにして使用することが出来ます。 ``` `{#something#}` ```