Статья о том, как удобно расширить пользовательские возможности при редактировании или создании контента в Joomla. Для начала небольшое отступление, которое пригодится начинающим разработчикам или разработчикам, незнакомым с нутром Joomla. Если Вы опытный пользователь или разработчик - можете перейти сразу к разделу статьи Как добавить кнопку редактора в Joomla со своим функционалом?
Что такое плагин в Joomla?
В терминологии Joomla "плагин" - это расширение, которое предоставляет функции, связанные с событиями (Event Dispatching). В Joomla довольно много типов плагинов, используемых для решения самых разных задач. Возможности и функционал плагина зависит от времени и места вызываемого события, по которому он срабатывает: можно добавить некий кусочек HTML к статье, а можно отправить данные заказа по API в CRM систему, "прочесать" весь готовый HTML-код страницы регуляркой или добавить новые команды в Joomla CLI интерфейс.
Когда происходит вызов конкретного события, то происходит последовательное выполнение всех функций подключаемых плагинов, связанных с этим событием. События могут вызывать как ядро Joomla, так и компоненты, да и в принципе любые расширения Joomla. Для сравнения, в терминологии WordPress "плагин" - это то, что в Joomla чаще всего называется "компонент".
Плагины группы Editors-Xtd или плагины кнопок редактора
Данный раздел нужен для новичков или не знакомых с Joomla разработчиков. Поэтому, если Вы - опытный пользователь или разработчик - можете его пропустить.
Для удобства и скорости работы все плагины в Joomla делятся на группы, каждая из которых срабатывает только при определенных условиях и в определенных местах сайта. Исключением является группа плагинов system. Плагины этой группы вызываются всегда ПЕРЕД плагинами групп. То есть, если у Вас будет 2 плагина, один из которых системный (группа system), а другой, например, контент-плагин (группа content) с одним и тем же событием (триггер), то сначала сработает системный, а потом уже контент-плагин.
Плагины группы editors-xtd вызываются только в том месте сайта, где есть поле для редактирования текста с помощью редактора: редактирование материала, описания товара, содержимого модуля и т.д.
Зачем они нужны?
Плагины этой группы добавляют дополнительные кнопки к окну редактирования текста, которые не зависят от собственно редактора текста. Вы можете пользоваться стандартным TinyMCE, Code Mirror, скачать из Joomla Extensions Directory JCE или любой другой редактор, или вообще работать без редактора и писать HTML код руками. Но эти вспомогательные кнопки будут всегда. Обычно они находятся под окном редактирования текста, но это уже регулируется настройками конкретного редактора.
Дополнительные кнопки могут реализовывать самый разный функционал, но обычно они позволяют совершать какие-то манипуляции с набранным в окне редактирования текстом.
Это может быть:
вставка шорткода для вставки модуля по позиции (
{loadposition position_name}) или по id модуля ({loadmoduleid 42}).вставка шорткода для вывода данных контакта, материала, пункта меню и т.д.
вставка картинки в текст с помощью штатного медиа менеджера (многие редакторы предоставляют свои альтернативы).
вставка линий "подробнее" и/или "разрыв страницы".
вставка шорткода для замены его на изображения из компонента фотогалереи
вообще любые манипуляции с HTML-кодом поля редактирования: исправления опечаток, типографирование текста, отправка или получение данных к стороннему API и так далее. Всё, что Ваша душа пожелает.
Обычно плагины кнопки редактора работают в 2-х режимах:
Вариант 1: напрямую модифицируют HTML-код в поле редактирования
Вариант 2: вызывают модальное окно для сортировки и выбора данных, затем модифицируют HTML-код в поле редактирования
Пример первого варианта - плагин для вставки линии "подробнее". В материалах Joomla эта линия используется для разделения текста статьи на вступительный и полный текст.
Пример 2-го варианта - кнопка для вставки SEF ссылки на материал. Сначала открывается модальное окно для поиска и выбора нужного материала, затем в текст статьи вставляется non-SEF ссылка на нужный материал. При рендере страницы системный плагин SEF обрабатывает все вхождения таких ссылок и заменяет их на актуальные SEF ссылки. Если материал останется в той же категории, но будет, например, переименован - url ссылок на него обновятся автоматически.
Как добавить кнопку редактора в Joomla со своим функционалом?
Ответ простой: написать свой плагин группы editors-xtd. Также Вам может пригодится статья Создание плагинов с учётом новой структуры Joomla 4.
В данном разделе я постараюсь описать какие инструменты даёт Вам Joomla для реализации своего функционала. В качестве примера будет плагин WT Typograph, служащий для исправления типографики текста и приведения его к единому стилю.
Плагин:
обрабатывает текст поля редактора с помощью стороннего сервиса типографики typograf.ru. Данный сервис имеет бесплатное API.
отправляет в API выделенный текст. Если выделения нет - весь текст поля редактора.
имеет 2 режима: обычный (по умолчанию) и экспресс.
обычный режим при нажатии на кнопку редактора открывает модальное окно с предпросмотром изменений типографа и кнопкой "вставить". Замена текста на измененный происходит по нажатию этой кнопки.
В экспресс-режиме при нажатии на кнопку редактора текст отправляется в API в фоновом режиме и заменяет содержимое или выделение сразу, без промежуточного окна и предпросмотра.
Режим работы плагина переключается в настройках плагина.
Таким образом, данный плагин сможет продемонстрировать оба распространённых режима работы с контентом в Joomla.
Распределение функционала
Работа по открытию модального окна, получению выделения текста или всего текста, вставка обработанного результата, закрытию модального ложится на плечи javascript.
Получение текста для типографирования, отправка текста в API и получение его, возврат результата в javascript ложится на плечи PHP.
Фронтенд часть (javascript код) мы разнесём по двум разным js-файлам, которые будем подключать в зависимости от выбранного режима работы.
Файловая структура
В Joomla 3 и Joomla 4 различается файловая структура расширений. Однако, Joomla 4 поддерживает старую файловую структуру, поэтому в нашем примере будет использоваться именно она. В рамках данной статьи файловая структура не имеет большого значения. Это, скорее, чисто техническая деталь. Но, обратите внимание на то, что до версии Joomla 4.3 плагины группы редактора имели старую файловую структуру, не использовали namespaces, так как их поддержка ещё не была реализована. Начиная с версии 4.3 можно писать плагин кнопки редактора по новой файловой структуре. Это предпочтительнее по многим причинам. Подробнее в разделе "Новая система событий для плагинов в Joomla 4" статьи Создание плагинов с учётом новой структуры Joomla 4.
Серверная часть плагина. PHP.
Для создания и установки плагина, возможности сделать раздел настроек плагина нам нужно создать минимум 2 файла (в рамках старой файловой структуры плагинов Joomla 3):
XML-манифест плагина
файл класса плагина
XML-манифест плагина
В нём указывается описание плагина для установщика расширений Joomla (системное имя, дата, версия, сайт разработчика и т.д.), параметры конфигурации плагина, сервер обновлений и т.д.
<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" group="editors-xtd" method="upgrade">
<name>Кнопка - Типограф</name>
<author>Sergey Tolkachyov</author>
<creationDate>12/03/2023</creationDate>
<copyright>(C) 2023 Sergey Tolkachyov</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>info@web-tolk.ru</authorEmail>
<authorUrl>https://web-tolk.ru</authorUrl>
<version>1.0.0</version>
<description>Типографирует текст с помощью типографов</description>
<scriptfile>script.php</scriptfile>
<files>
<filename plugin="wttipograph">wttipograph.php</filename>
</files>
<scriptfile>script.php</scriptfile>
<media folder="media" destination="plg_editors-xtd_wttipograph">
<folder>js</folder>
</media>
<config>
<fields name="params">
<fieldset name="basic">
<field type="radio"
name="express_mode"
label="Экспресс режим?"
description="По умолчанию будет открываться промежуточное модальное (всплывающее) окно. Экспресс режим позволяет изменять текст сразу в редакторе, без модального окна."
class="btn-group btn-group-yesno"
default="0">
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
</fieldset>
</fields>
</config>
</extension>
Секция <files> говорит Joomla в каком именно файле находится класс плагина.
Секция <media> говорит Joomla, что содержимое папки js при установке нужно скопировать в media/plg_editors-xtd_wttipograph/js. Находящиеся в этой папке скрипты (и стили) удобно и безопасно потом подключать с помощью HTMLHelper (или Web Assets Manager в Joomla 4).
Секция <config> реализует возможность настройки плагина из админки. Если Вам это не нужно - эту секцию можно удалить полностью. В нашем случае настройка использования экспресс-режима находится именно там. В данном примере в атрибутах label и description я написал сразу по-русски. Joomla так позволяет делать. Но правильно создать файлы локализации для английского и Вашего языка, указать в них языковые константы и в значениях этих атрибутов указывать именно языковые константы.
PHP файл класса плагина. Создание и вывод кнопки.
Класс плагина расширяет класс CMSPlugin и в Joomla 3 (и legacy Joomla 4) должен включать в своё имя префикс Plg, словоButton и имя класса. Имя класса совпадает с именем файла и папки, где плагин лежит.
То есть в файле plugins/editors-xtd/wttipograph/wttipograph.php будет находится класс PlgButtonWttipograph. В Joomla 4 с этим, конечно, проще
Интересные статьи
Интересные статьи
