プラグインからの拡張
この機能は Ver. 3.3.0 で追加予定の、リリース前の機能です
このページは、アルファ版(Ver. 3.3.0-alpha.1)時点の内容です。正式版までに仕様や設定項目が変わる可能性があります。本番サイトでは使わず、検証環境でお試しください。
カスタムフィールド定義は、コアを改修せずに、プラグインから型や場所を足せます。登録は、プラグインの ServiceProvider::init() で、ファサード Acms\Services\Facades\FieldDefinition を使って行います。公開している拡張の入口は、雛形の Hook(extension/acms/Hook.php)と、管理画面の JS の拡張点の一覧(@ablogcms/plugins の HOOKS.md)に載っているものです。
登録の例
カレンダーの型・表示する場所・表示条件の項目・パターンを登録する ServiceProvider です。
<?php
namespace Acms\Plugins\MyCalendar;
use ACMS_App;
use Acms\Services\Common\HookFactory;
use Acms\Services\Facades\FieldDefinition;
use Acms\Services\Facades\Twig;
class ServiceProvider extends ACMS_App
{
public $version = '1.0.0';
public $name = 'MyCalendar';
public $author = 'example';
public $module = false;
public $menu = false;
public $desc = 'カレンダーのフィールド型';
public function init()
{
HookFactory::singleton()->attach('MyCalendarHook', new Hook());
// .twig をプラグインのディレクトリから読むために登録する(@mycalendar/... で参照できる)
Twig::addTemplatePath(PLUGIN_LIB_DIR . 'MyCalendar/template', 'mycalendar');
FieldDefinition::registerFieldType('mycalendar.date', [
'label' => 'カレンダー',
'template' => '@mycalendar/field-types/calendar.twig',
'icon' => 'calendar_month',
'configFields' => [
['key' => 'format', 'label' => '日付フォーマット', 'type' => 'text', 'default' => 'Y-m-d'],
],
'validators' => ['regex'],
]);
FieldDefinition::registerPlacement('entry', 'mycalendar-schedule', '日程', '日付の入力向けです。');
FieldDefinition::registerLocationSubject('mycalendar.season', [
'label' => '季節',
'entityTypes' => ['entry'],
'kind' => 'enum',
'options' => [
['value' => 'summer', 'label' => '夏'],
['value' => 'winter', 'label' => '冬'],
],
'provider' => static function (string $entityType, int $blogId, ?int $userId, array $values): string {
$month = (int) date('n');
return ($month >= 6 && $month <= 9) ? 'summer' : 'winter';
},
]);
FieldDefinition::registerPatternDirectory(PLUGIN_LIB_DIR . 'MyCalendar/patterns');
}
}{# extension/plugins/MyCalendar/template/field-types/calendar.twig #}
<input type="text" name="{{ name }}" value="{{ values[0] ?? '' }}"
class="js-mycalendar" data-format="{{ definition.config.format ?? 'Y-m-d' }}">独自のフィールド型を登録する
FieldDefinition::registerFieldType(string $key, array $options): void で型を登録します。
オプション | 必須 | 内容 | 既定値 |
|---|---|---|---|
| 必須 | 型を選ぶ画面の名前。 | — |
| 必須 | 入力欄のテンプレート。 | — |
| アイコン名。 | 空 | |
| 型ごとの設定の欄( | なし | |
| 入力チェックで選べる項目のメソッド名。 | なし | |
|
|
| |
| 使える対象の配列。 | すべて | |
| 分類。 |
| |
| 値の処理をコアのカスタムフィールドの保存処理に頼るか。 |
| |
| 設定にカテゴリー・ブログ・ユーザー・ロールの ID を持つとき、設定のキーと種類( | なし |
キーは
vendor.typeの形を勧めます(64 文字以内)。コアの型のキーは使えず、例外になります。同じキーの型がテーマにもあると、テーマの型が優先されます。
templateに文字列のパスを書くと、.twig以外はテーマの中だけを探します。プラグインのディレクトリのテンプレートを使うときは、Twig::addTemplatePath()で登録した.twigか、関数にします。テンプレートや関数には
definition(定義)・name(値の入力の name)・values(保存済みの値の配列)が渡ります。値の入力はnameだけで書き、field[]・:v#は書きません。
出力は必ずエスケープしてください
テンプレートや関数の出力は、そのまま編集画面に入ります。Twig では |raw を使わないでください。保存済みの値から XSS になります。
場所・表示条件・定義・パターンを足す
メソッド | 内容 |
|---|---|
| フィールドセットの「表示する場所」の選択肢を足します。編集画面のテンプレートに |
| フィールドセットの表示条件に項目を足します。名前は |
| ディレクトリに置いた |
| ディレクトリに置いたパターンの JSON を「パターン」に並べます。テーマのパターンの後、標準のパターンの前に並びます。 |
registerLocationSubject() のオプションです。
オプション | 必須 | 内容 | 既定値 |
|---|---|---|---|
| 必須 | 値を返す関数( | — |
| 表示条件の選択肢に出す名前。 | 名前 | |
|
|
| |
|
|
| |
| 使える条件。 | kind のすべて | |
|
|
| — |
ファイルの形は、テーマと同じです(テーマでフィールド定義を宣言する、テーマでパターン・独自の型・表示する場所を足す)。
Hook
雛形の Hook にある、カスタムフィールド定義の拡張点です。プラグインでは HookFactory::singleton()->attach() で Hook のクラスを登録します。
Hook | いつ呼ばれるか |
|---|---|
| 有効なフィールドセットを編集画面へ渡す前。保存時のチェックと、公開側の参照切れの判定にも同じ加工が効きます。 |
| 保存時、値を保存する定義のキーごと(必須・入力チェックの前)。値の整形や、派生キーを作るときに使います。 |
| 権限・ロール別の表示を決めた後。 |
| 選べる型を決めるとき。 |
| テーマの宣言ファイルを読んだ後。 |
| 親ブログから継承する定義を決めた後。 |
| キーを変更した後。 |
| 参照の型で、選択肢の一覧を作るとき。条件を足して候補を絞れます(アクセス制御には使えません)。 |
| 公開側で、存在しない参照先を出すとき。 |
| 定義の変更をキーワード検索に反映する前・対象ごと・後。 |
| 定義をエクスポートするとき。 |
| 定義をインポートするとき。例外を投げると取り込みません。 |
| インポートで、ロールの参照を読み替えるとき。 |
<?php
namespace Acms\Plugins\MyCalendar;
class Hook
{
/**
* 保存時に、値を保存する定義のキーごとに呼ばれる
*/
public function extendsFieldDefinitionValue(\Field_Validation $field, string $key, array $definition): void
{
if (($definition['type'] ?? '') !== 'mycalendar.date') {
return;
}
$field->set($key, str_replace('/', '-', (string) $field->get($key)));
}
/**
* 選べる型を決めるときに呼ばれる。ユーザーの定義ではブロックエディターを選べなくする
*/
public function extendsFieldTypePolicy(array &$policy, string $entityType, int $blogId): void
{
if ($entityType === 'user') {
$policy['deny'][] = 'block-editor';
}
}
}引数の詳細と例は、雛形の Hook のコメントを参照してください。
管理画面の JS イベント
ACMS.events で購読します。
イベント | 種類 | 内容 |
|---|---|---|
| 通知 | テンプレートの型の入力欄を DOM に入れた直後(要素につき 1 回)。payload は |
| 通知 | 入力欄を DOM から外す直前。描き直すときは remove → rendered の順で発火します。rendered で付けたものをここで片付けます。 |
| 通知 | JS から編集画面の値を書き換える口。 |
| ゲート | 項目のラベルを書き換えます。payload は |
| 通知 | 編集画面を開いたときの、権限・ロール別の表示の結果(制限のあるキーだけ)。 |
| 通知 | 定義をインポートした後。 |
| 通知 | 検索対象の変更をキーワード検索に反映した結果。 |
| 通知 | テーマ・継承の定義を「使わない/使う」に切り替えた後。 |
| 通知 | キーを変更した後。 |
const mounted = new WeakMap();
ACMS.events.on('field-definition.field.rendered', ({ element, definition }) => {
if (definition.type !== 'mycalendar.date') {
return;
}
const input = element.querySelector('.js-mycalendar');
// input にカレンダーを付け、片付けの関数を覚えておく
mounted.set(element, () => {
// カレンダーを外す
});
});
ACMS.events.on('field-definition.field.remove', ({ element }) => {
mounted.get(element)?.();
mounted.delete(element);
});JS の読み込みは、InjectTemplate::add() で管理画面に <script type="module"> を差し込む形で行います。
実験的な API
次の API は experimental です。公開 API として固まっておらず、変わる可能性があります。
FieldDefinition::registerEntityType(string $name, array $options = []): コメント・フォームなどのプラグインが、自分の持ち主(対象)に定義を使うための登録。値はプラグインが自前のテーブルに保存します。FieldDefinition::validateValues(string $entityType, int $blogId, \Field_Validation $values, string $status = 'open', ...)とFieldDefinition::validateValuesWithSets(...): 定義で値を確かめ、結果を返します。管理画面の定義画面の部品(
@ablogcms/field-definition)