Nette Documentation Preview

syntax 
構文
*******

.[perex]
Latteの構文は、Webデザイナーの実用的な要件から生まれました。そうでなければ本当に難しい構造でもエレガントに記述できる、最もユーザーフレンドリーな構文を探しました。 同時に、すべての式はPHPとまったく同じように記述されるため、新しい言語を学ぶ必要はありません。すでに知っていることを活用するだけです。

以下は、いくつかの基本的な要素を示す最小限のテンプレートです：タグ、n:属性、コメント、フィルタ。

```latte
{* これはコメントです *}
<ul n:if=$items>                  {* n:ifはn:属性です *}
{foreach $items as $item}         {* foreachループを表すタグ *}
	<li>{$item|capitalize}</li>   {* フィルタ付きで変数を出力するタグ *}
{/foreach}                        {* ループの終わり *}
</ul>
```

これらの重要な要素と、それらが素晴らしいテンプレートを作成するのにどのように役立つかを詳しく見てみましょう。


タグ
====

テンプレートには、テンプレートのロジックを制御するタグ（例えば、*foreach* ループ）や式を出力するタグが含まれます。両方に単一のデリミタ `{ ... }` が使用されるため、他のシステムのように、どの状況でどのデリミタを使用するかを考える必要はありません。`{` 文字の後に引用符またはスペースが続く場合、Latteはそれをタグの開始とは見なしません。これにより、テンプレート内でJavaScript構造、JSON、またはCSSルールを問題なく使用できます。

[すべてのタグの概要|tags]をご覧ください。さらに、[カスタムタグ|custom-tags]を作成することもできます。


LatteはPHPを理解します
===============

タグ内では、よく知っているPHP式を使用できます：

- 変数
- 文字列（HEREDOCおよびNOWDOCを含む）、配列、数値など
- [演算子 |https://www.php.net/manual/en/language.operators.php]
- 関数とメソッドの呼び出し（[sandbox|sandbox]で制限可能）
- [match式 |https://www.php.net/manual/en/control-structures.match.php]
- [アロー関数 |https://www.php.net/manual/en/functions.arrow.php]
- [ファーストクラスcallable構文 |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- 複数行コメント `/* ... */`
- など…

さらに、LatteはPHP構文にいくつかの [便利な拡張機能 |#シンタックスシュガー] を追加します。


n:属性
====

`{if} … {/if}` などのすべてのペアタグは、単一のHTML要素上で動作する場合、n:属性の形式で書き換えることができます。例えば、冒頭の例の `{foreach}` もこのように記述できます：

```latte
<ul n:if="$items">
	<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>
```

機能は、それが配置されているHTML要素に適用されます：

```latte
{var $items = ['I', '♥', 'Latte']}

<p n:foreach="$items as $item">{$item}</p>
```

出力：

```latte
<p>I</p>
<p>♥</p>
<p>Latte</p>
```

プレフィックス `inner-` を使用すると、動作を要素の内部部分のみに適用するように変更できます：

```latte
<div n:inner-foreach="$items as $item">
	<p>{$item}</p>
	<hr>
</div>
```

出力：

```latte
<div>
	<p>I</p>
	<hr>
	<p>♥</p>
	<hr>
	<p>Latte</p>
	<hr>
</div>
```

または、プレフィックス `tag-` を使用すると、機能はHTMLタグ自体にのみ適用されます：

```latte
<p><a href="{$url}" n:tag-if="$url">Title</a></p>
```

これは、変数 `$url` に応じて出力されます：

```latte
{* $url が空の場合 *}
<p>Title</p>

{* $url が 'https://nette.org' を含む場合 *}
<p><a href="https://nette.org">Title</a></p>
```

しかし、n:属性はペアタグの単なる短縮形ではありません。純粋なn:属性も存在します。例えば、[n:href |application:creating-links#Presenterテンプレート内] や、コーダーにとって非常に便利なヘルパー [n:class |tags#n:class] などです。


フィルタ
====

[標準フィルタ |filters] の概要をご覧ください。

フィルタは縦棒の後ろに記述します（前にスペースがあってもかまいません）：

```latte
<h1>{$heading|upper}</h1>
```

フィルタは連結でき、左から右の順に適用されます：

```latte
<h1>{$heading|lower|capitalize}</h1>
```

パラメータはフィルタ名の後にコロンまたはカンマで区切って指定します：

```latte
<h1>{$heading|truncate:20,''}</h1>
```

フィルタは式にも適用できます：

```latte
{var $name = ($title|upper) . ($subtitle|lower)}
```

ブロックに：

```latte
<h1>{block |lower}{$heading}{/block}</h1>
```

または直接値に（[`{=}` |tags#出力] タグと組み合わせて）：
```latte
<h1>{='  Hello world  '|trim}</h1>
```


動的HTMLタグ .{data-version:3.0.9}
==============================

Latteは動的HTMLタグをサポートしており、タグ名に柔軟性が必要な場合に便利です：

```latte
<h{$level}>Heading</h{$level}>
```

上記のコードは、例えば変数 `$level` の値に応じて `<h1>Heading</h1>` または `<h2>Heading</h2>` を生成できます。Latteの動的HTMLタグは常にペアである必要があります。その代替案は [n:tag |tags#n:tag] です。

Latteは安全なテンプレートエンジンであるため、結果のタグ名が有効であり、望ましくないまたは有害な値が含まれていないことをチェックします。さらに、終了タグの名前が常に対応する開始タグの名前と同じであることを保証します。


コメント
====

コメントはこのように記述され、出力には含まれません：

```latte
{* これはLatteのコメントです *}
```

タグ内ではPHPコメントが機能します：

```latte
{include 'file.info', /* value: 123 */}
```


シンタックスシュガー
==========


引用符なしの文字列
---------

単純な文字列では引用符を省略できます：

```latte
PHPと同様:  {var $arr = ['hello', 'btn--default', '€']}

短縮形:    {var $arr = [hello, btn--default, €]}
```

単純な文字列とは、文字、数字、アンダースコア、ハイフン、ドットのみで構成されるものです。数字で始まってはならず、ハイフンで始まったり終わったりしてはなりません。 すべて大文字とアンダースコアだけで構成されていてはなりません。その場合、定数と見なされます（例：`PHP_VERSION`）。 そして、キーワードと衝突してはなりません：`and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`。


定数
---------

単純な文字列では引用符を省略できるため、区別するためにグローバル定数を先頭にバックスラッシュを付けて記述することをお勧めします：

```latte
{if \PROJECT_ID === 1} ... {/if}
```

この記述はPHP自体で完全に有効であり、バックスラッシュは定数がグローバル名前空間にあることを示します。


短縮三項演算子
-------

三項演算子の3番目の値が空の場合、省略できます（エルビス演算子と同様）：

```latte
PHPと同様:  {$stock ? '在庫あり' : ''}

短縮形:    {$stock ? '在庫あり'}
```


配列のキーのモダンな記述法
-------------

配列のキーは、関数呼び出し時の名前付きパラメータと同様に記述できます：

```latte
PHPと同様:  {var $arr = ['one' => 'item 1', 'two' => 'item 2']}

モダンな記述法:     {var $arr = [one: 'item 1', two: 'item 2']}
```


フィルタ
----

フィルタは任意の式に使用でき、全体を括弧で囲むだけです：

```latte
{var $content = ($text|truncate: 30|upper)}
```


`in` 演算子
--------

`in` 演算子は `in_array()` 関数の代わりに使用できます。比較は常に厳密 (`===`) です：

```latte
{* in_array($item, $items, true) と同等 *}
{if $item in $items}
	...
{/if}
```


歴史的な背景
------

Latteはその歴史の中で、数年後にPHP自体に登場した多くのシンタックスシュガーを導入しました。例えば、Latteでは、PHP自体で可能になるずっと前から、配列を `array(1, 2, 3)` の代わりに `[1, 2, 3]` と書いたり、nullsafe演算子 `$obj?->foo` を使用したりすることができました。Latteはまた、今日のPHPの `...$arr` 演算子と同等の配列展開演算子 `(expand) $arr` を導入しました。

変数が存在しない場合にエラーを発生させないnullsafe演算子 `?->` の類似物であるUndefined-safe演算子 `??->` は、歴史的な理由から生まれ、今日では標準のPHP演算子 `?->` を使用することをお勧めします。


LatteにおけるPHPの制限
===============

LatteではPHP式のみを記述できます。つまり、セミコロンで終了するステートメントは使用できません。クラスを宣言したり、[制御構造 |https://www.php.net/manual/en/language.control-structures.php]（例：`if`, `foreach`, `switch`, `return`, `try`, `throw` など）を使用したりすることはできません。代わりにLatteは独自の [タグ|tags] を提供します。 また、[属性 |https://www.php.net/manual/en/language.attributes.php]、[バッククォート（実行演算子） |https://www.php.net/manual/en/language.operators.execution.php]、または一部の [マジック定数 |https://www.php.net/manual/en/language.constants.magic.php] を使用することもできません。`unset`, `echo`, `include`, `require`, `exit`, `eval` も使用できません。これらは関数ではなく、PHPの特別な言語構造であり、したがって式ではないためです。コメントは複数行 `/* ... */` のみがサポートされています。

ただし、これらの制限は、[RawPhpExtension |develop#RawPhpExtension] 拡張機能を有効にすることで回避できます。これにより、テンプレート作成者の責任において、`{php ...}` タグ内で任意のPHPコードを使用できます。

構文

Latteの構文は、Webデザイナーの実用的な要件から生まれました。そうでなければ本当に難しい構造でもエレガントに記述できる、最もユーザーフレンドリーな構文を探しました。 同時に、すべての式はPHPとまったく同じように記述されるため、新しい言語を学ぶ必要はありません。すでに知っていることを活用するだけです。

以下は、いくつかの基本的な要素を示す最小限のテンプレートです：タグ、n:属性、コメント、フィルタ。

{* これはコメントです *}
<ul n:if=$items>                  {* n:ifはn:属性です *}
{foreach $items as $item}         {* foreachループを表すタグ *}
	<li>{$item|capitalize}</li>   {* フィルタ付きで変数を出力するタグ *}
{/foreach}                        {* ループの終わり *}
</ul>

これらの重要な要素と、それらが素晴らしいテンプレートを作成するのにどのように役立つかを詳しく見てみましょう。

タグ

テンプレートには、テンプレートのロジックを制御するタグ（例えば、foreach ループ）や式を出力するタグが含まれます。両方に単一のデリミタ { ... } が使用されるため、他のシステムのように、どの状況でどのデリミタを使用するかを考える必要はありません。{ 文字の後に引用符またはスペースが続く場合、Latteはそれをタグの開始とは見なしません。これにより、テンプレート内でJavaScript構造、JSON、またはCSSルールを問題なく使用できます。

すべてのタグの概要をご覧ください。さらに、カスタムタグを作成することもできます。

LatteはPHPを理解します

タグ内では、よく知っているPHP式を使用できます：

さらに、LatteはPHP構文にいくつかの 便利な拡張機能 を追加します。

n:属性

{if} … {/if} などのすべてのペアタグは、単一のHTML要素上で動作する場合、n:属性の形式で書き換えることができます。例えば、冒頭の例の {foreach} もこのように記述できます：

<ul n:if="$items">
	<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>

機能は、それが配置されているHTML要素に適用されます：

{var $items = ['I', '♥', 'Latte']}

<p n:foreach="$items as $item">{$item}</p>

出力：

<p>I</p>
<p>♥</p>
<p>Latte</p>

プレフィックス inner- を使用すると、動作を要素の内部部分のみに適用するように変更できます：

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

出力：

<div>
	<p>I</p>
	<hr>
	<p>♥</p>
	<hr>
	<p>Latte</p>
	<hr>
</div>

または、プレフィックス tag- を使用すると、機能はHTMLタグ自体にのみ適用されます：

<p><a href="{$url}" n:tag-if="$url">Title</a></p>

これは、変数 $url に応じて出力されます：

{* $url が空の場合 *}
<p>Title</p>

{* $url が 'https://nette.org' を含む場合 *}
<p><a href="https://nette.org">Title</a></p>

しかし、n:属性はペアタグの単なる短縮形ではありません。純粋なn:属性も存在します。例えば、n:href や、コーダーにとって非常に便利なヘルパー n:class などです。

フィルタ

標準フィルタ の概要をご覧ください。

フィルタは縦棒の後ろに記述します（前にスペースがあってもかまいません）：

<h1>{$heading|upper}</h1>

フィルタは連結でき、左から右の順に適用されます：

<h1>{$heading|lower|capitalize}</h1>

パラメータはフィルタ名の後にコロンまたはカンマで区切って指定します：

<h1>{$heading|truncate:20,''}</h1>

フィルタは式にも適用できます：

{var $name = ($title|upper) . ($subtitle|lower)}

ブロックに：

<h1>{block |lower}{$heading}{/block}</h1>

または直接値に（{=} タグと組み合わせて）：

<h1>{='  Hello world  '|trim}</h1>

動的HTMLタグ

Latteは動的HTMLタグをサポートしており、タグ名に柔軟性が必要な場合に便利です：

<h{$level}>Heading</h{$level}>

上記のコードは、例えば変数 $level の値に応じて <h1>Heading</h1> または <h2>Heading</h2> を生成できます。Latteの動的HTMLタグは常にペアである必要があります。その代替案は n:tag です。

Latteは安全なテンプレートエンジンであるため、結果のタグ名が有効であり、望ましくないまたは有害な値が含まれていないことをチェックします。さらに、終了タグの名前が常に対応する開始タグの名前と同じであることを保証します。

コメント

コメントはこのように記述され、出力には含まれません：

{* これはLatteのコメントです *}

タグ内ではPHPコメントが機能します：

{include 'file.info', /* value: 123 */}

シンタックスシュガー

引用符なしの文字列

単純な文字列では引用符を省略できます：

PHPと同様:  {var $arr = ['hello', 'btn--default', '€']}

短縮形:    {var $arr = [hello, btn--default, €]}

単純な文字列とは、文字、数字、アンダースコア、ハイフン、ドットのみで構成されるものです。数字で始まってはならず、ハイフンで始まったり終わったりしてはなりません。 すべて大文字とアンダースコアだけで構成されていてはなりません。その場合、定数と見なされます（例：PHP_VERSION）。 そして、キーワードと衝突してはなりません：and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor。

定数

単純な文字列では引用符を省略できるため、区別するためにグローバル定数を先頭にバックスラッシュを付けて記述することをお勧めします：

{if \PROJECT_ID === 1} ... {/if}

この記述はPHP自体で完全に有効であり、バックスラッシュは定数がグローバル名前空間にあることを示します。

短縮三項演算子

三項演算子の3番目の値が空の場合、省略できます（エルビス演算子と同様）：

PHPと同様:  {$stock ? '在庫あり' : ''}

短縮形:    {$stock ? '在庫あり'}

配列のキーのモダンな記述法

配列のキーは、関数呼び出し時の名前付きパラメータと同様に記述できます：

PHPと同様:  {var $arr = ['one' => 'item 1', 'two' => 'item 2']}

モダンな記述法:     {var $arr = [one: 'item 1', two: 'item 2']}

フィルタ

フィルタは任意の式に使用でき、全体を括弧で囲むだけです：

{var $content = ($text|truncate: 30|upper)}

in 演算子

in 演算子は in_array() 関数の代わりに使用できます。比較は常に厳密 (===) です：

{* in_array($item, $items, true) と同等 *}
{if $item in $items}
	...
{/if}

歴史的な背景

Latteはその歴史の中で、数年後にPHP自体に登場した多くのシンタックスシュガーを導入しました。例えば、Latteでは、PHP自体で可能になるずっと前から、配列を array(1, 2, 3) の代わりに [1, 2, 3] と書いたり、nullsafe演算子 $obj?->foo を使用したりすることができました。Latteはまた、今日のPHPの ...$arr 演算子と同等の配列展開演算子 (expand) $arr を導入しました。

変数が存在しない場合にエラーを発生させないnullsafe演算子 ?-> の類似物であるUndefined-safe演算子 ??-> は、歴史的な理由から生まれ、今日では標準のPHP演算子 ?-> を使用することをお勧めします。

LatteにおけるPHPの制限

LatteではPHP式のみを記述できます。つまり、セミコロンで終了するステートメントは使用できません。クラスを宣言したり、制御構造（例：if, foreach, switch, return, try, throw など）を使用したりすることはできません。代わりにLatteは独自の タグ を提供します。 また、属性、バッククォート（実行演算子）、または一部の マジック定数 を使用することもできません。unset, echo, include, require, exit, eval も使用できません。これらは関数ではなく、PHPの特別な言語構造であり、したがって式ではないためです。コメントは複数行 /* ... */ のみがサポートされています。

ただし、これらの制限は、RawPhpExtension 拡張機能を有効にすることで回避できます。これにより、テンプレート作成者の責任において、{php ...} タグ内で任意のPHPコードを使用できます。