テーマでフィールド定義を宣言する
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
テーマにフィールド定義の JSON ファイルを置くと、そのテーマを使うブログで、管理画面で作った定義と同じように編集画面に出ます。テンプレートと一緒に定義もファイルで持ち運べるため、案件をまたいでフィールドを使い回せます。
置き場所と読み込まれる条件
対象 | ファイル |
|---|---|
エントリー |
|
カテゴリー |
|
ブログ |
|
ユーザー |
|
モジュール |
|
コンポーネント |
|
テーマの宣言が効くのは、そのテーマを使っているブログです。
親テーマ(
テーマ名@親テーマ名)がある場合は、親テーマのファイルも読みます。同じコードのフィールドセットは、子テーマのものがフィールドセットごと置き換わります。ファイルを書き換えると、次の表示から反映されます。
ファイルが 1MB を超える、JSON として読めない、
versionやentityTypeが違う場合は、ファイルごと読みません。形の誤ったフィールドセット・フィールドはその部分だけ読まず、知らないキーは無視します。いずれも監査ログに警告を残します。
完全な例
エントリーの「イベント情報」を宣言した entry.json です。そのまま読み込めます。表示条件の event はカテゴリーのコードです。そのブログに「event」カテゴリーが無いと、条件を読み替えられないため、このフィールドセットは無効で読み込まれます。
{
"version": 1,
"entityType": "entry",
"sets": [
{
"code": "event",
"label": "イベント情報",
"description": "イベントカテゴリーのエントリーに出します。",
"status": "open",
"layout": { "placement": "foot" },
"conditions": {
"or": [
{ "and": [ { "subject": "category", "operator": "eq", "value": "event", "axis": "descendant-or-self" } ] }
]
},
"fields": [
{ "key": "cf_event_box", "label": "開催情報", "type": "accordion" },
{
"key": "cf_event_date",
"label": "開催日",
"labels": { "en": "Date" },
"type": "date",
"parentKey": "cf_event_box",
"config": { "width": 50 },
"validation": { "required": "publish", "rules": [] }
},
{
"key": "cf_event_place",
"label": "会場",
"type": "text",
"parentKey": "cf_event_box",
"config": { "width": 50, "placeholder": "例: 東京国際フォーラム" },
"validation": { "required": "none", "rules": [ { "method": "maxlength", "arg": "100", "message": "100 文字以内で入力してください。" } ] }
},
{
"key": "cf_event_type",
"label": "種類",
"type": "select",
"config": {
"options": [
{ "value": "seminar", "label": "セミナー" },
{ "value": "workshop", "label": "ワークショップ" }
],
"emptyLabel": "選択してください"
}
},
{
"key": "cf_event_capacity",
"label": "定員",
"type": "number",
"description": "セミナーのときだけ入力します。",
"config": { "suffix": "名" },
"conditions": {
"or": [ { "and": [ { "field": "cf_event_type", "operator": "eq", "value": "seminar" } ] } ]
},
"validation": { "required": "none", "rules": [ { "method": "min", "arg": "1" } ] }
},
{
"key": "cf_event_memo",
"label": "社内メモ",
"type": "textarea",
"search": false,
"config": { "visibility": { "default": "hidden", "byAuth": { "editor": "editable" } } }
}
]
}
]
}この例では、次のことを宣言しています。
「イベント情報」を本文の下(
foot)に出し、「event」カテゴリーとその配下のエントリーだけに出します。「開催日」「会場」をアコーディオン「開催情報」の中に、50% の幅で横に並べます。「開催日」は公開時に必須です。
「種類」がセミナーのときだけ「定員」を出します。
「社内メモ」は、管理者と編集者だけに出し、ほかの人には出しません。キーワード検索の対象にしません。
トップレベルとフィールドセットのキー
キー | 必須 | 型 | 既定値 | 内容 |
|---|---|---|---|---|
| 必須 | 数値 | — |
|
| 必須 | 文字列 | — | ファイル名と同じ対象( |
| 必須 | 配列 | — | フィールドセットの配列。 |
フィールドセットのキー | 必須 | 型 | 既定値 | 内容 |
|---|---|---|---|---|
| 必須 | 文字列 | — | 半角英数字とアンダースコアの 64 文字以内。 |
| 必須 | 文字列 | — | ラベル。 |
| 文字列 |
| 説明。 | |
| 文字列 |
|
| |
| オブジェクト |
|
| |
| オブジェクト |
| 表示条件(後述)。 | |
| 配列 |
| フィールドの配列。 | |
| 文字列 | — |
|
フィールドのキー
キー | 必須 | 型 | 既定値 | 内容 |
|---|---|---|---|---|
| 必須 | 文字列 | — | テンプレートのキー。半角英字かアンダースコアで始まる、半角英数字とアンダースコアの 64 文字以内。 |
| 必須 | 文字列 | — | ラベル。 |
| 必須 | 文字列 | — | 型のキー( |
| オブジェクト | なし | ロケールごとのラベル( | |
| 文字列 |
| 説明。 | |
| 文字列 |
|
| |
| 文字列 |
| 入れる箱・フィールドグループ・ブロックのキー。 | |
| 真偽値 |
| キーワード検索の対象にするか。 | |
| オブジェクト |
| 型ごとの設定と、共通の設定(後述)。 | |
| オブジェクト | 任意・チェックなし |
| |
| オブジェクト |
| 条件付き表示(後述)。 | |
| 整数 | なし | テーマの宣言だけで使えます。管理画面で作った定義との並び順を数値で決めます。 |
共通の設定の config のキーは次のとおりです。型ごとの設定のキーは「入力の型の設定(文字・選択・日付・数値)」「メディア・参照・地図・アップロード・ブロックエディターの型の設定」「レイアウトの型(見出し・メッセージ・行・タブ・アコーディオン)」「フィールドグループ(繰り返し)」の表を参照してください。
config のキー | 型 | 内容 | 例 |
|---|---|---|---|
| 整数 | 列幅(25・33・50・66・75・100)。ほかの値は 100 になります。 |
|
| 文字列 | 初期値。 |
|
| 文字列 | 補足(ツールチップ)。 |
|
| 文字列 | 入力欄の長さ( |
|
| 真偽値 | 条件付き表示で隠れているときは値を保存しない。 |
|
| オブジェクト | 権限・ロール別の表示。 |
|
条件と参照の書き方
表示条件・条件付き表示は、どちらも {"or": [ {"and": [ 条件, … ]}, … ]} の形で書きます。and の中をすべて満たすか、or のどれかの組を満たすときに出します。
条件のキー | 内容 |
|---|---|
| 表示条件で使う項目の名前( |
| 条件付き表示で比べるフィールドのキー。フィールドの |
|
|
| 比べる値。 |
|
|
カテゴリー・ブログ・ユーザー・ロールは、ID ではなく次の表記で書きます。読み込むときに、そのブログの ID に読み替えます。
参照 | 表記 | 例 |
|---|---|---|
カテゴリー | ルートからのコードのパス |
|
ブログ | 先頭を |
|
ユーザー |
|
|
ロール | ロール名 |
|
参照型の選択範囲(scopeBlogId・scopeCategoryId・scopeParentCategoryId)も同じ表記で書きます。読み替えられない参照があると、その条件の組や設定を外し、フィールドセット・フィールドを無効(close)にして読み込みます。入力欄が意図せず広く出ないようにするためです。
テーマ由来の定義の扱い
テーマで宣言した定義は、定義画面で「テーマ」の印付きで並び、編集できません。定義元のファイルのパスも表示されます。
管理画面で同じキーの定義を作ると、管理画面の定義が優先されます。同じコードのフィールドセットは 1 つにまとめ、フィールドセットの設定(ラベル・有効・表示する場所・表示条件)は管理画面のものを使います。
このブログでだけ使いたくない定義は、カードの「「(ラベル)」をこのブログでは使わない」で止められます。戻すときは「「(ラベル)」をこのブログで使う」を押します。テーマのファイルは書き換えません。
並び順は、テーマだけのフィールドセット(書いた順)、管理画面で作ったフィールドセットの順です。フィールドは、テーマ由来(書いた順)の後に管理画面の定義が並びます。
sortを書くと、管理画面の定義と数値で並びます。
子孫のブログへの継承
管理画面でフィールドセットの「子孫のブログにも継承する」をオンにすると、子孫のブログの編集画面にも出ます。
継承した定義は、子孫のブログでは「親ブログ」の印付きで並び、編集できません。フィールドごとに「使わない」にできます。
同じキーが複数の祖先にあるときは、近い祖先の定義を使います。
有効なフィールドセットの、有効な定義だけを継承します。
優先順位は、そのブログで作った定義 → テーマ由来の定義 → 継承した定義の順です。
テーマの宣言は継承しません
継承するのは、管理画面で作ったフィールドセットだけです。テーマの JSON に "scope": "global" を書いても、子孫のブログには継承されません。子孫のブログでも使うときは、子孫のブログのテーマにも同じ宣言を置きます。
宣言を作る手順
手で書くより、管理画面で作ってエクスポートするほうが確実です。
検証環境の管理画面でフィールドセットとフィールドを作り、編集画面で動きを確かめます。
定義画面の一覧からフィールドセットをエクスポートします。ダウンロードしたファイル(
field-definitions-<対象>.jsonなど)の名前を<対象>.json(例:entry.json)に変え、themes/<テーマ>/admin/field-definitions/に置きます。複数のフィールドセットを 1 つのファイルにまとめるときは、setsの配列に並べます。別のブログ(またはサイト)でそのテーマを使い、編集画面に出ることを確かめます。
検証に使ったブログの、管理画面で作った定義は削除します(同じキーの定義が残ると、管理画面の定義が優先されます)。
手で書き換えたときは、監査ログに定義の読み込みの警告が出ていないかも確かめてください。