ビュー
"foa/html-view-bundle": "2.*"
を composer.json
に追加し composer update
を実行してインストールしましょう。
出力をエスケープする
テンプレートで値を出力する際は、セキュリティのため 常に 適切なエスケープを行うようにしましょう。 HTMLテンプレートなら、HTMLエスケーピング、 CSSテンプレートならCSSエスケーピング、XMLテンプレートならXMLエスケーピング、 PDFテンプレートならPDFエスケーピング、 RTFテンプレートならRTFエスケーピング…という事です。
ビューテンプレートの登録
Aura\View\View オブジェクトを持っていると仮定しましょう、ビューレジストリへテンプレートを登録してみます。 これは一般的にPHPファイルへのパスを設定しますが、クロージャを使う事も出来ます。 一般的な例を下記に示します。:
browse.php
は下記のようなファイルです。:
テンプレートで、return
ではなく、echo
を使用している事に注目してください。
テンプレートのロジックは、 View オブジェクトのスコープ内で実行されます,
これはテンプレート内の $this
が View オブジェクトを参照する事を意味します。
クロージャベースのテンプレートも同じです。
データのセット
大抵の場合、テンプレートにはダイナミックなデータを使用したいと思うでしょう。データを view へセットするには、setdata()
メソッドを使用します。 配列でもオブジェクトでも大丈夫です。そしてこれらのデータは view オブジェクトのプロパティとして利用できます。
テンプレートロジック内の $this
は View オブジェクトを参照する事を覚えていますか?
View へ設定されたデータは $this
のプロパティとしてアクセスできます。
setData()
メソッドは_View_ オブジェクトの全てのデータを上書きします。一方で、addData()
メソッドは View オブジェクトへ設定されているデータとマージします。
ビューの呼び出し
さあ、テンプレートを登録していくつかデータを View にセットしてきました、View に描画するテンプレートを設定し、invoke(呼び出し)してみましょう!
$output
は下記のような出力になります。
サブテンプレートを使う (“パーシャル”)
テンプレートを部分的に分割したいというような時があります。こういった部分的な “パーシャル” テンプレートは、メインテンプレート内で render()
メソッドを使用して描画を行います。
まずはじめに、ビューレジストリへサブテンプレートを登録します。(レイアウトのために使用する場合はレイアウトレジストリになります)
それから、メインテンプレート内で render()
を実行します。サブテンプレートには好きなネームスキームを使用できます。 いくつかのシステムでは、アンダースコアをプレフィックスに使用する習慣があります。下記の例もそのようにしてあります。
次に、パーシャルテンプレートで利用するために、変数群の配列を渡します。($this
変数は常に利用できます)
例として, browse.php
テンプレートを分割してアイテムを表示する部分をサブテンプレートとして切り出してみましょう。
browse.php
からアイテム表示を行うコードを _item.php
へ移行します。:
それから、 browse.php
をサブテンプレートを使うように変更します。:
出力は前例でビューを呼び出した時の物と同じになります。
または、 include
あるいは require
を使って
現在のテンプレートスコープで直接PHPファイルを実行する事も出来ます。
セクションを使う
セクションはサブテンプレートと似ていますが、セクションについては後々の描画のために出力のキャプチャーを行う点が異なります。 一般的に、ビューテンプレートに使用され、レイアウトテンプレートのために出力をキャプチャーします。
例えば、ビューテンプレートの出力を指定のセクションにキャプチャーします …
… それからレイアウトテンプレートで出力します。
加えて、setSection()
メソッドはキャプチャーの代わりに、直接下記のように設定することも出来ます。
2ステップビューの描画
レイアウトの中でメインコンテンツをラップするために、まずレイアウトテンプレートを
View に登録して、setLayout()
メソッドを使いセットします。(もしレイアウトが設定されていなければ、実行されません。)
ビューレジストリへ browse
テンプレートを登録していると仮定します。default
レイアウトテンプレートをレイアウトレジストリへ登録してみましょう。:
default.php
レイアウトテンプレートは下記のようなファイルです。:
それから View オブジェクトに、ビューとレイアウトを設定して呼び出します。
内側のビューテンプレートからの出力は保持され View オブジェクトの getContent()
メソッドから利用できるようになります。レイアウトテンプレートはそれから getContent()
を呼び出しレイアウトテンプレートに、ビューの結果を出力します。
ビューテンプレートから、setLayout()
を呼ぶ事も出来ます。
ビューロジックの一部としてレイアウトを選択する事が可能です。
ビューテンプレートとレイアウトテンプレートは同じ View オブジェクトの中で実行されます。つまり:
-
全てのデータは、ビューとレイアウト間で共有されます。ビューにセットされたデータや、ビューによって変更されたデータはレイアウトからもそのまま使えます。
-
全てのヘルパーは、ビューとレイアウト間で共有されます。レイアウトが実行されるまえにビューからデータやヘルパーを変更できます。
-
全てのセクションボディは、ビューとレイアウト間で共有されます。よって、ビューテンプレートからキャプチャーされたセクションがレイアウトテンプレートからも利用できます。
テンプレートとしてのクロージャ
ビュー、及びレイアウトレジストリにはクロージャもテンプレートとして登録する事が出来ます。
下記は、 browse.php
と _item.php
テンプレートでクロージャを利用した例です。
クロージャベースのテンプレートを登録する時は、出力時に return
ではなく echo
を使うようにしましょう。 クロージャは View オブジェクトに返るので、
ファイルベースのテンプレートと同様にクロージャの $this
も View を参照するようになります。
クロージャベースでサブテンプレートを利用する場合は少し追加の作業が必要になります。ファイルベースのテンプレートでは、セットされたデータを含む配列を自動的にローカルスコープに展開してくれますが、クロージャベースのテンプレートでは以下の作業が必要になります:
-
注入された変数を受け取るパラメーターを関数に定義しましょう。(_item
テンプレート内の $vars
パラメーターです)
-
extract()
を使って注入された変数を展開します。または、注入された変数をそのまま直接使う事も出来ます。
上記を除き、クロージャベースのテンプレートはファイルベースのテンプレートと同様に機能します。
Aura.Htmlでのビルトインヘルパー
エスケーパー
出力のエスケープは、セキュリティの観点から 絶対に必要不可欠 です。このパッケージの、escape()
ヘルパーには4つのメソッドがあります:
$this->escape()->html('foo')
HTMLのエスケープに使用します。
$this->escape()->attr('foo')
HTML属性のエスケープに使用します。
$this->escape()->css('foo')
CSSのエスケープに使用します。
$this->escape()->js('foo')
JavaScriptのエスケープに使用します。
下記にいくつか escape()
ヘルパーの使用例を示します:
不幸なことに、エスケープの処理はくどく、テンプレートのコードは酷く散らかったように見えます。これを和らげるために、2つの方法があります。
1つ目の方法は、escape()
ヘルパーを変数にセットして、呼び出すようにする事です。下記は例です。
2つ目の方法は、 escape()
ヘルパーに使用される Escaper クラスに実装されている4つのstaticメソッドを使う事です。:h()
, a()
, c()
, j()
順番に、HTMLのエスケープ、HTML属性のエスケープ、CSSのエスケープ、JavaScriptのエスケープを行います。
注意 : Auraでは、基本的にstaticメソッドの利用を避けています。しかし、この場合ではテンプレートの可読性のためのトレードオフです。
PHPベースのテンプレートで、static Escaper メソッドを呼び出すためには、use
を使って Escaper のエイリアスを定義します。それから、エイリアスからstaticメソッドを呼び出します。 (もし、HelperLocatorFactory のインスタンスを生成していない場合は、Escaper::setStatic(new Escaper)
を呼び出す必要があります。)
下記は、staticメソッドを使用した例です:
タグヘルパー
HelperLocator のメソッドとしてヘルパーを使用できます。 利用できるヘルパーの一覧です:
フォームのためのヘルパー もあります。
a
<a>
タグヘルパー
base
<base>
タグヘルパー
img
<img>
タグヘルパー
label
<label>
タグヘルパー
links
<link>
タグヘルパーです、 リンクを add()
メソッドで追加し、それから出力します。
<meta>
タグヘルパーです。 add*()
メソッドで追加し、出力します。
ol
<ol>
タグ 、及び <li>
アイテムを出力するタグヘルパーです。タグを生成した後 (そのままの値かエスケープされた値) で出力を行います。
scripts
<script>
タグヘルパーです。リンクをセットして出力します。
scriptsFoot()
ヘルパーも同じように機能します。ただし、このヘルパーはHTMLボディの最後に出力を行います。
ul
<ul>
タグ 、及び <li>
アイテムを出力するタグヘルパーです。タグを生成した後 (そのままの値かエスケープされた値) で出力を行います。
styles
<link>
タグヘルパーです、リンクを生成した後、出力します。script
ヘルパーと同じで、それぞれのスタイルシートに優先度を設定することも出来ます。
tag
一般的なタグのヘルパーです。
title
<title>
タグのためのヘルパー
フォームヘルパー
フォームエレメント
formタグは下記のように利用します:
全てのHTML 5 input ヘルパーは同じ用法で利用します。input エレメントのフォーマットに配列を使用します。
配列を用いる事で特殊な用途においても、Aura.Html に依存する事なく他ライブラリがフォームのエレメントを生成する事が出来ます。
type
の値で有効なinputのエレメント一覧:
checkbox
checkbox
タイプは擬似属性の value_unchecked
使って (もうお分りかもしれませんが) hidden
エレメントの未チェックの値を設定するために使用します。
また label
擬似属性は、チェックボックスの後に置かれるラベルテキストを設定することが出来ます。
color
date
datetime
datetime-local
email
file
hidden
image
month
number
password
radio
このタイプは1つのラジオ、あるいは options
を設定する事で複数のラジオを生成する事ができます。
range
reset
search
select
<select>
タグ、及び <option>
タグのヘルパーです。 擬似属性の placeholder
は未選択時のプレイスホルダーとして扱われます。 'multiple' => true
を
を設定すると複数選択可能になります。そしてもし設定されていなければ、自動的にname属性に []
を追加します。
このヘルパーはoptionのグループ化にも対応しています。もし、options
の値が配列の場合は配列のキーが <optgroup>
のラベルに使用されます。
submit
tel
text
textarea
time
url
week
カスタムヘルパー
カスタムヘルパーは下記の2ステップで追加できます。
-
ヘルパークラスを作成します。
-
HelperLocator へクラスのファクトリーをセットします。
ヘルパークラスに必要な事は、__invoke()
メソッドを実装するだけです。
インデンティング、エスケーピングを利用したい場合は、 Aura\Html\AbstractHelper を継承する事を推奨しますが、
必須ではありません。
ここでは、定義済みのルーターから、新しいルーターを作成するためにルーターオブジェクトを返すヘルパーを作成してみます。
ヘルパークラスを作成したので、今度は HelperLocator にファクトリーをセットしてみます。
作成したヘルパークラスを返すように設定します。
{$PROJECT_PATH}/config/Common.php
を編集します。
HelperLocator のサービス名は、メソッド名も兼ねます。
これはヘルパーを $this->router()
で呼び出せるという事です:
ヘルペーのサービス名は自由につける事が出来ます。ヘルパークラスにサービス名をつけられるだけでなく、同じ名前でメソッドとしてコールできるのです。