Latte タグ

標準で利用可能な Latte テンプレートシステムの全タグの概要と説明です。

出力

{$var} {...} {=...}

Latteでは、任意の式を出力するために{=...}タグを使用します。Latteはあなたの快適さを重視しているので、式が変数または関数呼び出しで始まる場合、等号を記述する必要はありません。これは実際には、ほとんどの場合、記述する必要がないことを意味します：

名前: {$name} {$surname}<br>
年齢: {date('Y') - $birth}<br>

式として、PHPから知っているものなら何でも記述できます。新しい言語を学ぶ必要はありません。例えば：

{='0' . ($num ?? $num * 3) . ', ' . PHP_VERSION}

前の例に意味を探さないでください。もし見つけたら、私たちに教えてください :-)

出力のエスケープ

テンプレートシステムの最も重要なタスクは何ですか？セキュリティホールを防ぐことです。そして、Latteは何かを出力するたびにまさにこれを行います。自動的にエスケープします：

<p>{='one < two'}</p>   {* 出力: '<p>one &lt; two</p>' *}

正確には、Latteはコンテキストに応じたエスケープを使用します。これは非常に重要でユニークなことなので、別の章を割きました。

そして、信頼できるソースからのHTMLでエンコードされたコンテンツを出力する場合はどうなりますか？その場合、エスケープを簡単に無効にできます：

{$trustedHtmlString|noescape}

noescapeフィルタの誤った使用は、XSS脆弱性の発生につながる可能性があります！何をしているかを完全に確信しており、出力される文字列が信頼できるソースからのものである場合を除き、絶対に使用しないでください。

JavaScriptでの出力

コンテキストに応じたエスケープのおかげで、JavaScript内で変数を非常に出力しやすく、Latteが正しいエスケープを処理します。

変数は文字列である必要はなく、任意のデータ型がサポートされており、JSONとしてエンコードされます：

{var $foo = ['hello', true, 1]}
<script>
	alert({$foo});
</script>

生成：

<script>
	alert(["hello", true, 1]);
</script>

これが、変数の周りに引用符を書かない理由でもあります：Latteは文字列の場合に自動的に追加します。そして、文字列変数を別の文字列に挿入したい場合は、単にそれらを連結します：

<script>
	alert('Hello ' + {$name} + '!');  // OK

	alert({="Hello $name!"});         // OK

	alert('Hello {$name} !');         // エラー!
</script>

フィルタ

出力される式はフィルタで変更できます。例えば、文字列を大文字に変換し、最大30文字に短縮します：

{$string|upper|truncate:30}

フィルタは、式の一部にもこのように適用できます：

{$left . ($middle|upper) . $right}

条件

{if} {elseif} {else}

条件は、PHPの対応するものと同じように動作します。PHPから知っているのと同じ式を使用でき、新しい言語を学ぶ必要はありません。

{if $product->inStock > Stock::Minimum}
	在庫あり
{elseif $product->isOnWay()}
	輸送中
{else}
	利用不可
{/if}

すべてのペアタグと同様に、{if} ... {/if}のペアもn:属性の形式で記述できます。例として：

<p n:if="$count > 0">在庫 {$count} 個</p>

n:属性にプレフィックスtag-を付けることができることを知っていましたか？そうすると、条件はHTMLタグの出力にのみ適用され、その間のコンテンツは常に表示されます：

<a href="..." n:tag-if="$clickable">Hello</a>

{* $clickable が false の場合 'Hello' を出力 *}
{* $clickable が true の場合 '<a href="...">Hello</a>' を出力 *}

素晴らしい。

n:else

条件{if} ... {/if}をn:属性の形式で記述する場合、n:elseを使用して代替分岐を指定するオプションがあります：

<strong n:if="$count > 0">在庫 {$count} 個</strong>

<em n:else>利用不可</em>

n:else属性は、n:ifset、n:foreach、n:try、`n:ifcontent`、およびn:ifchangedとのペアでも使用できます。

{/if $cond}

{if}条件内の式を終了タグで指定できることに驚くかもしれません。これは、条件を開くときにその値がまだわからない場合に便利です。これを遅延決定と呼びましょう。

例えば、データベースからのレコードを含むテーブルの出力を開始し、出力が完了した後にデータベースにレコードがなかったことに気づいたとします。そこで、終了タグ{/if}に条件を付け、レコードがない場合は何も出力されません：

{if}
	<h1>データベースからの行のリスト</h1>

	<table>
	{foreach $resultSet as $row}
		...
	{/foreach}
	</table>
{/if isset($row)}

便利でしょう？

遅延条件では{else}を使用できますが、{elseif}は使用できません。

{ifset} {elseifset}

参照 {ifset block}

{ifset $var}条件を使用して、変数（または複数の変数）が存在し、null以外の値を持っているかどうかを確認します。実際には、PHPのif (isset($var))と同じです。すべてのペアタグと同様に、n:属性の形式でも記述できます。例として示しましょう：

<meta name="robots" content={$robots} n:ifset="$robots">

{ifchanged}

{ifchanged}は、ループ（foreach、for、またはwhile）の最後のイテレーション以降に変数の値が変更されたかどうかを確認します。

タグに1つ以上の変数を指定すると、それらのいずれかが変更されたかどうかを確認し、それに応じてコンテンツを出力します。例えば、次の例では、名前のリストを出力するときに名前の最初の文字が変更されるたびに、それをヘッダーとして出力します：

{foreach ($names|sort) as $name}
	{ifchanged $name[0]} <h2>{$name[0]}</h2> {/ifchanged}

	<p>{$name}</p>
{/foreach}

ただし、引数を指定しない場合は、レンダリングされたコンテンツが前の状態と比較されます。つまり、前の例では、タグ内の引数を省略できます。そしてもちろん、n:属性を使用することもできます：

{foreach ($names|sort) as $name}
	<h2 n:ifchanged>{$name[0]}</h2>

	<p>{$name}</p>
{/foreach}

{ifchanged}内では、{else}句を指定することもできます。

{switch} {case} {default}

値を複数のオプションと比較します。これは、PHPから知っているswitch条件文に似ています。ただし、Latteはそれを改善します：

• 厳密な比較（===）を使用します
• breakは必要ありません

したがって、PHP 8.0で導入されたmatch構造と完全に同等です。

{switch $transport}
	{case train}
		電車で
	{case plane}
		飛行機で
	{default}
		その他
{/switch}

{case}句には、カンマで区切られた複数の値を含めることができます：

{switch $status}
{case $status::New}<b>新規項目</b>
{case $status::Sold, $status::Unknown}<i>利用不可</i>
{/switch}

ループ

Latteには、PHPから知っているすべてのループがあります：foreach、for、while。

{foreach}

ループはPHPとまったく同じように記述します：

{foreach $langs as $code => $lang}
	<span>{$lang}</span>
{/foreach}

さらに、これから説明するいくつかの便利な機能があります。

例えば、Latteは、作成された変数が誤って同じ名前のグローバル変数を上書きしていないかを確認します。これにより、$langに現在のページの言語が含まれていると期待していて、foreach $langs as $langがその変数を上書きしたことに気づかない状況を救います。

foreachループは、n:属性を使用して非常にエレガントかつ簡潔に記述することもできます：

<ul>
	<li n:foreach="$items as $item">{$item->name}</li>
</ul>

n:属性にプレフィックスinner-を付けることができることを知っていましたか？そうすると、ループ内で要素の内部のみが繰り返されます：

<div n:inner-foreach="$items as $item">
	<h4>{$item->title}</h4>
	<p>{$item->description}</p>
</div>

したがって、次のようなものが出力されます：

<div>
	<h4>Foo</h4>
	<p>Lorem ipsum.</p>
	<h4>Bar</h4>
	<p>Sit dolor.</p>
</div>

{else}

foreachループ内では、{else}句を指定できます。その内容は、ループが空の場合に表示されます：

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>申し訳ありませんが、このリストにはユーザーがいません</em></li>
	{/foreach}
</ul>

$iterator

foreachループ内で、Latteは$iterator変数を作成します。これを使用して、進行中のループに関する有用な情報を取得できます：

• $iterator->first – ループを初めて通過していますか？
• $iterator->last – 最後のパスですか？
• $iterator->counter – 1から数えて何番目のパスですか？
• $iterator->counter0 – 0から数えて何番目のパスですか？
• $iterator->odd – 奇数番目のパスですか？
• $iterator->even – 偶数番目のパスですか？
• $iterator->parent – 現在のイテレータを囲むイテレータ
• $iterator->nextValue – ループ内の次の項目
• $iterator->nextKey – ループ内の次の項目のキー

{foreach $rows as $row}
	{if $iterator->first}<table>{/if}

	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>

	{if $iterator->last}</table>{/if}
{/foreach}

Latteは賢く、$iterator->lastは配列だけでなく、項目数が事前にわからない一般的なイテレータ上でループが実行される場合にも機能します。

{first} {last} {sep}

これらのタグは{foreach}ループ内で使用できます。{first}の内容は、最初のパスの場合にレンダリングされます。{last}の内容は…推測できますか？はい、最後のパスの場合にレンダリングされます。これらは実際には{if $iterator->first}と{if $iterator->last}の短縮形です。

タグはn:属性としてもエレガントに使用できます：

{foreach $rows as $row}
	{first}<h1>名前のリスト</h1>{/first}

	<p>{$row->name}</p>

	<hr n:last>
{/foreach}

{sep}タグの内容は、パスが最後でない場合にレンダリングされます。したがって、出力される項目の間に区切り文字、例えばカンマをレンダリングするのに役立ちます：

{foreach $items as $item} {$item} {sep}, {/sep} {/foreach}

これはかなり実用的でしょう？

{iterateWhile}

foreachループ内で反復処理中に線形データをグループ化するのを簡略化します。条件が満たされている間、ネストされたループで反復処理を実行します。詳細なチュートリアルを読む。

上記の例の{first}と{last}をエレガントに置き換えることもできます：

{foreach $rows as $row}
	<table>

	{iterateWhile}
	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>
	{/iterateWhile true}

	</table>
{/foreach}

参照 batch および group フィルタ。

{for}

ループはPHPとまったく同じように記述します：

{for $i = 0; $i < 10; $i++}
	<span>項目 {$i}</span>
{/for}

タグはn:属性としても使用できます：

<h1 n:for="$i = 0; $i < 10; $i++">{$i}</h1>

{while}

ループもPHPとまったく同じように記述します：

{while $row = $result->fetch()}
	<span>{$row->title}</span>
{/while}

またはn:属性として：

<span n:while="$row = $result->fetch()">
	{$row->title}
</span>

終了タグに条件を持つバリアントも可能です。これはPHPのdo-whileループに対応します：

{while}
	<span>{$item->title}</span>
{/while $item = $item->getNext()}

{continueIf} {skipIf} {breakIf}

任意のループを制御するために、条件が満たされた場合に次の要素に進む{continueIf ?}タグと、ループを終了する{breakIf ?}タグを使用できます：

{foreach $rows as $row}
	{continueIf $row->date < $now}
	{breakIf $row->parent === null}
	...
{/foreach}

{skipIf}タグは{continueIf}と非常によく似ていますが、$iterator->counterカウンターをインクリメントしません。したがって、それを表示し、同時にいくつかの項目をスキップすると、番号付けにギャップが生じません。また、すべての項目をスキップした場合に{else}句がレンダリングされます。

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>申し訳ありませんが、このリストには大人がいません</em></li>
	{/foreach}
</ul>

{exitIf}

条件が満たされた場合にテンプレートまたはブロックのレンダリングを終了します（いわゆる「早期終了」）。

{exitIf !$messages}

<h1>メッセージ</h1>
<div n:foreach="$messages as $message">
   {$message}
</div>

テンプレートの挿入

{include 'file.latte'}

参照 {include block}

{include}タグは、指定されたテンプレートを読み込んでレンダリングします。私たちのお気に入りの言語PHPで言えば、次のようなものです：

<?php include 'header.phtml'; ?>

インクルードされたテンプレートは、アクティブなコンテキストの変数にアクセスできず、グローバル変数にのみアクセスできます。

インクルードされたテンプレートに変数を渡すには、次のようにします：

{include 'template.latte', foo: 'bar', id: 123}

テンプレート名は、任意のPHP式にすることができます：

{include $someVar}
{include $ajax ? 'ajax.latte' : 'not-ajax.latte'}

インクルードされたコンテンツはフィルタを使用して変更できます。次の例では、すべてのHTMLを削除し、大文字小文字を調整します：

<title>{include 'heading.latte' |stripHtml|capitalize}</title>

デフォルトでは、この場合、テンプレート継承はまったく機能しません。インクルードされたテンプレートでブロックを使用できても、インクルード先のテンプレートの対応するブロックは置き換えられません。インクルードされたテンプレートを、ページの独立した分離された部分またはモジュールと考えてください。この動作は、with blocks修飾子を使用して変更できます：

{include 'template.latte' with blocks}

タグで指定されたファイル名とディスク上のファイルとの関係は、ローダーの問題です。

{sandbox}

エンドユーザーが作成したテンプレートを挿入する場合は、Sandboxモードを検討する必要があります（詳細についてはsandbox ドキュメントを参照）：

{sandbox 'untrusted.latte', level: 3, data: $menu}

{block}

参照 {block name}

名前のないブロックは、テンプレートの一部にフィルタを適用する方法として機能します。例えば、このようにして、不要な空白を除去するstripフィルタを適用できます：

{block|strip}
<ul>
	<li>Hello World</li>
</ul>
{/block}

例外処理

{try}

このタグのおかげで、堅牢なテンプレートを非常に簡単に作成できます。

{try}ブロックのレンダリング中に例外が発生した場合、ブロック全体が破棄され、レンダリングはその後に続行されます：

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
{/try}

オプションの{else}句の内容は、例外が発生した場合にのみレンダリングされます：

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>申し訳ありませんが、ツイートを読み込めませんでした。</p>
{/try}

タグはn:属性としても使用できます：

<ul n:try>
	...
</ul>

例えばロギングのために、カスタム例外ハンドラを定義することも可能です。

{rollback}

{try}ブロックは、{rollback}を使用して手動で停止およびスキップすることもできます。これにより、すべての入力データを事前にチェックする必要がなく、レンダリング中にオブジェクトをまったくレンダリングしないことを決定できます：

{try}
<ul>
	{foreach $people as $person}
 		{skipIf $person->age < 18}
 		<li>{$person->name}</li>
	{else}
		{rollback}
	{/foreach}
</ul>
{/try}

変数

{var} {default}

新しい変数は、テンプレート内で{var}タグを使用して作成します：

{var $name = 'John Smith'}
{var $age = 27}

{* 複数宣言 *}
{var $name = 'John Smith', $age = 27}

{default}タグも同様に機能しますが、変数が存在しない場合にのみ作成します。変数がすでに存在し、null値を含んでいる場合、上書きされません：

{default $lang = 'cs'}

変数の型を指定することもできます。今のところ、これらは情報提供のみであり、Latteはそれらをチェックしません。

{var string $name = $article->getTitle()}
{default int $id = 0}

{parameters}

関数がパラメータを宣言するように、テンプレートも最初に変数を宣言できます：

{parameters
	$a,
	?int $b,
	int|string $c = 10
}

デフォルト値が指定されていない変数$aと$bは、自動的にデフォルト値nullを持ちます。宣言された型は今のところ情報提供のみであり、Latteはそれらをチェックしません。

宣言された変数以外の変数はテンプレートに渡されません。これは{default}タグとの違いです。

{capture}

出力を変数にキャプチャします：

{capture $var}
<ul>
	<li>Hello World</li>
</ul>
{/capture}

<p>キャプチャされた内容: {$var}</p>

すべてのペアタグと同様に、このタグもn:属性として記述できます：

<ul n:capture="$var">
	<li>Hello World</li>
</ul>

HTML出力は、出力時に不要なエスケープが発生しないように、Latte\Runtime\Htmlオブジェクトの形式で変数$varに保存されます。

その他

{contentType}

テンプレートが表すコンテンツのタイプを指定するタグ。オプションは次のとおりです：

• html (デフォルトタイプ)
• xml
• javascript
• css
• calendar (iCal)
• text

その使用は重要です。なぜなら、コンテキストに応じたエスケープを設定し、それによってのみ正しくエスケープできるからです。例えば、{contentType xml}はXMLモードに切り替え、{contentType text}はエスケープを完全に無効にします。

パラメータがapplication/xmlなどの完全なMIMEタイプである場合、さらにHTTPヘッダーContent-Typeをブラウザに送信します：

{contentType application/xml}
<?xml version="1.0"?>
<rss version="2.0">
	<channel>
		<title>RSSフィード</title>
		<item>
			...
		</item>
	</channel>
</rss>

{debugbreak}

プログラムの実行が一時停止され、デバッガが起動される場所を示します。これにより、プログラマーは実行環境を検査し、プログラムが期待どおりに機能しているかどうかを確認できます。Xdebugをサポートしています。プログラムを一時停止するタイミングを指定する条件を追加できます。

{debugbreak}                {* プログラムを一時停止 *}

{debugbreak $counter == 1}  {* 条件が満たされた場合にプログラムを一時停止 *}

{do}

PHPコードを実行しますが、何も出力しません。他のすべてのタグと同様に、PHPコードとは単一の式を意味します。参照 PHP の制限。

{do $num++}

{dump}

変数または現在のコンテキストをダンプします。

{dump $name} {* 変数 $name をダンプ *}

{dump}       {* 現在定義されているすべての変数をダンプ *}

ライブラリTracyが必要です。

{php}

任意のPHPコードを実行できます。タグはRawPhpExtension拡張機能を使用して有効にする必要があります。

{spaceless}

出力から不要な空白を除去します。spacelessフィルタと同様に機能します。

{spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/spaceless}

生成：

<ul> <li>Hello</li> </ul>

タグはn:属性としても記述できます。

{syntax}

Latteタグは、単一の波括弧で囲む必要はありません。実行時に別のデリミタを選択することもできます。これには{syntax …}を使用し、パラメータとして次を指定できます：

• double: {{...}}
• off: Latteタグの処理を完全に無効にします

n:属性を使用すると、例えばJavaScriptの1つのブロックに対してのみLatteを無効にできます：

<script n:syntax="off">
	var obj = {var: 123}; // これはもうタグではありません
</script>

LatteはJavaScript内でも非常に快適に使用できます。この例のように、{の直後に文字が続く構造を避けるだけで十分です。参照 JavaScript または CSS 内の Latte。

{syntax off}（つまり、n:属性ではなくタグ）を使用してLatteを無効にすると、{/syntax}までのすべてのタグが一貫して無視されます。

{trace}

Latte\RuntimeException例外をスローします。そのスタックトレースはテンプレートの精神に基づいています。つまり、関数やメソッドの呼び出しの代わりに、ブロックの呼び出しやテンプレートの挿入が含まれます。Tracyなどのスローされた例外を明確に表示するためのツールを使用している場合、すべての渡された引数を含むコールスタックが明確に表示されます。

HTMLコーダーヘルパー

n:class

n:classのおかげで、HTML属性classをまさに思い通りに非常に簡単に生成できます。

例：アクティブな要素にクラスactiveを持たせたい：

{foreach $items as $item}
	<a n:class="$item->isActive() ? active">...</a>
{/foreach}

さらに、最初の要素にクラスfirstとmainを持たせたい：

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main'">...</a>
{/foreach}

そして、すべての要素にクラスlist-itemを持たせたい：

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main', list-item">...</a>
{/foreach}

驚くほど簡単でしょう？

n:attr

n:attr属性は、classと同じ優雅さで任意のHTML属性を生成できます。

{foreach $data as $item}
	<input type="checkbox" n:attr="value: $item->getValue(), checked: $item->isActive()">
{/foreach}

返された値に応じて、例えば次のように出力されます：

<input type="checkbox">

<input type="checkbox" value="Hello">

<input type="checkbox" value="Hello" checked>

n:tag

n:tag属性は、HTML要素の名前を動的に変更できます。

<h1 n:tag="$heading" class="main">{$title}</h1>

$heading === nullの場合、タグ<h1>が変更なしで出力されます。それ以外の場合、要素の名前が変数の値に変更されます。したがって、$heading === 'h3'の場合、次のように出力されます：

<h3 class="main">...</h3>

Latteは安全なテンプレートシステムであるため、新しいタグ名が有効であり、望ましくないまたは有害な値が含まれていないことをチェックします。

n:ifcontent

空のHTML要素、つまり空白以外の何も含まない要素が出力されるのを防ぎます。

<div>
	<div class="error" n:ifcontent>{$error}</div>
</div>

変数$errorの値に応じて出力されます：

{* $error = '' *}
<div>
</div>

{* $error = 'Required' *}
<div>
	<div class="error">Required</div>
</div>

翻訳

翻訳タグが機能するには、トランスレータを有効化する必要があります。翻訳にはtranslateフィルタを使用することもできます。

{_...}

値を他の言語に翻訳します。

<a href="basket">{_'カート'}</a>
<span>{_$item}</span>

トランスレータには他のパラメータを渡すこともできます：

<a href="basket">{_'カート', domain: order}</a>

{translate}

テンプレートの一部を翻訳します：

<h1>{translate}注文{/translate}</h1>

{translate domain: order}Lorem ipsum ...{/translate}

タグはn:属性としても記述でき、要素の内部を翻訳します：

<h1 n:translate>注文</h1>