Skip to main content
Version: 4.4

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:



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


if (!\in_array('example-cat', $disabled)) {
// Register script with our custom action
['type' => 'module'],

$button2 = new Button('example-cat', [
'text' => 'Insert 🐈'
'icon' => 'file-add',
'action' => 'insert-cat', // Custom action, will code it later


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) => {

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