Shopifyオリジナルテーマ実装のためのファイルの構造と読み込み方

本記事は私達の会社で作ったShopifyテーマ開発入門書『Hello Shopify Themes Shopifyテーマ開発ガイド』からの抜粋です。

本節では、次に示すテーマファイルの区分ごとに、特徴や実装上の留意点を解説してゆきます。

1. レイアウトファイル
2. テンプレートファイル
3. セクションファイル
4. スニペットファイル
5. アセットファイル（画像、CSS、JavaScriptなどの静的ファイル）
6. コンフィグファイル（ストア全体の設定ファイル）
7. ロケールファイル（翻訳ファイル）

公式ドキュメントの読み方、探し方

本節の解説内容は、オリジナルテーマの実装にあたって重要なポイントに焦点を絞りました。
テーマファイルの各仕様については、次に示す公式ドキュメントのURLから参照できるので、併せて参考にしてください。

こちらのTheme architectureドキュメントの、Layout・Templates・Sections・Config・Localesそれぞれの区分に分かれた下層ページに目を通すにあたっては、まず「Overview」を一読しておくと、必要な情報がどこに存在するか把握しやすいかと思います。
公式ドキュメントは定期的にアップデートされているので、テーマ開発に慣れてきた方もときどき覗いてみると良いでしょう。
なお、Theme architectureドキュメントに含まれる「Settings」解説ページは、特定のテーマファイルではなく、テーマ内で用いられるテーマ設定・セクション設定・ブロック設定に関しての情報がまとめられています。

レイアウトファイル

レイアウトファイルの layout/theme.liquid は、テーマ全体の基盤を担うLiquidファイルです。
テーマ構築に必須のファイルでもあります。HTMLの構成上必要な要素（ <head> タグや <body> タグ、DOCTYPE指定や文字エンコード記述など）や、テーマ全体の共通要素を記述します。

該当ファイル

• layout/theme.liquid

上記のほか、 layout/sample.liquid のような独自のカスタムレイアウトファイルを作成し、特定のページではカスタムレイアウトファイルを元にレンダリングするよう設定することも可能です。
Dawnテーマでは、パスワード保護ページ用のカスタムレイアウトファイルとして layout/password.liquid が利用されています。

カスタマイズ時の留意点

theme.liquid にはテーマ全体にとって必要な要素が詰まっているため、ゼロから独自実装するのではなく、Dawnの記述を下地として参照するのが良いでしょう。

削除すべきではない要素

特に、次のLiquid構文は削除しないようにしてください。

content_for_header

{{ content_for_header }}

<head> タグ内に存在するLiquidオブジェクトです。テーマの必須JavaScriptを出力します。
Shopify上のレポート機能や、Google Analyticsとの連携、Shopifyアプリ用のコードと関連しています。

content_for_layout

{{ content_for_layout }}

<body> タグ内に存在するLiquidオブジェクトです。閲覧するページ種別に対応するテンプレートファイルの内容がここに出力されます。

その他の把握しておきたい要素

加えて、Dawnの layout/theme.liquid で記述されているコードの内、把握しておきたい要素を紹介します。

canonical_url

<link rel="canonical" href="{{ canonical_url }}">

<head> タグに存在します。 {{ canonical_url }} は、SEO対策において重要な、ページの正規URLを出力するLiquidオブジェクトです。
Shopifyの公式ブログ上で解説の記事が公開されています。

preconnect

<link rel="preconnect" href="https://cdn.shopify.com" crossorigin>

<head> タグに存在します。ShopifyのCDNサーバーとの接続を事前に開始するようブラウザに示唆し、ページの表示速度を向上させられます。

titleタグ

Dawnの <title> タグは次のように記述されています。
コレクションページやブログ記事一覧ページでは、タグや現在のページ位置に基づいた情報を追加で表示する仕組みです。

<title>
  {{ page_title }}
  {%- if current_tags %} – tagged "{{ current_tags | join: ', ' }}"{% endif -%}
  {%- if current_page != 1 %} – Page {{ current_page }}{% endif -%}
  {%- unless page_title contains shop.name %} – {{ shop.name }}{% endunless -%}
</title>

{{ page_title }} オブジェクトで返される情報の詳細は公式ドキュメントを参照してください。

JavaScriptグローバル変数定義

Dawnの <body> タグ末尾には、JavaScriptのグローバル変数定義が記述されています。
いずれもDawnのJavaScript挙動に影響するため、DawnのJavaScriptを引き継いでオリジナルテーマを作成する場合は削除しないように留意しましょう。

テンプレートファイル

テンプレートファイルは、商品・ブログ・コレクションといったShopifyのページ種別ごとの表示を担うファイルです。
LiquidとJSON2種のファイルタイプどちらかを利用できます（一部ファイルはLiquidのみ）。
テーマ構築にあたって必須のファイルはありませんが、対応するテンプレートファイルが存在しないページは適切に表示できなくなるので、いずれのファイルも削除しない方が良いでしょう。

該当ファイル

• templates ディレクトリおよび templates/customers ディレクトリ内の全ファイル

テンプレートファイルとページ種別の対応関係

テンプレートファイルとShopifyのページ種別の対応関係は次のとおりです。

一般的なテンプレートファイル

オンラインストアの一般的なページに対応するテンプレート群です。各ファイルは .liquid 拡張子でも利用できます。

用途の特殊なファイル

限られた用途で利用されるテンプレート群です。
パスワード保護時のテンプレートファイルはJSONとLiquidどちらのファイルタイプでも問題ありませんが、 gift_card.liquid と robots.txt.liquid はJSONファイルにはできません。

アカウント関連のファイル

ユーザーのアカウント登録やログイン関連ページに対応するテンプレートファイル群です。各ファイルは .liquid 拡張子でも利用できます。
いずれも templates/customers ディレクトリ内に格納する必要があります。

代替テンプレートの作成

同じページ種別タイプで、異なる複数のレイアウトを適用したい場合は、代替テンプレートが役立ちます。
代替テンプレートを作成できるページのテンプレート種別は、次のとおりです。

• article
• blog
• collection
• page
• product

代替テンプレートのファイル名は、次の命名規則に沿って設定してください。

テンプレート種別.任意の代替名称.拡張子

たとえば、ストア内の固定ページ「お問い合わせ」と「FAQ」でそれぞれ異なるテンプレートを適用したい場合は page.contact.json と page.faq.json ファイルを作成します。
該当ページのShopify管理画面における「テーマテンプレート」欄で、代替テンプレートを選択すれば、適用は完了です。

代替テンプレート設定

この際、管理画面で選択・適用できるのはライブテーマに存在する代替テンプレートのみであることに注意してください。
ページ適用前の代替テンプレートをプレビューしたい場合は、テーマエディタを利用するか、ページURLの末尾に「?view=テンプレートの代替名称」パラメータを付与してアクセスすれば閲覧できます。

2種のファイルタイプについて

テンプレートファイルのファイルタイプはもともとLiquidのみでしたが、OS2.0仕様では、JSONも利用できるようになりました。
ファイルタイプはテンプレートごとに二者択一です。page.liquid と page.json を同時に存在させることはできません。

Liquid形式のテンプレートファイル

Liquidテンプレートは、レイアウトファイルと同じように、HTMLとLiquidを記述できます。また、ページ種別ごとに関連づけられたLiquidオブジェクトにもアクセス可能です。
次に示すのは templates/page.liquid のコードサンプルです。Liquidオブジェクトの {{ page.title }} は該当する固定ページのタイトルを、 {{ page.content }} は該当する固定ページのコンテンツを表示します。

<section>
  <h1>{{ page.title }}</h1>
  <div>
    {{ page.content }}
  </div>
</section>

JSON形式のテンプレートファイル

本書で何度か紹介してきたとおり、JSONテンプレートはHTMLもLiquidも記述できませんが、テンプレートに読み込むセクションの一覧をJSON内で定義できます。加えて、テーマエディタから動的にセクションを追加・変更・削除できるようになるため、カスタマイズ可能な領域も大幅に向上します。
DawnなどのOS2.0対応テーマではJSONテンプレートが基本です。次に示すDawnの templates/collection.json では、2点のセクションファイル sections/main-collection-banner.liquid と sections/main-collection-product-grid.liquid を読み込んでいます。

templates/collection.json

{
  "sections": {
    "banner": {
      "type": "main-collection-banner"
    },
    "product-grid": {
      "type": "main-collection-product-grid"
    }
  },
  "order": [
    "banner",
    "product-grid"
  ]
}

JSONテンプレートのデータ構造

JSONテンプレート内部には sections 、 order 属性の記述が必ず必要です。
sections 属性は該当テンプレートに読み込むセクションの一覧を、 order 属性はセクションの順序をそれぞれ定義します。
任意記述の属性も含め、JSONテンプレートで利用できる属性一覧は次のとおりです。

sections・order属性のデータ形式

続けて sections 属性と order 属性の記法を詳しく見ていきます。
sections 属性において、重要な値はセクションIDとセクションタイプです。
先程の templates/collection.json サンプルコードがそれぞれ何を表していたのか、置き換えてみます。

{
  "sections": {
    <セクションID（任意のID値）_A>: {
      "type": <セクションタイプの値（セクションファイル名）_A>
    },
    <セクションID（任意のID値）_B>: {
      "type": <セクションタイプの値（セクションファイル名）_A>
    }
  },
  "order": [
    <セクションID_A>,
    <セクションID_B>
  ]
}

セクションID

セクションIDは、該当セクションを示すIDとなる任意の値です。テンプレート内で一意である必要があり、英数字のみを受け入れます。
templates/collection.json のサンプルコードでは banner と product-grid が該当します。
order 属性内にセクションIDを記述することで、レンダリング順序を定義できます。

セクションタイプ

セクションタイプは、セクションIDに対して紐づけられるセクションファイル名を値として記述します。
templates/collection.json のサンプルコードでは main-collection-banner と main-collection-product-grid が該当します。
セクションIDとセクションタイプの意味を把握した上で、サンプルコードの元の記述をもう一度見てみましょう。

{
  "sections": {
    "banner": {
      "type": "main-collection-banner"
    },
    //略
  },
  "order": [
    "banner",
    //略
  ]
}

sections 属性内のセクションID banner に対し、セクションファイル sections/main-collection-banner.liquid が紐づけられているのが分かりますね。併せて order 属性内にもセクションID bannerが記述され、レンダリングするセクションの順序を定義しています。
これらの記述を元に、JSONテンプレートはセクションファイルをレンダリングしています。

その他の属性

セクションIDとセクションタイプの他に、該当セクションのレンダリング時に表示するブロックの情報や、セクション設定の値を定義できる属性も存在します。
本書では割愛しますが、関心がある方は公式ドキュメントを参照してみてください。

セクションファイル

セクションファイルは、テーマエディタとの関連づけを定義できるLiquidファイルです（関連づけは必須ではありません）。テンプレートファイルのように特定のページと結びついてはいないため、設計の自由度が高いのが特徴です。
HTMLとLiquidを記述できる他、セクションファイル固有のLiquidタグである {% schema %} タグによって、テーマエディタから操作可能な項目を設定したり、アプリブロック（※後述）や動的セクションに対応させたりすることができます。

該当ファイル

• sectionsディレクトリ内の全ファイル

セクションファイルのレンダリング

セクションファイルはテーマ内に存在するだけでは表示されません。レイアウトファイルもしくはテンプレートファイルに次のどちらかの記法で読み込み、レンダリングする必要があります。

セクションタグ：静的にレンダリングする

Liquidのセクションタグ {% section "セクションファイル名" %} を用いる記法です。
セクションタグは、セクションを静的にレンダリングします。
該当するセクションのレンダリング位置を変更したり、削除したりする際は、都度Liquidの書き換えが必要です。
静的セクションのテーマエディタ入力内容は config/settings_data.json 内に保持されます。
留意点として、静的セクションのインスタンスは複製できません。一つのセクションファイルを複数のテーマファイルに読み込んだ場合、テーマエディタによる編集内容は該当セクション間で共通です。
同一レイアウトのパーツであっても、それぞれ異なる値（たとえば別個のバナー画像など）をテーマエディタから設定したければ、別個のセクションファイル——たとえば sections/image-banner-a.liquid と sections/image-banner-b.liquid ——を用意しなければいけません。

JSONテンプレートに追加：動的にレンダリングする

JSONテンプレートを利用すると、セクションを動的にレンダリングできます。JSONテンプレート側の記法については、前述した解説「JSONテンプレートのデータ構造」を参照してください。
JSONテンプレートによるセクションの読み込みでは、都度Liquidを書き換える必要はありません。テーマエディタの操作によって、テンプレート内の好きな場所にセクションを追加・並び替え・削除できます。
ただし、セクションを動的レンダリング対象に含めるためには、該当セクション内に適切な {% schema %} タグの記述が必要です。
動的セクションのテーマエディタ入力内容は、レンダリング元のJSONテンプレート内で個別に保持されます。そのため、静的セクションとは異なり、同一のセクションファイルに対して別々の値を設定可能です。
なお、JSONテンプレートによってレンダリングされるセクションは、テーマ内にアプリを簡単に追加するための「アプリブロック」という仕組みを備えることができます。
アプリブロックについては5章で、アプリブロックをサポートするための記法は次節で後述します。

セクションファイルに記述できるもの

セクションファイルには通常のHTMLとLiquidの他に、次の要素を記述できます。

1. セクション固有のLiquidオブジェクト
2. セクションアセット
3. セクションスキーマ

ひとつずつ特徴を見てゆきましょう。

1. セクション固有のLiquidオブジェクト

セクションファイルおよび、セクションファイル内でレンダリングされたスニペットファイルでのみ利用できる、固有のLiquidオブジェクトです。次の3つに分類されます。

• セクションオブジェクト
• ブロックオブジェクト
• セクション変数

セクションオブジェクト

セクションオブジェクトは、セクション固有のプロパティと、テーマエディタから操作された「セクション設定」の値を出力します。セクション設定については「3-2. 動的セクションとブロックの作成」でも言及しましたね。テーマエディタから操作可能な、該当セクションの {% schema %} タグ内 settings 属性で定義されている設定のことです。
次のコードは、 settings 属性で定義された各設定のうち、設定ID heading が持つ値を表示します。

{{ section.settings.heading }}

ブロックオブジェクト

ブロックについては「3-2. 動的セクションとブロックの作成」でも詳しく紹介しましたが、改めて。
ブロックとは、テーマエディタから操作可能な、セクション固有のコンテンツブロックのことです。各ブロックに紐づく設定は、セクション設定と区別して「ブロック設定」と呼ばれます。
前置きが長くなりましたが、ブロックオブジェクトとは、各ブロックの属性とブロック設定の値を出力するものです。
次のコードは、ブロック設定で定義された設定ID slide_caption が持つ値を表示します。

{{ block.settings.slide_caption }}

留意点として、ブロック配列そのものはセクションオブジェクトに分類されます（ブロックオブジェクトではありません）。
配列内のブロックにアクセスする際は、次のコードのように、ブロック配列に対するループ処理などが必要です。

<div class="slider">
  {% for block in section.blocks %}
    <div class="slide">{{ block.settings.slide_caption }}</div>
  {% endfor %}
</div>

セクション変数

テーマにおけるLiquid変数の扱いは少々ややこしいのですが、セクション内で使える変数は、そのセクションの中で作成されたものだけです。レイアウトファイルや他のセクションファイルなど、自身以外のファイルで作成された変数にはアクセスできません。
例外として、スニペットファイルをレンダリングする際に値を渡せば、スニペットファイルからセクション変数を参照することはできます。
セクション固有のLiquidオブジェクトに関する紹介は以上です。

2. セクションアセット

続いて、セクションアセットとは、セクション固有のLiquidタグで紐づけるJavaScriptアセットとCSSアセットのことを指します。 {% javascript %} もしくは {% stylesheet %} という形で記述します。
記述されたセクションアセットは、 {{ content_for_header }} オブジェクトを介してテーマに読み込まれます。セクションアセットを利用する必要があるのは、該当セクションが複数テーマやストアへインストールされる場合のみです。本書では詳しく触れませんが、必要な方は公式ドキュメントを参照してみてください。

3. セクションスキーマ

セクション固有のLiquidタグで定義するテーマエディタとの関連づけです。 {% schema %} タグの中にJSON形式で記述します。
何度か触れてきた「セクション設定」も、このスキーマ内で制御されています。スキーマの記述を持たないセクションは、テーマエディタからの操作を受け付けません。
スキーマ内の値を書き換えれば、テーマエディタに表示される文言や入力欄のタイプをさまざまに変更できます。
{% schema %} タグ内部の記法については、「4-5. テーマエディタとスキーマ記法」に節を分割しました。併せて参照してください。

スニペットファイル

スニペットファイルは、すべてのLiquidファイル内でレンダリングできる、汎用性の高いLiquidファイルです。
ここまで紹介してきたレイアウト・テンプレート・セクションと比べ、特別なことはできない代わりに、制限もほぼ無いことが特徴と言えるでしょう。
たとえばページネーションやパンくずリストのような、テーマ内のあちこちで繰り返し使われるモジュールは、スニペットファイルの利用が適しています。

該当ファイル

• snipetsディレクトリ内の全ファイル

スニペットのレンダリング

スニペットファイルは、セクションファイルと同じく、テーマ内に存在するだけでは表示されません。固有のLiquidタグによるレンダリングが必要です。

{% render %} タグ

Liquidタグ {% render 'スニペットファイル名' %} を用いることで、どのLiquidファイルであっても、スニペットを静的にレンダリングできます。
さらに、 {% render %} タグにパラメータを追加することで、レンダリング元の親ファイル内に存在するLiquid変数を、スニペットに渡すことも可能です。 たとえば次に示すコードは、 {% render %} タグにパラメータを追加していないため、レンダリング元ファイルの変数にアクセスできません。

sections/section_sample.liquid

{% assign variable_sample = 'Hello World!' %}
{% render 'snippets_sample' %}

snippets/snippets_sample.liquid

{{ variable_sample }} //出力結果：空白（変数が渡されていないため、何も出力されない）

パラメータを渡すと、次のような出力結果になります。

sections/section_sample.liquid

{% assign variable_sample = 'Hello World!' %}
{% render 'snippets_sample', variable_sample: variable_sample %}

snippets/snippets_sample.liquid

{{ variable_sample }} //出力結果：Hello World!

スニペットからは変数を参照しているだけなので、スニペット内で変数の値を変更しても、レンダリング元の変数には影響しません。

sections/section_sample.liquid

{% assign variable_sample = 'Hello World!' %}
{% render 'snippets_sample', variable_sample: variable_sample %}
{{ variable_sample }} //出力結果：Hello World!

snippets/snippets_sample.liquid

{{ variable_sample }} //出力結果：Hello World!
{% assign variable_sample = 'enjoy Shopify!' %} //変数の値を変更
{{ variable_sample }} //出力結果：enjoy Shopify!

変数の他に、オブジェクトの情報を渡せる with パラメータ、配列の情報を渡せる for パラメータが存在します。本書では割愛しますが、公式ドキュメントも参照してみてください。

非推奨のタグ

古いテーマをメンテナンスする際、次のようなコードを見かけるかもしれません。

{% include 'スニペットファイル名' %}

これは既に非推奨となったスニペットのレンダリングタグです。この {% include %} タグは、 {% render %} タグと異なり、レンダリング元ファイルの変数を上書きするという特徴があります。
現時点では動作しますが、テーマのパフォーマンスを低下させるため、 {% render %} タグで置き換えるようにしましょう。

アセットファイル

アセットファイルは、画像・CSS・JavaScriptなど、テーマ内で利用するさまざまな素材ファイルの総称です。

該当ファイル

• assetsディレクトリ内の全ファイル

アセットのレンダリング

テーマ内でアセットを用いる際には、Liquidのアセットフィルターを利用します。たとえば次に示すコードは、 assets/base.css ファイルを読み込むためのHTMLタグを出力します。

{{ 'base.css' | asset_url | stylesheet_tag }}
//出力結果：<link href="//cdn.shopify.com/s/files/..中略../assets/base.css?xxxx" rel="stylesheet" type="text/css" media="all" />

Liquidフィルターについては、「4-3. Liquid文法解説」で前述しているので、併せて参照してください。

コンフィグファイル

コンフィグファイルは、テーマエディタから操作可能な「テーマ設定」を定義し、入力された値を保存するJSONファイルです。静的にレンダリングされたセクションのセクション設定・ブロック設定も、コンフィグファイルに保存されます。

該当ファイル

• config/settings_schema.json
• config/settings_data.json

settings_schema.json

settings_schema.json は、テーマのメタデータと、テーマ設定を定義します。
次に示すのは、メタデータを定義した上で、テーマ設定にSNSアカウントのURLを加えるためのサンプルコードです。

config/settings_schema.json

[
  {
    "name": "theme_info",
    "theme_name": "テーマの名称",
    "theme_author": "テーマの作者",
    "theme_version": "テーマのバージョン番号",
    "theme_documentation_url": "テーマのドキュメントURL",
    "theme_support_url": "テーマのサポート先URL"
  },
  {
    "name": "SNSアカウント情報",
    "settings": [
      {
        "type": "text",
        "id": "social_facebook_link",
        "label": "Facebook"
      },
      {
        "type": "text",
        "id": "social_twitter_link",
        "label": "Twitter"
      }
    ]
  }
]

メタデータ：テーマの追加情報

メタデータは、テーマに関する追加情報です。
settings_schema.json に "name": "theme_info" および次の属性を含めることでテーマエディタに表示されます。各属性はすべて必須です。

テーマ設定：テーマ全体で利用できる設定

テーマ設定は、テーマ全体のどこからでもアクセス可能な設定を定義します。
テーマエディタから操作できるという点では、セクションファイルの節で前述したセクション設定やブロック設定も同じですが、こちらはセクション外部からアクセスできないという制限がありました。
一方で、テーマ設定で定義された項目は、グローバルなLiquidオブジェクトとしてテーマのどこからでも利用することができます。
そのため、複数のセクションから利用する設定項目は、テーマ設定に含めると便利です。
たとえば次のサンプルでは、SNSアカウントのURLを設定する項目を定義しています。

{
  "name": "SNSアカウント情報",
  "settings": [
    {
      "type": "text",
      "id": "social_facebook_link",
      "label": "Facebook"
    },
    {
      "type": "text",
      "id": "social_twitter_link",
      "label": "Twitter"
    }
  ]
}

そして次のコードを記述すれば、どのLiquidファイルであっても、テーマ設定の該当項目を出力できます。

{{ settings.social_facebook_link }}

JSON内における設定の定義方法、各属性の詳細については、「4-5. テーマエディタとスキーマ記法」で後述します。

settings_data.json

settings_data.json は、テーマ設定および、静的セクションのセクション設定・ブロック設定の値を保存しているファイルです。テーマエディタから設定を変更すると、 settings_data.json の値も自動的に更新されます。※JSONテンプレートファイルに動的レンダリングされたセクションの設定値は、JSONテンプレート側に保存されます。
settings_data.json の留意点は「なるべく開発者側で編集しないこと」です。
マーチャントによるテーマエディタの入力内容が日々保存されているため、（開発フロー次第ではあるものの）同期を取るのが難しく、テーマエディタ外での無闇な編集は先祖返りに直結します。
Theme Kitによる開発フローを継続していたり、GitHubとの未連携テーマであったりする場合は、より注意が必要です。ignore対象に含める等、意図しない編集を防ぐ仕組みを整えておきましょう。

ロケールファイル

ロケールファイルは、テーマおよびテーマエディタの文言翻訳を扱うJSONファイルです。
ロケールファイルで定義された項目は、ストア管理画面の「言語」ページからも自由に更新できるようになります。

該当ファイル

• localesディレクトリ内の全ファイル

Dawnテーマに基づく開発では、主に次の4ファイルを考慮すると良いでしょう。

• en.default.json
• en.default.schema.json
• ja.json
• ja.schema.json

翻訳の扱い

テーマを日本語で表示した際、次のようなエラーメッセージがページに表示されることがあります。これは、該当箇所の日本語翻訳文言が存在しないために発生するエラーです。

translation missing: ja.sections.collection_template.filter_by_label

管理画面「言語」ページからも翻訳未了の項目は特定できるので、JSONファイルを直接編集する機会は少ないかと思いますが、JSON側から修正する場合は、 en.default.json の該当項目を参照し、同一のプロパティを ja.json にも追加すればOKです。

私達の会社で制作したShopifyテーマ開発入門書のご購入はこちらから。
完売後の増刷予定は現時点ではございません。印刷書籍をご希望の方は、ぜひお早めにお迎えください。

• 著者：川島さやか
• 出版：non-standard world, Inc.
• 判型・ページ数：B5判・248ページ
• 価格：3,850円（税込）※PDF版同梱、送料無料

特集ページへ