ラテのタグ

Latte内蔵の全タグの概要と説明。

印刷

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

Latteでは、{=...} タグを使って、任意の式を出力しています。式の先頭が変数や関数呼び出しの場合、等号を書く必要はありません。つまり、実際には、ほとんど書く必要がないのです。

Name: {$name} {$surname}<br>
Age: {date('Y') - $birth}<br>

PHP で知っていることは何でも式として書くことができます。新しい言語を学ぶ必要がないだけです。例えば

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

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

エスケープ出力

テンプレートシステムの最も重要なタスクは何ですか？セキュリティホールを回避することです。そして、それはまさにLatteが出力に何かを印刷するときに行うことです。それは自動的にすべてをエスケープします。

<p>{='one < two'}</p>   {* prints: '<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>

これは、変数を引用符で囲まないでくださいという理由でもあります。ラテは文字列を引用符で囲みます。また、文字列の変数を別の文字列に入れたい場合は、単純に連結してください。

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

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

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

フィルタ

印刷された式は、フィルターによって変更することができます。例えば、この例では文字列を大文字に変換し、最大30文字に短縮しています。

{$string|upper|truncate:30}

また、以下のように式の一部にフィルタを適用することもできます。

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

条件

{if} {elseif} {else}

条件は、PHP の条件と同じように動作します。PHP でおなじみの表現が使えるので、新しい言語を学ぶ必要はありません。

{if $product->inStock > Stock::Minimum}
	In stock
{elseif $product->isOnWay()}
	On the way
{else}
	Not available
{/if}

他のペアタグと同様に、{if} ... {/ if} のペアは、例えばn:attribute のように書くことができます。

<p n:if="$count > 0">In stock {$count} items</p>

n:attributesに接頭辞tag- を付けることができることをご存知でしょうか？この場合、HTMLタグにのみ影響を与え、その間の内容は常に印刷されます。

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

{* prints 'Hello' when $clickable is falsey *}
{* prints '<a href="...">Hello</a>' when $clickable is truthy *}

いいですね。

n:else

の条件を{if} ... {/if} n:属性の形で記述した場合、 を使って別の分岐を指定するオプションがある：

。n:else`latte In stock {$count} items

not available ` n:else n:ifset, n:foreach, n:try, n:ifcontentおよび n:ifchanged.

{/if $cond}

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

たとえば、データベースからレコードを取得してテーブルのリストアップを開始し、レポートが完成した後で、データベースにレコードがないことに気がついたとします。そこで、終了タグ{/if} に条件を入れて、レコードがなければ、何も印刷されないようにします。

{if}
	<h1>Printing rows from the database</h1>

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

便利でしょう？

繰延条件では{else} も使えますが、{elseif} は使えません。

{ifset} {elseifset}

参照 {ifset block}

変数（あるいは複数の変数）が存在し、かつ非 null 値であるかどうかを調べるには、{ifset $var} 条件を使用します。これは、実際にはPHPのif (isset($var)) と同じです。他のペアタグと同様に、n:attributeの形式で書くことができますので、例で紹介しましょう。

<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:attributeを使うこともできます。

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

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

の中に{else} 節を入れることもできます。{ifchanged}.

{switch} {case} {default}

値を複数のオプションと比較します。これは、PHPでおなじみのswitch の構造に似ています。しかし、Latteではそれを改良しています。

• 厳密な比較を行う (===)
• は必要ありません。break

つまり、PHP 8.0が搭載しているmatch 構造とまったく同じものです。

{switch $transport}
	{case train}
		By train
	{case plane}
		By plane
	{default}
		Differently
{/switch}

節{case} は、カンマで区切られた複数の値を含むことができます。

{switch $status}
{case $status::New}<b>new item</b>
{case $status::Sold, $status::Unknown}<i>not available</i>
{/switch}

ループ

Latteでは、PHPでおなじみのforeach、for、whileといったループが利用可能です。

{foreach}

サイクルはPHPと全く同じように書きます。

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

さらに、これから説明するような便利な調整もあるそうです。

例えば、ラテは作成した変数が誤って同じ名前のグローバル変数を上書きしないようにチェックしています。これは、$lang がそのページの現在の言語であると仮定したときに、foreach $langs as $lang がその変数を上書きしてしまったことに気づかなかったときの救いになります。

foreachループもn:attributeを使えば非常にエレガントかつ経済的に書くことができる。

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

n:attributeの前に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>Sorry, no users in this list</em></li>
	{/foreach}
</ul>

$iterator

foreach ループの内部では、変数$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}

ラテは賢く、$iterator->last 配列だけでなく、事前に項目数が分からない一般的なイテレータ上でループを実行する場合にも有効です。

{first} {last} {sep}

これらのタグは、{foreach} のループの中で使用することができます。{first} のコンテンツは、最初のパスでレンダリングされます。 {last} のコンテンツがレンダリングされる......わかるかな？そう、最後のパスです。これらは実は、{if $iterator->first} と{if $iterator->last} のショートカットです。

タグはn:attributesと書くこともできる．

{foreach $rows as $row}
	{first}<h1>List of names</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}

バッチフィルター、グループフィルターも参照のこと。

{for}

サイクルはPHPと全く同じように書きます。

{for $i = 0; $i < 10; $i++}
	<span>Item #{$i}</span>
{/for}

タグはn:attributeと書くこともできる。

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

{while}

ここでも、PHPと全く同じ方法でサイクルを書きます。

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

あるいはn:attributeのように。

<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>Sorry, no adult users in this list</em></li>
	{/foreach}
</ul>

{exitIf}

ある条件が満たされたとき、テンプレートまたはブロックのレンダリングを終了します（すなわち、「早期終了」）。

{exitIf !$messages}

<h1>Messages</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 'untrusted.latte', level: 3, data: $menu}

{block}

こちらもご覧ください {block name}

名前のないブロックは、テンプレートの一部にフィルタを適用する機能を提供します。例えば、ストリップフィルターを適用して不要なスペースを削除することができます。

{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>Sorry, the tweets could not be loaded.</p>
{/try}

このタグはn:attributeと書くこともできる．

<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}

{* Multiple declaration *}
{var $name = 'John Smith', $age = 27}

{default} タグも同様に動作しますが、変数が存在しない場合にのみ変数を作成する点が異なります。

{default $lang = 'cs'}

変数の種類を指定することもできる。今のところ、これらは情報提供であり、ラテはチェックしない。

{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} タグを使用することで、出力を変数に取り込むことができます。

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

<p>Captured: {$var}</p>

このタグは、他のペアタグと同様にn:attributeと書くこともできる：

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

HTML出力は、印刷時に不要なエスケープを避けるため、Latte\Runtime\Html オブジェクトとして$var 変数に格納される。

その他

{contentType}

タグを使用して、テンプレートが表すコンテンツの種類を指定します。オプションは以下の通りです。

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

この機能は，文脈に応じたエスケープを設定し，Latteが正しくエスケープできるようにするために重要です．例えば、{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 feed</title>
		<item>
			...
		</item>
	</channel>
</rss>

{debugbreak}

コードの実行が中断される場所を指定します。プログラマが実行環境を検査し、コードが期待通りに実行されることを確認するためのデバッグ目的で使用されます。Xdebugに対応しています。さらに、コードがブレークする条件を指定することができます。

{debugbreak}                {* breaks the program *}

{debugbreak $counter == 1}  {* breaks the program if the condition is met *}

{do}

PHPコードを実行し、何も表示しません。他のタグと同様に、PHPコードは単一の式です。PHPの制限を参照してください。

{do $num++}

{dump}

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

{dump $name} {* dumps the $name variable *}

{dump}       {* dumps all the defined variables *}

Tracy パッケージが必要です。

{php}

任意の PHP コードを実行できるようにします。このタグはRawPhpExtensionエクステンションを使用してアクティブにする必要があります。

{spaceless}

不要な空白を削除する。スペースレスフィルタと似ている。

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

出力は

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

タグは、n:attributeと書くこともできる。

{syntax}

ラテタグは中括弧だけで囲む必要はありません。実行時であっても、別のセパレータを選択することができます。これは、{syntax…} 、パラメータにすることができます。

• doubleとする。 {{...}}
• off: Latteタグを完全に無効にする

n:attributeという記法を用いると、JavaScriptのブロックに対してのみLatteを無効にすることができます。

<script n:syntax="off">
	var obj = {var: 123}; // this isn't a tag any more
</script>

JavaScriptでもLatteは快適に使えますが、この例のように{の直後に文字が来るような構成は避けてください、詳しくはJavaScriptやCSSでのLatteをご覧ください。

{syntax off} (つまりn:属性ではなくタグ)でLatteをオフにすると、{/syntax} までのタグは厳密に無視されます。

{trace}

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

HTMLタグヘルパー

n:class

n:class のおかげで、必要な HTML 属性class を正確に生成することが非常に簡単になりました。

例を挙げましょう。active 要素に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 属性はn: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:タグ

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">{_'Basket'}</a>
<span>{_$item}</span>

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

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

{translate}

Překládá části šablony:

<h1>{translate}Order{/translate}</h1>

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

タグは、要素の内部を翻訳するために、n:attributeと記述することも可能です。

<h1 n:translate>Order</h1>