セクション
このページで分かること
- セクションの役割（挿入したあとは元のセクションと独立したコピーになる）と、ウィジェットエリアとの使い分け
- 管理画面でのセクションの作成と、Portable Textのフィールドへの挿入（
/sectionと入力） - シードファイルでセクションを用意する方法と、テンプレートでセクションの現在の内容を直接描画する方法
このページの目次
セクション（Section）は、再利用できるPortable Textのブロックのまとまりです。編集者はセクションを任意のPortable Textフィールドに挿入でき、挿入したあとは、元のセクションを変えずに挿入したブロックを変更できます。
セクションは、行動を促す案内、著者の紹介文、決まった形のお知らせのように、繰り返し使う書き出しに使います。一か所で管理する1つの値を、表示しているすべての場所で更新したい場合は、ウィジェットエリアを使います。
セクションの作成
セクションは、EmDashの管理画面の「セクション」で作成し、管理します。
-
「新しいセクション」をクリックし、タイトル、スラッグ、必要に応じて説明を入力します。
-
編集者がセクションを挿入したときに入るコンテンツを追加します。
-
編集者がセクションを探すときに使いそうな語を、検索キーワードとして追加します。
-
セクションを保存します。
セクションのスラッグには、小文字の英字、数字、ハイフンを使います。スラッグは、テンプレートとAPIでセクションを識別するためのもので、公開ページのURLではありません。
コンテンツへのセクションの挿入
-
Portable Textフィールドにカーソルを置き、
/sectionと入力します。 -
タイトル、説明、キーワードでセクションを検索します。
-
セクションを選択すると、そのブロックがカーソルの位置に挿入されます。
-
必要に応じて挿入したコンテンツを編集し、エントリーを保存します。
エディターは、セクションのPortable Textをエントリーにコピーします。あとからライブラリのセクションを編集しても、すでに挿入したコピーは変わりません。
やさしい解説
WordPressのブロックエディターにある「再利用ブロック（パターン）」に近い機能です。定型の文章やお知らせをセクションとして登録しておき、記事の本文で /section と入力して呼び出します。挿入した時点で記事の中にコピーされるため、記事ごとに自由に書き換えられます。その代わり、元のセクションをあとで直しても、すでに挿入した記事には反映されません。全ページで同じ内容を常に最新にしたい場合は、ウィジェットエリアを使います。
シードファイルでのセクションの提供
テーマやスターターは、シードファイルでセクションを提供できます。ほかのシードのコンテンツと同じく、Portable Textのすべてのブロックとスパンに、変わらない _key を付けます。
次のシードファイルは、ニュースレターのセクションを追加します。
{
"version": "1",
"sections": [
{
"slug": "newsletter-signup",
"title": "Newsletter signup",
"description": "A short newsletter call to action",
"keywords": ["newsletter", "subscribe", "email"],
"source": "theme",
"content": [
{
"_type": "block",
"_key": "newsletter-heading",
"style": "h3",
"children": [
{
"_type": "span",
"_key": "newsletter-heading-text",
"text": "Receive new articles by email"
}
]
},
{
"_type": "block",
"_key": "newsletter-body",
"style": "normal",
"children": [
{
"_type": "span",
"_key": "newsletter-body-text",
"text": "Subscribe for occasional updates."
}
]
}
]
}
]
}
手書きのシードファイルを適用する前に、emdash seed --validate を実行します。適用と競合時の扱いのオプションはシードファイルを参照してください。
テーマが提供するセクションの source は theme です。管理画面で作成したセクションは user、EmDashがインポートしたWordPressの再利用ブロックは import になります。インポートの流れはコンテンツのインポートを参照してください。
テンプレートでのセクションの描画
ほとんどのサイトは、セクションのコンテンツを、コピー先のエントリーの一部として描画します。ライブラリにある現在の値を直接描画するには、スラッグでセクションを取得し、その内容を PortableText に渡します。
次のコンポーネントは、一か所から取得したニュースレターのセクションを描画します。
---
import { getSection } from "emdash";
import { PortableText } from "emdash/ui";
const section = await getSection("newsletter-signup");
---
{section && (
<aside aria-label={section.title}>
<PortableText value={section.content} />
</aside>
)}
この直接描画する方法では、描画のたびにライブラリの値を読み込みます。そのため、あとでセクションを編集すると、このコンポーネントを使っているすべての場所に影響します。
セクションのクエリとページ分割はランタイムAPIリファレンスで説明しています。プログラムから変更する場合は、Bearerトークンで認証し、状態を変更するすべてのリクエストに X-EmDash-Request: 1 を付けます。リクエストの本文とレスポンスはセクションのエンドポイントを参照してください。