テーマでフィールド定義を宣言する


この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です

このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。

テーマにフィールド定義の JSON ファイルを置くと、そのテーマを使うブログで、管理画面で作った定義と同じように編集画面に出ます。テンプレートと一緒に定義もファイルで持ち運べるため、案件をまたいでフィールドを使い回せます。

置き場所と読み込まれる条件

対象

ファイル

エントリー

themes/<テーマ>/admin/field-definitions/entry.json

カテゴリー

themes/<テーマ>/admin/field-definitions/category.json

ブログ

themes/<テーマ>/admin/field-definitions/blog.json

ユーザー

themes/<テーマ>/admin/field-definitions/user.json

モジュール

themes/<テーマ>/admin/field-definitions/module.json

コンポーネント

themes/<テーマ>/admin/field-definitions/component.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% の幅で横に並べます。「開催日」は公開時に必須です。

  • 「種類」がセミナーのときだけ「定員」を出します。

  • 「社内メモ」は、管理者と編集者だけに出し、ほかの人には出しません。キーワード検索の対象にしません。

トップレベルとフィールドセットのキー

キー

必須

型

既定値

内容

version

必須

数値

—

1 を書きます。

entityType

必須

文字列

—

ファイル名と同じ対象(entry など)。

sets

必須

配列

—

フィールドセットの配列。

フィールドセットのキー

必須

型

既定値

内容

code

必須

文字列

—

半角英数字とアンダースコアの 64 文字以内。

label

必須

文字列

—

ラベル。

description

文字列

""

説明。

status

文字列

"open"

"open"(有効)か "close"(無効)。

layout

オブジェクト

null(標準の位置)

{"placement": "場所の名前"}。場所の名前は main・foot・side など。

conditions

オブジェクト

null(常に出す)

表示条件(後述)。

fields

配列

[]

フィールドの配列。

scope

文字列

—

"local" か "global"。テーマの宣言では使われません(後述)。

フィールドのキー

キー

必須

型

既定値

内容

key

必須

文字列

—

テンプレートのキー。半角英字かアンダースコアで始まる、半角英数字とアンダースコアの 64 文字以内。

label

必須

文字列

—

ラベル。

type

必須

文字列

—

型のキー(text・select・group など)。

labels

オブジェクト

なし

ロケールごとのラベル({"en": "Date"})。管理画面の言語に合わせて出します。管理画面では編集できません。

description

文字列

""

説明。

status

文字列

"open"

"open" か "close"。

parentKey

文字列

null

入れる箱・フィールドグループ・ブロックのキー。

search

真偽値

true

キーワード検索の対象にするか。

config

オブジェクト

{}

型ごとの設定と、共通の設定(後述)。

validation

オブジェクト

任意・チェックなし

required("none"・"save"・"publish")と rules(method・arg・message の配列)。arg は文字列で書きます。

conditions

オブジェクト

null

条件付き表示(後述)。

sort

整数

なし

テーマの宣言だけで使えます。管理画面で作った定義との並び順を数値で決めます。

共通の設定の config のキーは次のとおりです。型ごとの設定のキーは「入力の型の設定(文字・選択・日付・数値)」「メディア・参照・地図・アップロード・ブロックエディターの型の設定」「レイアウトの型(見出し・メッセージ・行・タブ・アコーディオン)」「フィールドグループ(繰り返し)」の表を参照してください。

config のキー

型

内容

例

width

整数

列幅(25・33・50・66・75・100)。ほかの値は 100 になります。

50

defaultValue

文字列

初期値。

"seminar"

tooltip

文字列

補足(ツールチップ)。

"半角で入力します"

inputWidth

文字列

入力欄の長さ(mini・small・medium・large・full)。

"small"

clearOnHide

真偽値

条件付き表示で隠れているときは値を保存しない。

true

visibility

オブジェクト

権限・ロール別の表示。default(指定のないユーザー)、byAuth(editor・contributor・subscriber)、byRole(ロール名)に editable・readonly・hidden を書きます。

{"default": "readonly"}

条件と参照の書き方

表示条件・条件付き表示は、どちらも {"or": [ {"and": [ 条件, … ]}, … ]} の形で書きます。and の中をすべて満たすか、or のどれかの組を満たすときに出します。

条件のキー

内容

subject

表示条件で使う項目の名前(category・blog など。一覧は フィールドセットの作成と設定)。フィールドセットの conditions で使います。

field

条件付き表示で比べるフィールドのキー。フィールドの conditions で使います。

operator

eq・neq・in・contains・empty・notEmpty・gt・lt・matches。

value

比べる値。in では配列にします。empty・notEmpty では書きません。

axis

"self"(そのもの)か "descendant-or-self"(それと配下すべて)。カテゴリー・ブログなど階層のある項目だけに書けます。

カテゴリー・ブログ・ユーザー・ロールは、ID ではなく次の表記で書きます。読み込むときに、そのブログの ID に読み替えます。

参照

表記

例

カテゴリー

ルートからのコードのパス

news、news/press

ブログ

先頭を / にしたコードのパス

/(ルートブログ)、/news

ユーザー

ブログのパス:ユーザーコード

/news:taro

ロール

ロール名

編集担当

参照型の選択範囲(scopeBlogId・scopeCategoryId・scopeParentCategoryId)も同じ表記で書きます。読み替えられない参照があると、その条件の組や設定を外し、フィールドセット・フィールドを無効(close)にして読み込みます。入力欄が意図せず広く出ないようにするためです。

テーマ由来の定義の扱い

  • テーマで宣言した定義は、定義画面で「テーマ」の印付きで並び、編集できません。定義元のファイルのパスも表示されます。

  • 管理画面で同じキーの定義を作ると、管理画面の定義が優先されます。同じコードのフィールドセットは 1 つにまとめ、フィールドセットの設定(ラベル・有効・表示する場所・表示条件)は管理画面のものを使います。

  • このブログでだけ使いたくない定義は、カードの「「(ラベル)」をこのブログでは使わない」で止められます。戻すときは「「(ラベル)」をこのブログで使う」を押します。テーマのファイルは書き換えません。

  • 並び順は、テーマだけのフィールドセット(書いた順)、管理画面で作ったフィールドセットの順です。フィールドは、テーマ由来(書いた順)の後に管理画面の定義が並びます。sort を書くと、管理画面の定義と数値で並びます。

子孫のブログへの継承

管理画面でフィールドセットの「子孫のブログにも継承する」をオンにすると、子孫のブログの編集画面にも出ます。

  • 継承した定義は、子孫のブログでは「親ブログ」の印付きで並び、編集できません。フィールドごとに「使わない」にできます。

  • 同じキーが複数の祖先にあるときは、近い祖先の定義を使います。

  • 有効なフィールドセットの、有効な定義だけを継承します。

  • 優先順位は、そのブログで作った定義 → テーマ由来の定義 → 継承した定義の順です。

テーマの宣言は継承しません

継承するのは、管理画面で作ったフィールドセットだけです。テーマの JSON に "scope": "global" を書いても、子孫のブログには継承されません。子孫のブログでも使うときは、子孫のブログのテーマにも同じ宣言を置きます。

宣言を作る手順

手で書くより、管理画面で作ってエクスポートするほうが確実です。

  • 検証環境の管理画面でフィールドセットとフィールドを作り、編集画面で動きを確かめます。

  • 定義画面の一覧からフィールドセットをエクスポートします。ダウンロードしたファイル(field-definitions-<対象>.json など)の名前を <対象>.json(例: entry.json)に変え、themes/<テーマ>/admin/field-definitions/ に置きます。複数のフィールドセットを 1 つのファイルにまとめるときは、sets の配列に並べます。

  • 別のブログ(またはサイト)でそのテーマを使い、編集画面に出ることを確かめます。

  • 検証に使ったブログの、管理画面で作った定義は削除します(同じキーの定義が残ると、管理画面の定義が優先されます)。

手で書き換えたときは、監査ログに定義の読み込みの警告が出ていないかも確かめてください。