オリジナルユニットを作る

エントリー本文に、独自の編集画面と保存データを持つユニット（オリジナルユニット）を追加します。

対応バージョン: Ver. 3.2.38 以降

カスタムユニットとオリジナルユニット

a-blog cms には、もともとカスタムユニットという標準の機能があります。このページで作るオリジナルユニットとは別のものです。

まずカスタムユニットで足りないかを検討してください。 カスタムユニットなら PHP の実装が不要で、運用も簡単です。入力欄の組み合わせで足りない場合に、オリジナルユニットを作ります。

標準のカスタムユニットの編集画面そのものを JavaScript で差し替えることもできますが、その差し替えはすべてのカスタムユニットに適用されます。特定のカスタムユニットだけを差し替えることはできないため、個別の編集画面が必要な場合は、オリジナルユニットを作ってください。

作業のチェックリスト

オリジナルユニットは、次の5つが揃わないと動きません。どれか1つでも欠けると、保存できない・表示されない・データが消えるといった状態になります。

• JavaScript で編集画面を登録する
• PHP でユニットを登録する
• 編集設定でユニットメニューに追加する
• ユニット設定で、メニューにユニットを割り当てる
• テーマにユニットの表示テンプレートを書く

JavaScript で編集画面を登録する

次の例は、文字列を1つ入力できる「グラフ」ユニットの編集画面です。入力欄の name は、ユニットの種類名_項目名_ユニットID の形にします。PHP 側の保存処理がこの名前で値を受け取ります。

ACMS.adminReady(() => {
  const { createElement } = ACMS.Library.React;

  function ChartEdit({ editor, unit }) {
    return createElement(
      'div',
      { className: 'acms-admin-unit-content' },
      createElement('input', {
        type: 'text',
        name: `my-chart_value_${unit.id}`,
        className: 'acms-admin-form-width-full',
        'aria-label': 'グラフの値（カンマ区切りの数値）',
        placeholder: '10,20,30',
        value: unit.attributes.value ?? '',
        onChange: (event) => editor.commands.setUnitAttributes(unit.id, { value: event.target.value }),
      }),
      createElement(
        'button',
        { type: 'button', className: 'acms-admin-btn', onClick: () => editor.commands.moveUpUnit(unit.id) },
        '上へ'
      ),
      createElement(
        'button',
        { type: 'button', className: 'acms-admin-btn', onClick: () => editor.commands.moveDownUnit(unit.id) },
        '下へ'
      ),
      createElement(
        'button',
        { type: 'button', className: 'acms-admin-btn', onClick: () => editor.commands.removeUnit(unit.id) },
        '削除'
      )
    );
  }

  ACMS.plugins.register('acme-units', {
    setup(ctx) {
      ctx.unitEditor.registerUnitDefinition('my-chart', {
        type: 'my-chart',
        name: 'グラフ',
        icon: 'bar_chart',
        edit: ChartEdit,
        supports: {
          multiple: true,
          nested: true,
        },
      });
    },
  });
});

edit に渡されるのは、unit（このユニットのデータ）と editor（ユニットエディター）などです。unit.attributes が、PHP 側の getAttributes() で返した値です。editor.commands で、データの更新・移動・削除などの操作ができます。

この例では、ユニットの移動と削除のボタンを自分で用意しています。標準のユニットが持つツールバーは、オリジナルユニットでは自動では付きません。

この登録だけで、エントリー編集・ダイレクト編集・編集設定の3つの画面すべてに反映されます。

PHP でユニットを登録する

保存・読み込み・サイト表示側の出力を担当するクラスを登録します。プラグインの ServiceProvider の init() に、次のように書きます。

use Acms\Services\Facades\Application;
use Acms\Services\Unit\Registry;

Application::bootstrap('unit-registry', function (Registry $registry) {
    $registry->bind('my-chart', \Acms\Plugins\AcmeUnits\Unit\MyChart::class);
});

登録するクラスは、Acms\Services\Unit\Contracts\Model を継承します。次の例は、JavaScript の例に対応する最小の実装です。

<?php

namespace Acms\Plugins\AcmeUnits\Unit;

use Acms\Services\Unit\Contracts\Model;
use Template;

/**
 * @extends \Acms\Services\Unit\Contracts\Model<array{value: string}>
 */
class MyChart extends Model
{
    /**
     * @var array{value: string}
     */
    private $attributes = ['value' => ''];

    public static function getUnitType(): string
    {
        return 'my-chart';
    }

    public static function getUnitLabel(): string
    {
        return 'グラフ';
    }

    public function getAttributes()
    {
        return ['value' => $this->getField1()];
    }

    public function setAttributes($attributes): void
    {
        $this->attributes = $attributes;
    }

    public function setDefault(string $configKeyPrefix, int $configIndex): void
    {
        $this->setField1(config("{$configKeyPrefix}field_1", '', $configIndex));
    }

    public function extract(array $request): void
    {
        $id = $this->getId();
        if (is_null($id)) {
            throw new \LogicException('Unit ID must be set before calling extract');
        }
        $value = $request["my-chart_value_{$id}"] ?? '';
        $this->setField1(is_string($value) ? $value : '');
    }

    public function canSave(): bool
    {
        return $this->getField1() !== '';
    }

    public function handleDuplicate(): void
    {
    }

    public function handleRemove(): void
    {
    }

    public function getSearchText(): string
    {
        return $this->getField1();
    }

    public function getSummaryText(): array
    {
        return [$this->getField1()];
    }

    public function render(Template $tpl, array $vars, array $rootBlock): void
    {
        if ($this->getField1() === '') {
            return;
        }
        $vars += ['value' => $this->getField1()];
        $tpl->add(array_merge(['unit#' . $this->getType()], $rootBlock), $vars);
    }

    public function renderEdit(Template $tpl, array $vars, array $rootBlock): void
    {
    }

    protected function getLegacy(): array
    {
        return ['value' => $this->getField1()];
    }
}

値は、ユニットが共通で持つ field1 に保存しています。getUnitType() が返す種類名は、bind() に渡した名前と同じにします。getUnitLabel() の値は、編集設定の入力候補やユニットメニューでの名前に使われます。

Application::bootstrap() に渡すコールバックは、unit-registry が使われるたびに実行されます。bind() のように何度実行しても同じ結果になる処理だけを書いてください（カウントアップや外部通信は書かないでください）。

編集設定でユニットメニューに追加する

1. 管理画面の「編集設定」→「ユニットメニュー」を開きます。編集画面セットを使っているサイトでは、使っているセットの「編集設定」を開きます。
2. 「モード」の入力欄に種類名（例: my-chart）を入力します。PHP に登録済みの種類は入力候補として表示されます。 「ラベル」「アイコン」も必要に応じて入力します。
3. 保存します。

PHP 側の追加実装は必要ありません。 入力候補は登録済みのユニットから自動的に作られます。

ユニット設定で、メニューにユニットを割り当てる

メニューの項目を追加しただけでは、エントリー編集画面のユニットメニューに出ません。どのユニットを追加する項目なのかを、「ユニット設定」で指定します。

1. 管理画面の「編集設定」の隣にある「ユニット設定」を開きます（編集画面セットを使っているサイトでは、同じセットのもの）。
2. 追加した項目（例: 「グラフ」）の欄に、ユニットの種類のボタンが並びます。「グラフ」のボタンを押して、ユニットを1つ追加します。
3. 保存します。

保存すると、エントリー編集画面の「ユニットを追加」に、「グラフ」が出ます。

テーマに表示テンプレートを書く

サイトに表示するときの HTML は、テーマのテンプレートに書きます。テーマの include/unit/extend.html に、unit#種類名 のブロックを追加します。render() で渡した値が、ブロックの中の変数になります。

<div class="my-chart" data-values="{value}">{value}</div>

テンプレートに書かれていない種類のユニットは、サイトに何も表示されません。

ツールバーにボタンを追加する

標準のツールバーを使うユニット（標準のユニットなど）には、UI の差し込み（Slot / Fill）でボタンを追加できます。次の例は、ツールバーに「ID をコピー」ボタンを追加します。

ACMS.adminReady(() => {
  const { createElement } = ACMS.Library.React;
  const { withFillProps } = ACMS.plugins;

  ACMS.plugins.register('acme-unit-toolbar', {
    setup(ctx) {
      ctx.ui.fill(
        'unit-editor.unit-toolbar',
        withFillProps(({ unit }) =>
          createElement(
            'button',
            {
              type: 'button',
              className: 'acms-admin-btn',
              onClick: () => navigator.clipboard.writeText(unit.id),
            },
            'ID をコピー'
          )
        )
      );
    },
  });
});

→ UI の差し込み（Slot / Fill）

関連ページ

• ユニット — ユニットの基本
• 機能の登録（レジストリ）
• 開発環境と型定義 — React・TypeScript で書く場合

変更履歴