📁

【Shopify.dev和訳】Themes/Architecture/Sections/Section schema

2021/09/18に公開約18,200字

この記事について

この記事は、Themes/Architecture/Sections/Section schemaの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

セクションは、セクション固有の Liquid タグ {% schema %} をサポートします。これは、セクションの次の属性を定義する場所です。

{% schema %} タグは Liquid のタグです。しかし、タグの内容は出力されず、タグ内に含まれる Liquid のレンダリングも行われません。

name

name 属性は、テーマエディタに表示されるセクションタイトルを決定します。たとえば、次のスキーマは次の出力を返します。

{% schema %}
{
  "name": "Slideshow"
}
{% endschema %}

Output

tag

デフォルトでは、Shopify がセクションをレンダリングする際には、ユニークな id 属性を持つ<div>要素でラップされます。

<div id="shopify-section-[id]" class="shopify-section">// セクションの内容の出力</div>

<div>を使用したくない場合は、tag属性で使用する HTML 要素の種類を指定します。使える値は以下の通りです。

  • article
  • aside
  • div
  • footer
  • header
  • section

たとえば、次のスキーマは次の出力を返します。

/sections/slideshow.liquid/
{% schema %}
{
  "name": "Slideshow",
  "tag": "section"
}
{% endschema %}
Output
<section id="shopify-section-[id]" class="shopify-section">
  // セクションの内容の出力
</section>

class

Shopify がセクションをレンダリングするとき、それは shopify-section というクラスを持つ HTML 要素に包まれます。このクラスは class 属性で追加することができます。

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow"
}
{% endschema %}
Output
<section id="shopify-section-[id]" class="shopify-section slideshow">
  // セクションの内容の出力
</section>

settings

セクション固有の設定を作成して、マーチャントが設定オブジェクトを使ってセクションをカスタマイズできるようにすることができます。

/sections/slideshow.liquid/
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "settings": [
    {
      "type": "text",
      "id": "header",
      "label": "Header"
    }
  ]
}
{% endschema %}

Access section settings

セクションの設定は、section Liquid オブジェクトからアクセスできます。詳しくは「アクセス設定」を参照してください。

Section title

テーマエディターは、設定された入力タイプに基づいてセクションタイトルを作成します。どの入力がこのタイトルを制御するかを明示的に設定したい場合は、その入力の id 属性に title を設定します。

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ]
}
{% endschema %}

blocks

セクションには、ブロックを作成することができます。ブロックは、再利用可能なコンテンツのモジュールで、セクション内での追加、削除、並び替えが可能です。

ブロックには次のような属性があります。

Attribute Description Required
type ブロックタイプです。これは、識別子として使用できる自由形式の文字列です。この値にアクセスするには、Liquid block オブジェクトの type 属性を使用します。 Yes
name テーマエディターでブロックタイトルとして表示されるブロック名です。 Yes
limit 使用可能なこのタイプのブロックの数です。 No
settings ブロックに必要な設定をします。特定の設定は、テーマエディタでのブロックのタイトルとして使用されるかもしれません。 No

以下は、セクションにブロックを含める例です。

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "blocks": [
     {
       "name": "Slide",
       "type": "slide",
       "settings": [
         {
           "type": "image_picker",
           "id": "image",
           "label": "Image"
         }
       ]
     }
   ]
}
{% endschema %}

Access block settings

ブロックの設定は、block Liquid オブジェクトからアクセスできます。詳しくは「アクセス設定」を参照してください。

Render blocks

section オブジェクトblocks 属性をループすることにより、セクションのブロックをレンダリングできます。

{% for block in section.blocks %}
  {% case block.type %}
    {% when 'slide' %}
      <div class="slide" {{ block.shopify_attributes }}>
        {{ block.settings.image | img_url: '2048x' | img_tag }}
      </div>
    ...
  {% endcase %}
{% endfor %}

上記の例では、各ブロックのコンテンツは親コンテナの中に含まれており、そのコンテナには {{ block.shopify_attributes }} が属性として追加されています。Shopify のテーマエディターは、その属性を使って JavaScript API でブロックを識別します。

ブロックが単一の要素である場合、その要素がこの属性を持っていることを確認してください。

Show dynamic block titles in the theme editor

特定のケースでは、テーマエディタのサイドバーで、入力設定値をブロックのタイトルとして表示することができます。これにより、マーチャントがセクション内のブロックを識別したり、再配置するのに役立ちます。

テーマエディターは、ブロック内の設定の id 値をチェックして、ブロックのタイトルに使用する最適な設定を決定します。

テーマエディターは、以下の id 値を持つ設定を優先的に使用します。

  • heading
  • title
  • text

一致する id 値を持つ設定が存在しない場合は、ブロック名がタイトルとして使用されます。

例えば、設定 idheading のこのブロックは、Welcome to our store というタイトルでサイドバーに表示されます。

"blocks": [
  {
    "name": "Announcement",
    "type": "announcement",
    "settings": [
      {
        "type": "text",
        "id": "heading",
        "default": "Welcome to our store",
        "label": "Heading"
      }
    ]
  }
]

App blocks

セクションが JSON テンプレートの一部である場合、@app 型のブロックをサポートする必要があります。これらのブロックにより、アプリ開発者はマーチャント用のブロックを作成し、テーマコードを直接編集することなくアプリのコンテンツをテーマに追加することができます。

App block schema

@app 型のブロックは、セクションスキーマに含まれている必要があります。例えば、以下のようになります。

"blocks": [
  {
    "type": "@app"
  }
]

Render app blocks

アプリブロックをレンダリングするには、適切なタイプをチェックする必要があり、以下のコードを使用します。

{% render block %}

例えば、以下のようになります。

{% for block in section.blocks %}
  {% case block.type %}
    {% when '@app' %}
      {% render block %}
    ...
  {% endcase %}
{% endfor %}

App blocks and section settings

自動入力の設定が曖昧になるのを防ぐため、アプリブロックをサポートするセクションでは、セクションの設定として各タイプのリソース設定を 1 つだけ含めることができます。例えば、製品の設定は 1 つ、コレクションの設定は 1 つ、などです。

App block wrapper

アプリブロックは、2 つの方法でページに追加できます。

  • ブロックをレンダリングしているセクションの範囲内でブロックとして追加する。
  • セクションと同様の方法で、コンテンツをレンダリングするためにページの全幅を与えます。

アプリブロックはセクションではないため、Shopify はデフォルトで全幅のアプリブロックをプラットフォームで生成されたセクションで囲みます。しかし、apps.liquid という独自のセクションを作成することで、このデフォルトのセクションを上書きすることができます。

apps.liquid セクションのスキーマは、@app タイプのブロックとpresetを含む必要があります。これらのいずれかが欠けていると、テーマエディタでApps not supportedまたはApps section is invalidというエラーが返され、マーチャントはそのセクションを使用することができません。

例えば、以下のようになります。

/sections/apps.liquid
{% for block in section.blocks %}
  {% render block %}
{% endfor %}

{% schema %}
  {
    "name": "App wrapper",
    "settings": [],
    "blocks": [
      {
        "type": "@app"
      }
    ],
    "presets": [
      {
        "name": "App wrapper"
      }
    ]
  }
{% endschema %}

マーチャントがアプリセクション内でのアプリの見え方をコントロールできるようにするには、マーチャントがアプリブロックの周囲にマージンを追加できる設定を追加します。これにより、アプリセクションの余白がテーマのレイアウトと一致するようになります。

/sections/apps.liquid
<div class="{% if section.settings.include_padding %}padded{% endif %}">
  {% for block in section.blocks %}
    {% render block %}
  {% endfor %}
</div>

{% schema %}
  {
    "name": "App wrapper",
    "settings": [
      {
        "type": "checkbox",
        "id": "include_padding",
        "default": true,
        "label": "Make section margins the same as theme"
      }
    ],
    "blocks": [
      {
        "type": "@app"
      }
    ],
    "presets": [
      {
        "name": "App wrapper"
      }
    ]
  }
{% endschema %}

max_blocks

1 つのセクションには 16 ブロックの制限があります。max_blocks 属性で下限値を指定することができます。

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "max_blocks": 5,
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "blocks": [
     {
       "name": "Slide",
       "type": "slide",
       "settings": [
         {
           "type": "image_picker",
           "id": "image",
           "label": "Image"
         }
       ]
     }
   ]
}
{% endschema %}

presets

セクションプリセットとは、マーチャントがテーマエディタを使って JSON テンプレートにセクションを簡単に追加できるようにするための、セクションのデフォルト設定です。これらは、settings_data.json で定義されるテーマスタイルとは関係ありません。

presets オブジェクトには、以下の属性があります。

Attribute Description Required
name テーマエディターのセクション追加部分に表示されるプリセット名です。 Yes
settings 入力したい設定のデフォルト値のリストです。各項目には、設定名と値が含まれます。 No
blocks 入れておきたいデフォルトブロックのリストです。各エントリは、typesettingsの属性を持つオブジェクトでなければなりません。type属性の値は、組み込みたいブロックのタイプを反映している必要があり、settingsオブジェクトは、上記のsettings属性と同じ形式である必要があります。 No

以下は、セクションに presets を含める例です。

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "max_blocks": 5,
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "blocks": [
     {
       "name": "Slide",
       "type": "slide",
       "settings": [
         {
           "type": "image_picker",
           "id": "image",
           "label": "Image"
         }
       ]
     }
   ]
  "presets": [
     {
       "name": "Slideshow",
       "settings": [
         {
           "title": "Slideshow"
         }
       ],
       "blocks": [
         {
           "type": "image",
           "settings": []
         },
         {
           "type": "image",
           "settings": []
         }
       ]
     }
   ]
}
{% endschema %}

default

セクションを静的にレンダリングする場合は、preset オブジェクトと同じ属性を持つ default オブジェクトを使って、デフォルトの設定を定義することができます。

以下に、セクションにデフォルトを含める例を示します。

{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "max_blocks": 5,
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "blocks": [
     {
       "name": "Slide",
       "type": "slide",
       "settings": [
         {
           "type": "image_picker",
           "id": "image",
           "label": "Image"
         }
       ]
     }
   ]
  "default": [
     {
       "settings": [
         {
           "title": "Slideshow"
         }
       ],
       "blocks": [
         {
           "type": "image",
           "settings": []
         },
         {
           "type": "image",
           "settings": []
         }
       ]
     }
   ]
}
{% endschema %}

locales

セクションは、localesオブジェクトを通じて、独自の翻訳された文字列のセットを提供することができます。これはテーマの locales ディレクトリとは別のものなので、複数のテーマやショップにインストールされることを想定しているセクションにとっては便利な機能です。

locales オブジェクトの一般的なフォーマットは以下のとおりです。

General format
{
  "locales": {
    "language": {
      "translation_key": "translation_value"
    }
  }
}

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "max_blocks": 5,
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "blocks": [
     {
       "name": "Slide",
       "type": "slide",
       "settings": [
         {
           "type": "image_picker",
           "id": "image",
           "label": "Image"
         }
       ]
     }
   ]
  "default": [
     {
       "settings": [
         {
           "title": "Slideshow"
         }
       ],
       "blocks": [
         {
           "type": "image",
           "settings": []
         },
         {
           "type": "image",
           "settings": []
         }
       ]
     }
   ],
  {
    "locales": {
      "en": {
        "title": "Slideshow"
      },
      "fr": {
        "title": "Diaporama"
      }
    }
  }
}
{% endschema %}

翻訳された内容は、言語エディタの「セクション」タブに表示され、マーチャントが編集できるようになっています。編集した場合、変更は該当するロケールファイルに直接保存され、セクションのスキーマは変更されません。

これらの翻訳は、Liquid 翻訳フィルターt フィルター)からアクセスすることができ、キーは以下の形式になります。

sections.[section-name].[translation-description]

例えば、上記の例でtitleの翻訳を参照したい場合は、以下のようにします。

{{ 'sections.slideshow.title' | t }}

templates

templates 属性で特定のテンプレートを指定することで、セクションを特定のテンプレートに限定することができます。この属性には、ページタイプを表す文字列のリストを指定します。

例えば、以下のようになります。

/sections/slideshow.liquid
{% schema %}
{
  "name": "Slideshow",
  "tag": "section",
  "class": "slideshow",
  "max_blocks": 5,
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Slideshow"
    }
  ],
  "blocks": [
    {
      "name": "Slide",
      "type": "slide",
      "settings": [
        {
          "type": "image_picker",
          "id": "image",
          "label": "Image"
        }
      ]
    }
  ],
  "default": [
    {
      "settings": [
        {
          "title": "Slideshow"
        }
      ],
      "blocks": [
        {
          "type": "image",
          "settings": []
        },
        {
          "type": "image",
          "settings": []
        }
      ]
    }
  ],
  "templates": ["article", "index", "page", "product"]
}
{% endschema %}

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます