پلاگین دکمه‌های ویرایشگر (XTD)

این بخش توضیح می‌دهد چگونه یک پلاگین دکمه‌های ویرایشگر (Editor XTD) توسعه بدهیم.

پلاگین به این صورت کار می‌کند: پلاگین یک دکمه ویرایشگر را در رویداد `onEditorButtonsSetup` ثبت می‌کند، سپس سیستم بسته به نحوه پیکربندی فیلد ویرایشگر در فرم از آن استفاده می‌کند.

رویدادهای این گروه:

onEditorButtonsSetup

این رویداد هر بار که ویرایشگر در حال رندر شدن است، اجرا می‌شود.

امضای رویداد:

function onEditorButtonsSetup(Joomla\CMS\Event\Editor\EditorButtonsSetupEvent $event){...}

ویژگی‌های رویداد:

/** 
 * @var Joomla\CMS\Editor\Button\ButtonsRegistry $subject 
 * @var array    $disabledButtons  لیست نام دکمه‌های غیرفعال
 * @var string   $editorType       نوع ویرایشگر
 * @var integer  $asset            شناسه اختیاری Asset برای بررسی دسترسی
 * @var integer  $author           شناسه اختیاری Author برای بررسی دسترسی
 */
$subject    = $event->getButtonsRegistry();
$disabled   = $event->getDisabledButtons();
$editorType = $event->getEditorType();
$asset      = $event->getAsset();
$author     = $event->getAuthor();

ساخت پلاگین دکمه ویرایشگر (XTD)

مثال زیر فرض می‌کند که شما قبلاً نحوه ساخت پلاگین جوملا را می‌دانید.

در این مثال، دو دکمه می‌سازیم که یکی 🍺 و دیگری 🐈 را در ویرایشگر وارد می‌کند. دکمه اول از عملیات درج تعریف‌شده استفاده می‌کند و دکمه دوم یک عملیات سفارشی است که همین کار را انجام می‌دهد.

برای شروع، یک پلاگین در مسیر `plugins/editors-xtd/example/` ایجاد کنید و نام آن را example بگذارید، فرض کنید namespace آن `JoomlaExample\Plugin\EditorsXtd\Example` باشد.

تنظیم دکمه‌ها در رویداد onEditorButtonsSetup

namespace JoomlaExample\Plugin\EditorsXtd\Example\Extension;

use Joomla\CMS\Editor\Button\Button;
use Joomla\CMS\Event\Editor\EditorButtonsSetupEvent;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;

final class Example extends CMSPlugin implements SubscriberInterface
{
    /**
     * بازگرداندن آرایه‌ای از رویدادهایی که این مشترک به آنها گوش می‌دهد
     *
     * @return array
     */
    public static function getSubscribedEvents(): array
    {
        return ['onEditorButtonsSetup' => 'onEditorButtonsSetup'];
    }
    
    /**
     * @param  EditorButtonsSetupEvent $event
     * @return void
     */
    public function onEditorButtonsSetup(EditorButtonsSetupEvent $event)
    {
        $subject  = $event->getButtonsRegistry();
        $disabled = $event->getDisabledButtons();

        // اگر دکمه example-beer غیرفعال نیست، آن را اضافه کن
        if (!\in_array('example-beer', $disabled)) {
            $button1 = new Button('example-beer', [
                'text' => 'درج 🍺',
                'icon' => 'file-add',
                'action' => 'insert', // عملیاتی که قبلاً توسط Joomla.EditorButton ارائه شده
            ], [
                'content' => '🍺', // محتوای قابل درج
            ]);
            
            $subject->add($button1);
        }
        
        // اگر دکمه example-cat غیرفعال نیست، آن را اضافه کن
        if (!\in_array('example-cat', $disabled)) {
            // ثبت اسکریپت برای عمل سفارشی
            $this->getApplication()->getDocument()->getWebAssetManager()
                ->registerScript(
                    'editor-button.example-cat',
                    'plg_editors_xtd_example/example-cat.js',
                    [],
                    ['type' => 'module'],
                    ['editors']
                );
            
            $button2 = new Button('example-cat', [
                'text'   => 'درج 🐈',
                'icon'   => 'file-add',
                'action' => 'insert-cat', // عمل سفارشی که بعداً کد می‌کنیم
            ]);
            
            $subject->add($button2);
        }
    }
}

ایجاد اسکریپت جاوااسکریپت برای عمل insert-cat

یک فایل جاوااسکریپت در مسیر `media/plg_editors_xtd_example/js/example-cat.js` ایجاد کنید و هندلری برای عمل `insert-cat` در `JoomlaEditorButton` ثبت کنید:

// وارد کردن مؤلفه‌های لازم
import { JoomlaEditorButton } from 'editor-api';

// درج 🐈 در مکان کرسر
JoomlaEditorButton.registerAction('insert-cat', (editor, options) => {
  editor.replaceSelection('🐈');
});

و تمام شد 🎉 پس از نصب و فعال‌سازی پلاگین، دکمه‌ها باید قابل دسترس باشند و عملکرد خود را انجام دهند.