プラグインからの拡張


この機能は 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 で型を登録します。

オプション

必須

内容

既定値

label

必須

型を選ぶ画面の名前。

—

template

必須

入力欄のテンプレート。.twig のパス、テーマの中の標準のテンプレートのパス、または HTML を返す関数(function (array $context): string)。

—

icon

アイコン名。

空

configFields

型ごとの設定の欄(key・label・type・description・default)。

なし

validators

入力チェックで選べる項目のメソッド名。required・password・filesize・converter・duplication は書いても選べません。

なし

edition

standard か professional。

standard

entityTypes

使える対象の配列。

すべて

category

分類。@ で始まる名前。

@custom

requiresFieldStorage

値の処理をコアのカスタムフィールドの保存処理に頼るか。

false

configReferences

設定にカテゴリー・ブログ・ユーザー・ロールの ID を持つとき、設定のキーと種類(category・blog・user・role)。エクスポートやブログのインポートで読み替えます。

なし

  • キーは vendor.type の形を勧めます(64 文字以内)。コアの型のキーは使えず、例外になります。

  • 同じキーの型がテーマにもあると、テーマの型が優先されます。

  • template に文字列のパスを書くと、.twig 以外はテーマの中だけを探します。プラグインのディレクトリのテンプレートを使うときは、Twig::addTemplatePath() で登録した .twig か、関数にします。

  • テンプレートや関数には definition(定義)・name(値の入力の name)・values(保存済みの値の配列)が渡ります。値の入力は name だけで書き、field[]・:v# は書きません。

出力は必ずエスケープしてください

テンプレートや関数の出力は、そのまま編集画面に入ります。Twig では |raw を使わないでください。保存済みの値から XSS になります。

場所・表示条件・定義・パターンを足す

メソッド

内容

registerPlacement(string $entityType, string $name, string $label, ?string $hint = null): void

フィールドセットの「表示する場所」の選択肢を足します。編集画面のテンプレートに <acms-custom-fields-slot placement="名前"> を置きます。エントリーの main・foot・side はコアの名前のため使えません(例外になります)。

registerLocationSubject(string $name, array $options): void

フィールドセットの表示条件に項目を足します。名前は vendor.name の形です。

registerThemeDefinitionDirectory(string $directory): void

ディレクトリに置いた <対象>.json を、テーマの宣言と同じように読みます。テーマの宣言より優先度は低くなります。

registerPatternDirectory(string $directory): void

ディレクトリに置いたパターンの JSON を「パターン」に並べます。テーマのパターンの後、標準のパターンの前に並びます。

registerLocationSubject() のオプションです。

オプション

必須

内容

既定値

provider

必須

値を返す関数(Closure)。fn(string $entityType, int $blogId, ?int $userId, array $values): string。

—

label

表示条件の選択肢に出す名前。

名前

entityTypes

'all' か対象の配列。

'all'

kind

text か enum。

text

operators

使える条件。text は eq・neq・contains・matches・empty・notEmpty、enum は in・eq・neq の中から選びます。

kind のすべて

options

enum のとき必須

value と label の配列。

—

ファイルの形は、テーマと同じです(テーマでフィールド定義を宣言する、テーマでパターン・独自の型・表示する場所を足す)。

Hook

雛形の Hook にある、カスタムフィールド定義の拡張点です。プラグインでは HookFactory::singleton()->attach() で Hook のクラスを登録します。

Hook

いつ呼ばれるか

extendsFieldDefinitions(array &$sets, string $entityType)

有効なフィールドセットを編集画面へ渡す前。保存時のチェックと、公開側の参照切れの判定にも同じ加工が効きます。

extendsFieldDefinitionValue(\Field_Validation $field, string $key, array $definition)

保存時、値を保存する定義のキーごと(必須・入力チェックの前)。値の整形や、派生キーを作るときに使います。

extendsFieldVisibility(string &$level, array $definition, array $context)

権限・ロール別の表示を決めた後。$level は editable・readonly・hidden。

extendsFieldTypePolicy(array &$policy, string $entityType, int $blogId)

選べる型を決めるとき。allow / deny に型のキーか分類(@inputs・@choices・@media・@relations など)を書いて絞れます。エディションの制限は緩められません。

extendsThemeFieldDefinitions(array &$sets, string $entityType, string $file)

テーマの宣言ファイルを読んだ後。

extendsInheritedFieldDefinitions(array &$sets, string $entityType, int $blogId)

親ブログから継承する定義を決めた後。

extendsKeyRenamed(string $entityType, int $blogId, string $oldKey, string $newKey, int $rows)

キーを変更した後。

extendsRelationPickerQuery(\SQL_Select $sql, string $type, array $scope)

参照の型で、選択肢の一覧を作るとき。条件を足して候補を絞れます(アクセス制御には使えません)。

extendsRelationBrokenReference(?string &$replacement, string $type, string $key, string $value, string $entityType, int $blogId)

公開側で、存在しない参照先を出すとき。

extendsFieldDefinitionSearchReindexBefore / extendsFieldDefinitionSearchReindex / extendsFieldDefinitionSearchReindexAfter

定義の変更をキーワード検索に反映する前・対象ごと・後。

extendsFieldDefinitionExport(array &$profile, string $entityType, int $blogId)

定義をエクスポートするとき。

extendsFieldDefinitionImport(array &$profile, string $entityType, int $blogId)

定義をインポートするとき。例外を投げると取り込みません。

extendsFieldDefinitionImportRoleId(?int &$roleId, string $original, array $context)

インポートで、ロールの参照を読み替えるとき。

<?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 で購読します。

イベント

種類

内容

field-definition.field.rendered

通知

テンプレートの型の入力欄を DOM に入れた直後(要素につき 1 回)。payload は { element, definition, name }。

field-definition.field.remove

通知

入力欄を DOM から外す直前。描き直すときは remove → rendered の順で発火します。rendered で付けたものをここで片付けます。

field-definition.value.set

通知

JS から編集画面の値を書き換える口。ACMS.events.notify('field-definition.value.set', { entityType, key, values }) と呼びます。読み取り専用・非表示のキー、フィールドグループのメンバーは書き換えません。

field-definition.label.before

ゲート

項目のラベルを書き換えます。payload は { locale, labels }。

field-definition.visibility.after

通知

編集画面を開いたときの、権限・ロール別の表示の結果(制限のあるキーだけ)。

field-definition.import.success

通知

定義をインポートした後。

field-definition.search-reindex.after

通知

検索対象の変更をキーワード検索に反映した結果。

field-definition.suppress.change

通知

テーマ・継承の定義を「使わない/使う」に切り替えた後。

field-definition.key.change

通知

キーを変更した後。

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)