NaifyView Native 構文

<nf-set> テンプレート内で変数を設定する

属性で変数を設定します。値をそのまま入れるなら value、式として評価するなら expr を使います。

<!-- リテラル文字列を変数へ入れる -->
<nf-set name="greeting" value="こんにちは"></nf-set>

<!-- 式を評価して変数へ入れる -->
<nf-set name="label" expr="user.name ~ ' さん'"></nf-set>

<!-- 配列 / map / range も式として扱える -->
<nf-set name="roles" expr="[person.role, guest.role]"></nf-set>
<nf-set name="payload" expr="{state: active_key, roles: roles}"></nf-set>
<nf-set name="pages" expr="1..10"></nf-set>

value と expr は同時に指定しません。タグの中身を変数へ入れたい場合は <nf-capture> を使います。

<nf-capture> 描画結果を変数へ入れる

タグ内の描画結果を文字列として変数に保存します。name で変数への代入、append で配列への追加を指定できます。

<!-- タグ内の描画結果を cardTitle へ入れる -->
<nf-capture name="cardTitle">
  <strong>{{ user.name }}</strong>
</nf-capture>

{{ cardTitle.raw() }}

<!-- append を使うと配列へ追加できる -->
<nf-capture append="rows">
  <li>{{ item.label }}</li>
</nf-capture>

name と append は同時に指定しません。どちらも無い場合や、名前が不正な場合は専用のエラーで止めます。

@this 変数名を指定して参照する

@this を使うと、テンプレートに渡された変数を名前で参照できます。参照する変数名を別の変数で切り替えたい場合に使います。

{{ @this[object_name].name }}
{{ @this['people'][active_person].role }}

認証変数の詳細 / $api.xxx

assignTrusted() で渡した変数だけは、テンプレートから PHP メソッドを呼べる認証変数として扱います。変数名の先頭に$が付くことで見分けられます。. / [] の解釈は通常変数と揃え、辿る先だけ PHP オブジェクトや配列になります。

$view->assign('user', $user);          // 通常の変数: {{ user.name }}
$view->assignTrusted('user', $user);  // メソッドを呼び出せる変数: {{ $user.isAuthed() }}
$view->assignTrusted('API', $API);    // メソッドを呼び出せる変数: {{ $API.getInformation() }}
$view->assignTrusted('api', $api);    // メソッドを呼び出せる変数: {{ $api.method() }}

{{ $api.formatPrice(item.price) }}
{{ $user.isAuthed() }}
{{ $API.getInformation() }}
{{ $api.labelFor(user.role) }}
{{ @filter($api.labelFor(user.role)).escape() }}

認証変数のプロパティやメソッドも、$obj.name や $obj.method() のようにドットで参照します。

テンプレートから呼び出すメソッドは、表示に必要な値を返す処理に絞ります。exit など、ページ全体の処理を終了させる操作は含めません。

<nf-if> 条件分岐を行う

test 属性の式が真と評価される場合に中身を描画します。現在の Native 構文は &&, ||, !, ==, != などの記号で記述します。

<!-- test が true の時だけ中身を描画する -->
<nf-if test="user.active && user.role == 'member'">
  ようこそ、{{ user.name }}さん
</nf-if>

<nf-elseif> 追加条件で分岐する

<nf-if> の追加条件分岐です。直前の条件が false の場合に評価されます。

<!-- 上から順に評価し、最初に true になったブロックだけ描画する -->
<nf-if test="count == 0">
  なし
<nf-elseif test="count < 10">
  少数
<nf-elseif test="count < 100">
  中程度
<nf-else>
  大量
</nf-if>

<nf-else> 条件に一致しない場合を描画する

<nf-if> / <nf-elseif> のいずれも true でなかった場合に描画されます。属性なし。

<!-- どの条件にも一致しなかった時の fallback -->
<nf-if test="user.active">
  有効ユーザー
<nf-else>
  無効ユーザー
</nf-if>

条件式 / test="..."

<nf-if>, <nf-elseif>, 三項演算子などで使う条件式のNative構文です。論理演算、定義済みかの判定、比較、配列アクセスは式出力と同じ式の評価処理を共有します。

<nf-if test="user.name == defined && user.age >= 20">
  {{ user.name }}
</nf-if>

<nf-if test="!flag || items.length() == 0">
  fallback
</nf-if>

<nf-if test="user.nickname != defined">
  nickname is missing
</nf-if>

<nf-if test="'alpha' in tags">
  hit
</nf-if>

<nf-if test="slug starts with 'docs/'">
  docs
</nf-if>

論理演算には &&、||、! を使います。値が定義されているかは value == defined、空の配列かは arr.length() == 0、null かは value == null で判定します。

比較には == / != を使います。=== / !== は使用できません。

<nf-for-each> 配列や iterable を繰り返す

配列・連想配列・iterable をループします。

<!-- items の各要素を item として描画する -->
<ul>
  <nf-for-each exp="item in items">
    <li>{{ item.label }}</li>
  </nf-for-each>
</ul>

<!-- key 付きで連想配列を読む -->
<nf-for-each exp="key, value in settings">
  {{ key }} = {{ value }}
</nf-for-each>

<!-- name を付けるとネスト時に outer.index のように参照できる -->
<nf-for-each exp="group in groups" name="outer">
  <nf-for-each exp="item in group.items" name="inner">
    {{ outer.index }}.{{ inner.index }}: {{ item }}
  </nf-for-each>
</nf-for-each>

<nf-for-range> 数値範囲を繰り返す

数値範囲でループします。基本の書き方はi = 0 to 10 step 1です。0..3 は値を公開しないショートカットとして扱います。

<!-- i に 0 から 10 までの値を入れて繰り返す -->
<nf-for-range exp="i = 0 to 10 step 1">
  <div>{{ i }}</div>
</nf-for-range>

<!-- step を指定して 10 ずつ進める -->
<nf-for-range exp="n = 0 to 100 step 10">
  {{ n }}
</nf-for-range>

<!-- 変数名なし。回数だけ回したい時のショートカット -->
<nf-for-range exp="0..3">
  <span class="dot"></span>
</nf-for-range>

変数名なしの 0..3 は繰り返し中の値を変数として参照できません。値が必要な時はi = 0 to 3 を使います。

<nf-break /> ループを抜ける

ループを抜けます。loop 属性なしの場合は最も内側のループが対象です。

<!-- item.stop が true になったら outer ループを抜ける -->
<nf-for-each exp="item in items" name="outer">
  <nf-if test="item.stop">
    <nf-break loop="outer" />
  </nf-if>
  {{ item.label }}
</nf-for-each>

ループの外で <nf-break> を書くと構文解析時のエラーになります。

<nf-continue /> 次の繰り返しへ進む

ループの次の繰り返しへ進みます。指定が無い時は最も内側のループが対象です。

<!-- hidden な item は描画せず、次の item へ進む -->
<nf-for-each exp="item in items">
  <nf-if test="item.hidden">
    <nf-continue />
  </nf-if>
  {{ item.label }}
</nf-for-each>

<!-- named loop を指定すると outer ループを continue できる -->
<nf-for-each exp="group in groups" name="outer">
  <nf-for-each exp="item in group.items" name="inner">
    <nf-if test="item.skip_group">
      <nf-continue loop="outer" />
    </nf-if>
    {{ item.label }}
  </nf-for-each>
</nf-for-each>

loop="outer" を付けると名前付きループの次の繰り返しへ進めます。指定が無い時は最内ループが対象です。

ループの状態を表す変数

ループの中で使える自動変数です。

<nf-for-each exp="item in items">
  {{ loop.index }}/{{ loop.length }}: {{ item }}
  <nf-if test="loop.last == false">, </nf-if>
</nf-for-each>

<!-- named loop 版 (name="outer" の場合 outer.index 等) -->
<nf-for-each exp="g in groups" name="outer">
  <nf-for-each exp="i in g.items" name="inner">
    {{ outer.index }}.{{ inner.index }}
  </nf-for-each>
</nf-for-each>

<nf-include> 別テンプレートを読み込む

別テンプレートをインクルードします。

<!-- 静的なテンプレートを読み込む -->
<nf-include src="partial/user-card.html"></nf-include>

<!-- 変数を渡す -->
<nf-include src="partial/user-card.html" with="{ user, active: status == 'warm' }"></nf-include>

<!-- rename して渡す -->
<nf-include src="partial/greeting.html" with="{ user as actor }"></nf-include>

<!-- include 先を式で決める -->
<nf-include dynamic="'partial/' ~ card_type ~ '.html'" with="{ user }"></nf-include>

<!-- 別テンプレートとして読み込む -->
<nf-include src="partial/heavy-card.html" bundle="false"></nf-include>

読み込み先は src または dynamic のどちらかで指定します。変数を渡す場合は with を使います。

<nf-macro> 再利用できる部品を定義する

再利用可能なマクロを定義します。同じテンプレート内から呼び出せます。

<!-- badge というマクロを定義する -->
<nf-macro name="badge" args="label, count">
  <span class="badge">{{ label }} ({{ count }})</span>
</nf-macro>

<!-- 定義したマクロを式として呼び出す -->
{{ badge('新着', 5) }}

<nf-layout> レイアウトを定義または使用する

レイアウトの定義 (define) または使用 (use)。<nf-slot> と組み合わせてコンポーネント合成やページ骨格の差し込みを行います。

<!-- 定義 (layouts/page.html) -->
<nf-layout define="page">
  <html>
    <head>
      <title><nf-slot name="title">Default Title</nf-slot></title>
    </head>
    <body>
      <main><nf-slot name="content">default</nf-slot></main>
    </body>
  </html>
</nf-layout>

<!-- 使用 -->
<nf-layout use="page" src="layouts/page.html">
  <nf-slot name="title">ユーザー一覧</nf-slot>
  <nf-slot name="content">
    <h1>ユーザー</h1>
  </nf-slot>
</nf-layout>

<!-- component 定義 (layouts/card.html) -->
<nf-layout define="card">
  <div class="card">
    <h3><nf-slot name="title"></nf-slot></h3>
    <div><nf-slot name="body"></nf-slot></div>
  </div>
</nf-layout>

<!-- 使用 -->
<nf-layout use="card" src="layouts/card.html" with="{ user }">
  <nf-slot name="title">{{ user.name }}</nf-slot>
  <nf-slot name="body">{{ user.bio }}</nf-slot>
</nf-layout>

<nf-slot> レイアウトへ内容を差し込む

レイアウトの差し込み口です。define 側では口を定義し、use 側では内容を差し込みます。

<!-- define 側: title という差し込み口を用意する -->
<nf-slot name="title">Default Title</nf-slot>

<!-- use 側: title へ内容を差し込む -->
<nf-slot name="title">ユーザー一覧</nf-slot>

例は <nf-layout> を参照してください。

<nf-literal> テンプレート構文を解釈せずに出す

中身を生のまま出力します。<nf-*> や {{ }} も解釈せずそのまま出ます。テンプレート構文自体をドキュメントに載せる時に使います。属性なし。

<!-- 中身の nf タグや {{ ... }} をテンプレート構文として解釈しない -->
<nf-literal>
  <nf-if test="...">これは解釈されない</nf-if>
  {{ この式もそのまま表示される }}
</nf-literal>

<nf-comment> 出力されないメモを書く

中身をコメント扱いにします。出力されません。属性なし。

<!-- テンプレート内に残すが、HTML には出力しない -->
<nf-comment>
  このメモは生成される HTML には含まれない
</nf-comment>

HTML コメント <!-- --> と違って、出力に残りません。

{{ ... }} 式出力

値または式を評価して出力します。autoEscape を有効にした場合でも、自動 HTML エスケープは {{ user.name }} のような変数の参照だけからなる式の値出力だけにかかります。{{ user.name ~ '<>' }} のような計算式は、テンプレートの作成者が組み立てた文字列としてそのまま出します。式の結果をエスケープしたい時は .escape() を明示します。

{{ user.name }}
{{ items[0].label }}
{{ count + 1 }}
{{ count % 2 ? 'odd' : 'even' }}
{{ mode == 'dev' ? 'DEV' : 'LIVE' }}
{{ a ~ b }}
{{ map['dynamic'] }}
{{ obj[i + '_name'] }}
{{ [person.name, guest.name].join(' / ') }}

値の出力と条件判定は式の評価処理を共有しているので、== defined, != defined, 三項演算子, %, [] なども同じ感覚で使えます。

通常の変数のドット呼び出しはメソッド呼び出しではなくフィルター処理として解釈します。通常のオブジェクトに無条件でメソッド呼び出しを開きません。

フィルターやメソッドはドットでつなげます。| や -> は使用できません。

式リテラル

配列、連想配列、数値の範囲は、式の中で直接作成できます。{{ ... }}, expr, test, with など、式を指定する場所で利用できます。

<nf-set name="payload" expr="{state: active_key, roles: [person.role, guest.role]}"></nf-set>
{{ payload.state }}
{{ payload.roles.join(' / ') }}

<nf-set name="pages" expr="1..5"></nf-set>
{{ pages.join(', ') }}

<nf-include src="partial/card.html" with="{ user, flags: [active_key, mode] }"></nf-include>

連想配列のキーは直接記述します。変数でキーを指定して値を読む場合は obj[key] を使います。

ドット記法のフィルター

フィルターはドット記法で指定します。obj.escape()、text.trim()、items.length() のように書きます。

{{ user.name.upper() }}
{{ items.length() }}
{{ text.trim().escape() }}
{{ user.nickname.default('未設定') }}
{{ html.raw() }}
{{ list.join(', ') }}
{{ tags.split(',').first() }}
{{ payload.jsonEncode().raw() }}
{{ feedback.category.urlEncode() }}
{{ row.datetime.toDate('Y-m-d H:i:s') }}
{{ user.enabled.toString() }}
{{ user.nickname.isEmpty().toString() }}
{{ user.nickname.isDefined().toString() }}
{{ user.name.contains('Mi').toString() }}
{{ route_path.startsWith('portal').toString() }}
{{ route_path.endsWith('profile').toString() }}
{{ title.truncate(20, '...') }}
{{ price.round(2) }}

default() は、未定義 / null / 空文字に対して使えます。[] / オブジェクトは、代替値への置き換えを前提にしません。false / 0 は曖昧な値として専用のエラーになります。

組み込みフィルター一覧

フィルターを明示的に適用する / @filter(...)

認証変数やマクロの戻り値にフィルターを適用する場合は、@filter(...) を使います。

{{ @filter($obj.method(test)).escape() }}
{{ @filter($obj.members[0].label(test)).slice(0, 6).upper() }}
{{ @filter(_self.render_badge_line(user.name, user.role)).replace('admin', 'lead') }}

認証変数の $obj.xxx はPHPオブジェクトの操作です。参照先の指定方法は通常の変数と同じで、$obj[methodName]() のような変数で名前を指定するメソッドも PHP オブジェクトに対して解決します。そこへドット記法のフィルターを繋げたい時だけ @filter(...) を使います。

テンプレートの基本設定

NaifyView::configure() でテンプレートの配置場所やキャッシュの保存先を設定し、NaifyView::create() に渡します。

$config = NaifyView::configure(__DIR__ . '/views')
    ->setCacheDir(__DIR__ . '/cache')
    ->setTemplateBasePath('pages')
    ->setTemplate('index.html')
    ->setAutoEscape(true);

$view = NaifyView::create($config);

自動エスケープの既定値はfalseです。有効にする場合は setAutoEscape(true) を指定します。計算式の出力には .escape() を明示します。詳しくは式出力を参照してください。