Editors Buttons (XTD) Plugin

This part describes how to develop an Editor XTD plugin.

The plugin works like following: The plugin register an Editor Button on onEditorButtonsSetup event, then system will use it depend on how the Editor field is configured in the form.

Events in this group:

onEditorButtonsSetup

onEditorButtonsSetup

The event triggered every time when the Editor is rendering.

Event signature:

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

Event attributes:

/** 
 * @var Joomla\CMS\Editor\Button\ButtonsRegistry $subject 
 * @var array    $disabledButtons  List of disabled button names
 * @var string   $editorType       Editor type
 * @var integer  $asset            Optional id of Asset, for access check
 * @var integer  $author           Optional id of Author, for access check
 */
$subject    = $event->getButtonsRegistry();
$disabled   = $event->getDisabledButtons();
$editorType = $event->getEditorType();
$asset      = $event->getAsset();
$author     = $event->getAuthor();

Creating an editor button (xtd) plugin

Following example assume you already know how to create Joomla plugin.

In the example we create a two button which insert 🍺 and 🐈 in to editor. First button will use predefined insert action, and second will use our custom action that doing the same.

For start create a plugin under plugins/editors-xtd/example/ folder, call it example, assume namespace is JoomlaExample\Plugin\EditorsXtd\Example.

Then set up buttons in onEditorButtonsSetup event handler.

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
{
    /**
     * Returns an array of events this subscriber will listen to.
     *
     * @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();

        if (!\in_array('example-beer', $disabled)) {
            $button1 = new Button('example-beer', [
                'text' => 'Insert 🍺'
                'icon' => 'file-add',
                'action' => 'insert', // Action already provided by Joomla.EditorButton
            ], [
                'content' => '🍺', // Content to insert
            ]);
            
            $subject->add($button1);
        }
        
        if (!\in_array('example-cat', $disabled)) {
            // Register script with our custom action
            $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'   => 'Insert 🐈'
                'icon'   => 'file-add',
                'action' => 'insert-cat', // Custom action, will code it later
            ]);
            
            $subject->add($button2);
        }
    }
}

Now create a JavaScript to make insert-cat action to work. Create a JavaScript file under media/plg_editors_xtd_example/js/example-cat.js, and register handler for insert-cat action in JoomlaEditorButton

// Import required components
import { JoomlaEditorButton } from 'editor-api';

// Insert 🐈 on cursor
JoomlaEditorButton.registerAction('insert-cat', (editor, options) => {
  editor.replaceSelection('🐈');
});

And all done 🎉 After plugin installation and enabling, the buttons should be available and do its job.