従来のカスタムフィールドとの併用と移行


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

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

併用の基本

  • 従来のテンプレートのカスタムフィールドは、そのまま動きます。定義の無いキーは、従来どおり確かめずに保存されます。

  • カスタムフィールド定義の入力欄は、テンプレートの入力欄の後ろに出ます(エントリーは本文の上)。

  • 定義の入力欄は、編集画面のフォームの中で acms_cf[キー] という名前で送られ、サーバーで元のキーに戻して保存されます。テーマの入力欄に acms_cf という name は使わないでください。

  • 保存される値の形は同じなので、公開側のテンプレートは方式によらず同じです。

同じキーをテンプレートと定義の両方に書いたとき

  • テーマのテンプレートが field[] で宣言しているキーがあると、編集画面はそのキーの定義の入力欄を出しません。保存もテンプレート側の値が優先されます(定義の側の値は保存されず、警告ログが残ります)。

  • フィールドグループも同じです。テーマに同じ名前のグループ(@グループ名)があると、定義の側は器ごと出しません。

  • ただし、定義で必須や入力チェックを設定したキーは、テンプレートの入力欄から送られた値にもサーバーで同じチェックが掛かります(定義もフィールドセットも有効で、条件で隠れていないとき)。

  • 定義のあるキーをテンプレートの入力欄で送るときも、従来どおり field[] の宣言が必要です。宣言が無く値だけを送ると、送られなかったものとして扱われ、保存済みの値に戻ります。

従来のフィールドを定義へ移す手順

テキスト・選択肢・日付など、派生キーを持たないフィールドを移す手順です。

  • 検証環境で作業し、移す前にデータベースのバックアップを取ります。

  • フィールドセットの編集画面の「使用中のフィールド」で「集計」すると、値はあるのに定義の無いキーが件数付きで並びます。移すキーを「定義に追加」し、テンプレートの入力欄と同じ型(<input type="text"> ならテキスト、name="キー[]" のチェックボックスなら複数選択のチェックボックス)を選びます。

  • ラベル・選択肢・必須・入力チェックを、テンプレートの入力欄(:v# の指定など)に合わせて設定します。選択肢の値は、テンプレートの value と同じにします。

  • テーマの field.html などから、そのキーの入力欄・field[] の宣言・:search・:v# の hidden をまとめて削除します(残っていると、定義の入力欄は出ません)。

  • 編集画面で、定義の入力欄に保存済みの値が入っていることを確かめてから保存し、公開側のテンプレートは変えずに、表示が変わらないことを確かめます。

フィールドグループ(@グループ名)は「使用中のフィールド」に出ません。型「フィールドグループ」を、キーをグループ名と同じにして作り、中にメンバーと同じキーのフィールドを作ってから、テーマの入力欄を削除します。

画像・ファイルのフィールドは移せません

テンプレートで作った画像・ファイルのフィールド(@path などの派生キーを持つもの)は、「テンプレート方式のフィールド(GUI 定義では扱えません)」の印が付き、定義に追加できません。テンプレート方式のまま使い続けてください。

同じキーでメディア画像の型を作ると、@path などの値はメディアの情報に置き換わり、元の画像は使われなくなります。メディアに移すときは、メディアライブラリに画像を登録して選び直します。

管理画面のテンプレートを上書きしているテーマ

システムテーマの編集画面には、定義の入力欄を出す次のモジュールが入っています。テーマで編集画面のテンプレートを上書きしていると、入力欄が出ません。その場合は次の手順で追記します。

  1. テーマが上書きしているファイルを確かめます。エントリーは admin/entry/edit.html と admin/_layouts/entry/edit.html、カテゴリー・ブログ・ユーザー・モジュールは admin/category/edit.html などです。

  2. admin/entry/edit.html を @extends("/admin/_layouts/entry/edit.html") で書き、@section("entry-field") を上書きしていなければ、追記は要りません。

  3. それ以外の場合は、カスタムフィールドの入力欄(field.html の読み込み)の後ろ、<form> の内側に次を追記します。

  4. エントリーで「本文の下」「サイドバー」を使うときは、field_foot.html・field_side.html を読み込んでいる位置の後ろに差し込み口も足します。

  5. 有効なフィールドセットがあるブログで編集画面を開き、入力欄が出て保存できることを確かめます。

<!-- BEGIN_MODULE Admin_FieldDefinition_CustomFields -->
<acms-custom-fields entity-type="entry" definitions="{definitions}[escvars]" values="{values}[escvars]"></acms-custom-fields>
<!-- END_MODULE Admin_FieldDefinition_CustomFields -->
<!-- カテゴリーの例。id と entity-type に category / blog / user / module を書く -->
<!-- BEGIN_MODULE Admin_FieldDefinition_CustomFields id="category" -->
<acms-custom-fields entity-type="category" definitions="{definitions}[escvars]" values="{values}[escvars]"></acms-custom-fields>
<!-- END_MODULE Admin_FieldDefinition_CustomFields -->
<acms-custom-fields-slot placement="foot"></acms-custom-fields-slot>
<acms-custom-fields-slot placement="side"></acms-custom-fields-slot>

追記しないまま使わないでください

入力欄が出ていなくても、定義の必須・入力チェックは保存時に掛かります。上書きしたテーマで追記を忘れると、画面に無い必須の項目で保存できなくなります。

定義に無い値・定義の削除

  • 定義を削除したり無効にしたりしたフィールドの値は、編集画面で保存しても消えないよう、そのまま送り直されます(画面には出ません)。この送り直しは、編集画面に定義の入力欄が出ているときに働きます。

  • キー名に「:」や「[ ]」を含むなど、送り直せない値は、編集画面に「保存すると消える値」として一覧で出ます。

  • 「使用中のフィールド」の「値があるのに定義の無いフィールド」で、定義の無い値を確かめられます。

  • 定義やフィールドセットを削除しても、データベースに保存済みの値は削除されません。

キーを変更する

フィールドの設定フォームの「キーを変更」で、新しいキーを入力して影響(書き換える値の件数、自動では書き換わらないもの)を確かめてから実行します。実行後に、テンプレート・テーマに書いた {古いキー} を新しいキーに書き換えます。編集中の内容は破棄されます。

保存済みの値(派生キーを含む)と、ほかの定義の表示条件・等価チェックの参照は、新しいキーに書き換わります。テンプレート・テーマは書き換わりません。エントリーなどの編集画面を閉じてから実行してください。テーマ・親ブログ由来の定義は、キーを変更できません。

エクスポートとインポート

別のブログや環境へ定義を移すときに使います。

移す元の定義画面でフィールドセットをエクスポートし(テーマ由来の定義も含めるときは「テーマ由来の定義も含める」を選びます。通常は含めません)、移す先の定義画面の同じ対象のタブでインポートします。JSON ファイルを選ぶか貼り付けると、フィールドセットごとの状態(「新規」「衝突」「変更なし」など)が確認できます。同じコードのフィールドセットがあるときは、「上書きする」か「スキップする」を選びます。上書きは、ファイルにあるフィールドを追加・更新し、ファイルに無い既存のフィールドは残します。

  • カテゴリー・ブログ・ロールの参照は、ID ではなくコード・名前で書き出し、取り込み先の ID に読み替えます。

  • ファイルは 1MB までです。

  • ブログのエクスポート・インポート(バックアップ)にも、フィールド定義が含まれます。

  • 書き出した JSON は、テーマに置ける形式です(テーマでフィールド定義を宣言する)。