Twigが有効なテーマでは、Twig記法と従来のテンプレート記法を混在させて記述できます。
ただし、テンプレートの解決順により、特定の組み合わせでは記法が正しく反映されない場合があります。

テンプレートの解決順

Twigが有効な場合、テンプレートは以下の順序で解決されます。

1. Twigによる記述の解決
   （{% include %} や {% extends %} など、Twigの構文を含む部分が先に処理されます）

2. Twigが解決された後に、従来のテンプレート記法が解決される
   （@include や @extends など、従来の構文が後から処理されます）

このため、処理順の都合で、テンプレートが正しく解決されないパターンがあります。

テンプレートが解決されないパターン

• 従来の @include で読み込んだテンプレートにあるTwig記法は解決されない

• 従来の @extends で継承したテンプレート以下にあるTwig記法は解決されない

• 従来の @extends で継承されているテンプレートは、Twig記法でインクルード出来ない

拡張子は「twig」がおすすめ

Twigテンプレートには特に拡張子の制限はありません。
そのため、拡張子が .html のテンプレートファイルにTwigの記法を使っても、正しく動作します。

しかし、Twigで記述する場合は .twig 拡張子を使用することをおすすめします。
理由は、エディタがテンプレートをTwigとして認識し、構文ハイライトやコード補完、Twig専用のフォーマット機能など、開発を効率化する機能を利用できるためです。

ファイル例

index.twig
_entry.twig
_top.twig

URLでテンプレートを指定する場合の注意点

通常、動的テンプレートやインクルード用テンプレートでは、ファイル名をURLで直接指定することはありません。
しかし、ページURLとテンプレートファイル名を合わせたい場合には注意が必要です。

例として、検索結果ページを

https://example.com/search.html

で表示したい場合、テンプレートファイルを search.twig にすると、URLが

https://example.com/search.twig

になってしまいます。

これを避けるには、テンプレートファイル名を search.html.twig にします。
URLと一致する .html 部分を含めたファイル名にすることで、URLを変更せずにTwigテンプレートを利用できます。

URLで指定されたファイル名に対して自動的に .twig 拡張子を持つテンプレートも検索する仕組みがあるため、search.html.twig でも正しく読み込まれます。

a-blog cms での Twig の基本的な使い方について学んできましたが、他にも便利なTwigの機能がありますので、ぜひ目を通してみてください。

Twigのドキュメント

以下一部便利な機能を紹介します。

macro（マクロ）機能

Twigには、テンプレート内で関数のように使える macro（マクロ）機能 があります。
複雑なHTML構造や繰り返し処理をひとつの関数としてまとめられるため、特に階層構造のデータを扱うときに便利です。

階層データの例

たとえば「V2_Category_Tree」モジュールは、カテゴリが入れ子になった階層構造のデータを返します。

{
  categories:
    [
      {
        id: 1,
        name: "お知らせ",
      },
      {
        id: 2,
        name: "製品",
        children:
          [
            {
              id: 3,
              name: "家庭用製品",
            },
            {
              id: 4,
              name: "業務用製品",
              children:
                [
                  {
                    id: 6,
                    name: "業務用製品のお知らせ",
                  },
                ],
            },
          ],
      },
    ]
}

for文のみで書く場合

階層をすべて表示しようとすると、階層分だけfor文をネストする必要があり、コードが深く複雑になります。

{% set tree = module('V2_Category_Tree') %}

<ul>
  {% for category in tree.categories %}
    <li>
      {{ category.name }}
      {% if category.children is not empty %}
        <ul>
          {% for child in category.children %}
            <li>
              {{ child.name }}
              {% if child.children is not empty %}
                <ul>
                  {% for child2 in child.children %}
                    <li>{{ child2.name }}</li>
                  {% endfor %}
                </ul>
              {% endif %}
            </li>
          {% endfor %}
        </ul>
      {% endif %}
    </li>
  {% endfor %}
</ul>

macroを使ってシンプルに書く

macroを使えば、階層構造の処理を再帰的に呼び出せる関数としてまとめられるため、コードがすっきりします。

{% set tree = module('V2_Category_Tree') %}

{% macro renderCategories(categories) %}
  <ul>
    {% for category in categories %}
      <li>
        {{ category.name }}
        {% if category.children is not empty %}
          {{ _self.renderCategories(category.children) }}
        {% endif %}
      </li>
    {% endfor %}
  </ul>
{% endmacro %}

{{ _self.renderCategories(tree.categories) }}

• macroはテンプレート内で定義できる関数のような構文。

• 上記例ではrenderCategoriesというマクロを作成し、カテゴリをリスト表示。

• 子カテゴリ（children）が存在すれば同じマクロを再帰的に呼び出し、階層の深さに制限なく対応可能。

• 呼び出しは_self.マクロ名()で行います。

Twig記法をそのまま出力する

{{ ... }} や {% ... %} など、テンプレートとして解釈されてほしくない場合は verbatim タグを使用することで、そのまま出力することができます。

たとえば、他のテンプレートエンジン（Vue.js や Angular など）と併用し、{{ }} がTwigに解釈されないようにしたい場合などに便利です。

{% verbatim %}
  Twigの構文 {{ variable }} も
  そのまま出力されます。
{% endverbatim %}

本CMSでは、/themes/テーマ/ がドキュメントルート相当として扱われます。
そのため、静的サイトをそのまま themes 内に置いても動作するよう、テンプレート内のパスを自動で書き換える機能があります。

書き換え対象

パスの書き換えには、次の2種類があります。

1. ファイル指定の書き換え

対象となるのは以下の要素や属性です。

• {{ include('xxx') }} インクルードパス

• img / input / script / frame / iframe 要素の src属性

• srcset属性

• link 要素

• object / applet 要素

• background属性

書き換え仕様（ファイル指定）

1. スキーマ（http:// 等）から始まる場合 → 書き換えない

2. / のみの場合 → 書き換えない

3. / から始まり、ドキュメントルートから探索して見つかった場合 → 書き換えない

4. / から始まり、a-blog cms設置ディレクトリから探索して見つかった場合 → 書き換える

5. / から始まらない場合で、テンプレートからの相対パスとして探索して見つかった場合 → 書き換える

6. 上記に当てはまらず、継承テーマから探索して見つかった場合 → 書き換える

2. アンカー類の書き換え

対象となるのは以下の属性です。

• a 要素の href属性

• form 要素の action属性

書き換え仕様（アンカー類）

1. 空の場合 → 書き換えない

2. スキーマ（http:// 等）から始まる場合 → 書き換えない

3. # から始まる場合 → 書き換えない

4. / から始まらない場合 → 書き換えない

5. a-blog cms設置ディレクトリのパスから始まっている場合 → 書き換えない

6. 上記に当てはまらない場合 → ブログコードからのパスに書き換える

書き換えを行わない設定

このパス書き換えは便利ですが、全ブログで共通するリンクやグローバルナビなどでは、書き換えを行いたくない場合があります。

<a href="/">HOME</a>

このコードが子ブログ内にあると、
http://ドメイン/子ブログコード/ のトップページへのリンクに書き換わってしまいます。

書き換えを防ぐ方法

アンカー類のパス書き換えを行いたくない場合は、要素に acms_no_rewrite 属性を付与します。

<a href="/" class="acms_no_rewrite">HOME</a>

• class以外にも、独自データ属性などで指定可能です。

• 識別子 acms_no_rewrite は、config.system.yaml で変更できます。

acms_no_rewrite: custom_identifier

Vite（ヴィート）は、モダンなWeb開発のための高速ビルドツールです。本CMSのTwigテンプレートには、Viteでビルドしたファイルを簡単に読み込むための補助機能が組み込まれています。

使い方

a-blog cms で Vite を利用してバンドルしたファイルを読み込むためには、バックエンドとの統合で記載されている仕様に合わせて、script タグや link タグを出力する必要があります。

Twigテンプレート補助機能を使用することで、Vite の仕様に合わせてタグを出力することができるようになり、a-blog cms のテンプレート内で簡単に Vite を利用することができます。

Vite の設定

Vite の設定は vite.config.js に記述します。詳細は Vite のドキュメント を参照してください。

build.manifest を true に設定し、rollupOptions.input でエントリーポイントとなるファイルを指定します。 以下のサンプルは、themes/利用テーマ/src/js/main.js をエントリーポイントとして指定しています。

import { defineConfig } from 'vite';

export default defineConfig({
    // ...
    build: {
        manifest: true,
        rollupOptions: {
            input: {
                bundle: resolve(__dirname, 'src/js/main.js'),
            },
        },
    },
});

この設定をすることで、manifest.json にビルドされたアセットのパスが出力されるようになります。

スクリプトとスタイルの読み込み

Vite の設定が完了したら、a-blog cms のテンプレート内にスクリプトとスタイルを読み込むための記述を追加します。 head タグ内 @vite() を追加します。

<!DOCTYPE html>
<head>
  @vite('src/js/main.js')
</head>

複数のエントリーポイントを指定する場合は、配列で指定します。

<!DOCTYPE html>
<head>
  @vite(['src/js/main.js', 'src/js/main.css'])
</head>

これで、Vite の開発サーバーからビルドされたアセットが読み込まれるようになります。

本番環境での利用

Vite で本番環境用ビルドしたアセットを読み込めるようにするためには、a-blog cms 設置ディレクトリにある .env ファイルを編集します。

以下のように VITE_ENVIRONMENT に production を指定します。

# Vite
VITE_ENVIRONMENT=production # development | production

これで、Vite で本番環境用ビルドしたアセットが読み込まれるようになります。

設定

@vite() の第2引数にJSON形式でオプションを指定することができます。

出力ディレクトリの設定

例えば、Vite の設定で build.outDir を bundle に設定している場合、以下のように記述します。

import { defineConfig } from 'vite';

export default defineConfig({
    // ...
    build: {
        outDir: 'bundle',
    },
});

@vite() の第2引数に出力ディレクトリを指定します。

<!DOCTYPE html>
<head>
  @vite('src/js/main.js', {
    outDir: 'bundle'
  })
</head>

タグの属性をカスタマイズする

タグの属性をカスタマイズすることができます。

以下の例では、エントリーポイントから出力された script タグに async 属性を追加しています。

<!DOCTYPE html>
<head>
  @vite('src/js/main.js', {
    "scriptTagAttributes": {
      "async": true
    }
  })
</head>

また、link タグの属性もカスタマイズすることができます。 以下の例では、エントリーポイントから出力された link タグに type="text/css" 属性を追加しています。

<!DOCTYPE html>
<head>
  @vite('src/styles/main.css', {
    "linkTagAttributes": {
      "type": "text/css"
    }
  })
</head>

React の利用

React と @vitejs/plugin-react を利用する場合、既存の @vite と一緒に、追加で @viteReactRefresh を追加する必要があります。

<!DOCTYPE html>
<head>
  @viteReactRefresh
  @vite('src/js/main.jsx')
</head>

@viteReactRefresh は、React の Hot Module Replacement を有効にするためのスクリプトを出力します。

<script type="module">
  import RefreshRuntime from 'http://localhost:5173/@react-refresh'
  RefreshRuntime.injectIntoGlobalHook(window)
  window.$RefreshReg$ = () => {}
  window.$RefreshSig$ = () => (type) => type
  window.__vite_plugin_react_preamble_installed__ = true
</script>

グローバル変数

本拡張アプリをインストールすることで、以下のグローバル変数が利用できるようになります。

高度なカスタマイズ

環境変数を利用して、Vite の設定をカスタマイズすることができます。

a-blog cms設置ディレクトリにある .env ファイルを編集することで環境変数を設定します。

# Vite
VITE_ENVIRONMENT=production # development | production
VITE_MANIFEST_PATH=dist/.vite/manifest.json
VITE_DEV_SERVER_URL=http://localhost:5173

以下、環境変数の説明です。