- Где взять исходники кода плагина для Joomla 4
- Структура плагина для Joomla 4 и его установочного пакета zip-файла
- Файл манифеста плагина для Joomla 4
- Языковые файлы плагина для Joomla 4
- Форма администрирования плагина для Joomla 4
- Код плагина для Joomla 4
- Возможные ошибки в плагинах для Joomla 4
- Скриншот работы плагина для Joomla 4
Где взять исходники кода плагина для Joomla 4
MediaWiki автоматически генерирует хорошее оглавление (ToC). Есть плагины для Joomla 3.x, которые выполняют ту же работу, но пока ничего для Joomla 4. Поэтому в демонстрационных целях было решено создать плагин ToC и документировать процесс в виде учебника. Код плагина и рабочий zip-файл доступны на github:
Здесь также есть полезный учебник по Joomla 4:
Структура плагина для Joomla 4 и его установочного пакета zip-файла
Структуры установочных пакетов Zip-файлов для расширений Joomla 4 немного различаются, поскольку назначение отдельных файлов определяется в файле манифеста. Например, если два языковых файла ini, показанные здесь, находятся на одном более высоком уровне в структуре папок zip-архива, а папка en-GB здесь не существует, то целевая папка en-GB должна быть указана в файле манифеста. Zip-файл установки ToC структурирован следующим образом:
plg_j4xdemost.zip
plg_j4xdemos_toc
language
en-GB
en-GB.plg_content_j4xdemostc.ini
en-GB.plg_content_j4xdemostc.sys.ini
j4xdemostoc.php
j4xdemostoc.xmlФайл манифеста плагина для Joomla 4
Файл манифеста содержит данные расширения, и он сообщает коду установки CMS Joomla 4, что и куда идет. В качестве типа plugin в группе content файлы плагина будут установлены в файле site_root/plugins/content/j4xdemostoc. Папка для файлов с языковыми константами - site_root/administrator/language. Раздел config используется для установки параметров в интерфейсе администрирования плагина (описано ниже). По соглашению ключ перевода <name> находится в нижнем регистре. Все остальные ключи перевода находятся в верхнем регистре и включают группу после кода типа, в данном случае PLG_CONTENT_J4XDEMOSTOC_usage.
<?xml version="1.0" encoding="UTF-8"?>
<extension type="plugin" version="4.0" method="upgrade" group="content">
<name>plg_content_j4xdemostoc</name>
<creationDate>August 2019</creationDate>
<author>Clifford E Ford</author>
<authorEmail>cliff@ford.myzen.co.uk</authorEmail>
<authorUrl>http://www.fford.me.uk/</authorUrl>
<copyright>Copyright (C) 2019 Clifford E Ford, All rights reserved.</copyright>
<license>GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html</license>
<!-- Строка версии записывается в таблицу компонентов -->
<version>0.1.0</version>
<!-- Описание является необязательным и по умолчанию используется имя -->
<description>PLG_CONTENT_J4XDEMOSTOC_XML_DESCRIPTION</description>
<files>
<filename plugin="j4xdemostoc">j4xdemostoc.php</filename>
</files>
<languages folder="administrator/language">
<language tag="en-GB">language/en-GB/en-GB.plg_content_j4xdemostoc.ini</language>
<language tag="en-GB">language/en-GB/en-GB.plg_content_j4xdemostoc.sys.ini</language>
</languages>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="help"
type="text"
label="PLG_CONTENT_J4XDEMOSTOC_PARAMS_APPLIES_LABEL"
description="PLG_CONTENT_J4XDEMOSTOC_PARAMS_APPLIES_DESC"
default="PLG_CONTENT_J4XDEMOSTOC_PARAMS_APPLIES_DEFAULT"
readonly="readonly"
/>
<field
name="toc_class"
type="list"
label="PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_LABEL"
description="PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_DESC"
default="light"
>
<option value="light">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_LIGHT</option>
<option value="info">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_INFO</option>
<option value="primary">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_PRIMARY</option>
<option value="secondary">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_SECONDARY</option>
<option value="success">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_SUCCESS</option>
<option value="danger">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_DANGER</option>
<option value="warning">PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_WARNING</option>
</field>
<field
name="toc_head_class"
type="list"
label="PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_HEAD_CLASS_LABEL"
description="PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_HEAD_CLASS_DESC"
default="center"
>
<option value="center">center</option>
<option value="left">left</option>
</field>
<field
name="list_indent"
type="list"
label="PLG_CONTENT_J4XDEMOSTOC_PARAMS_CONTENTS_INDENT_LABEL"
description="PLG_CONTENT_J4XDEMOSTOC_PARAMS_CONTENTS_INDENT_DESC"
default="1"
>
<option value="1">1rem</option>
<option value="2">2rem</option>
<option value="3">3rem</option>
</field>
</fieldset>
</fields>
</config>
</extension>Языковые файлы плагина для Joomla 4
Если вам интересно, файл sys.ini используется системой во время установки и при перечислении списка установленных плагинов. Файл .ini используется при отображении формы параметров плагина. И если какие-либо строки появятся в интерфейсе сайта, они также могут быть расположены здесь. Это необычно, но оно предусматривает возможные альтернативные названия, такие как Contents или Index. Эти термины могут быть включены непосредственно в код, но тогда они будут не доступны для перевода в режиме мультиязычности.
Файл en-GB.plg_content_j4xdemostoc.sys.ini:
PLG_CONTENT_J4XDEMOSTOC="Content J4xdemos ToC"
PLG_CONTENT_J4XDEMOSTOC_XML_DESCRIPTION="Render Article Table of Contents."Файл en-GB.plg_content_j4xdemostoc.ini:
PLG_CONTENT_J4XDEMOSTOC_CONTENTS="Contents"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_APPLIES_LABEL="Applies to"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_APPLIES_DESC="Usage: {ToC} or {toc} in the article where the rable of contents is to appear."
PLG_CONTENT_J4XDEMOSTOC_PARAMS_APPLIES_DEFAULT="Articles"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_LABEL="Contents card class"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_DESC="For card and border colours"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_LIGHT="Bootstrap light: Light grey"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_INFO="Bootstrap info: Aquamarine"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_PRIMARY="Bootstrap primary: Blue"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_SECONDARY="Bootstrap secondary: Grey"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_SUCCESS="Bootstrap success: Green"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_DANGER="Bootstrap danger: Red"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_CLASS_OPTION_WARNING="Bootstrap Warning: Yellow"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_HEAD_CLASS_LABEL="Card heading class"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CARD_HEAD_CLASS_DESC="Should the word 'Contents' appear at the left or center?"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CONTENTS_INDENT_LABEL="List item indent"
PLG_CONTENT_J4XDEMOSTOC_PARAMS_CONTENTS_INDENT_DESC="The distance to indent the content list links in rem units."Форма администрирования плагина для Joomla 4
Эта форма доступна через интерфейс администратора в разделе Система -> Управление -> Плагины (System -> Manage -> Plugins). Не забудьте включить плагин, чтобы он мог работать в CMS Joomla 4.
Первый пункт в форме, Applies to, - это напоминание о том, что плагин работает только со статьями, а не с избранными статьями или модулями. или что-нибудь еще.
Остальные элементы задают внешний вид Toc:
Contents card class- выбирает один из стилей Bootstrap карты из выпадающего списка.
Card heading class- выбор выравнивания текста заголовка по левому краю или по центру.
List item indent- выбор относительного отступа для каждого элемента в списке содержимого.
Обратите внимание, что по соображениям доступности лучше показывать описания элементов формы в виде обычного текста, а не всплывающих подсказок или всплывающих окон.
Код плагина для Joomla 4
Большая часть кода плагина - это обычный php для манипулирования текстом. Пожалуйста, ознакомьтесь с кодом на github для получения полного списка. Код хорошо закомментирован. Вот важные строки из j4demostoc.php:
Оператор класса
defined('_JEXEC') or die;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Language\Text;
// See https://docs.joomla.org/J4.x:Creating_a_Plugin_for_Joomla
/**
* Создание и/или визуализизация оглавление статьи (ToC - Table of Contents).
*
* @since 4.0
*/
class PlgContentJ4xdemostoc extends CMSPlugin
{Не забудьте запустить код с проверкой на загрузку Joomla или умереть! (1-я строка)
Инструкции use сообщают загрузчику, какие внешние классы необходимы этому плагину. CMSPlugin является родительским классом PlgContentJ4xdemostoc, и Text используется для перевода заголовка списка содержимого (List of Contents).
Обратите внимание на инструкцию класса: она должна начинаться с Plg, за которой следует группа плагинов, в данном случае Content, за которым следует имя этого плагина J4xdemostoc.
Блоки с комментариями тоже важны! Они используются автоматизированными инструментами документирования.
Точка входа
/**
* Look for {ToC} or {toc} and replace with Contents Panel.
*
* @return void
*
* @since 4.0
*/
public function onContentPrepare($context, &$article, &$params, $page = 0)
{Важно: Для вызова функции точки входа должно быть инициировано именованное событие. Событие onContentPrepare генерируется во время создания публикации, поэтому этот плагин просто должен реагировать на это событие. Нет необходимости, даже неправильно, пытаться вызвать это событие в другом месте.
Переменная $context будет содержать строку, такую как 'com_content.article' или 'com_content.featured'. Это можно проверить, то как этот плагин будет отрабатывать.
Переменная $article содержит объект, передаваемый по ссылке. Любые изменения, внесенные в него в плагине, устанавливаются в объекте. Таким образом, плагину не нужно возвращать какие-либо переменные.
Переменная $params содержит параметры публикации.
Тестирование, какие действия следует предпринять
// избранная публикация с разделителем readmore нуждается в удалении {ToC}
if ($context === 'com_content.featured')
{
$article->text = str_ireplace('{ToC}', '', $article->text);
return;
}
// контекст может быть чем-то иным, чем com_content, например модулем:
// в этом случае ничего не делайте и возвращайтесь
if ($context !== 'com_content.article')
{
return;
}
// возврат, если в содержимом публикации нет {ToC}
if (stripos($article->text,'{ToC}') === false)
{
return;
}
// Загружайте языковой файл плагина только при необходимости
$this->loadLanguage();Все это объясняется в комментариях к коду, поэтому никаких дополнительных объяснений здесь не требуется. Остальная часть кода плагина - это манипуляция с текстом: извлечение заголовков для создания списка содержимого со ссылками и изменение заголовков для добавления якорей.
Возможные ошибки в плагинах для Joomla 4
Там будут ошибки и баги. Вероятно, не для автора, но, вероятно, для кого-то еще. Поэтому пройдите через код с отладчиком и посмотрите на переменные; используйте временные операторы var_dump() или операторы echo и die; и используйте инструменты разработчика браузера для решения проблем с отображением. В первый раз я забыл обработать заполнитель {Toc} в избранных статьях. И отображение карты содержимого было плохим.
На дисплее загрузочной карты: цвет фона карты установлен в один из рекомендуемых цветов. Затем цвет заголовка карты устанавливается на черный с непрозрачностью 0,03. Это почти заметно на сайте начальной загрузки, но совсем не с шаблоном Cassiopeia. Добавленное в строку стиля, увеличивающее непрозрачность фона заголовка до 0,1, значительно улучшило различие.
Скриншот работы плагина для Joomla 4
Это обрезанный скриншот результата для обучающей статьи, написанной для CMS Joomla 4.0 Alpha 10:
Другие цветовые схемы начальной загрузки ужасны с шаблоном Cassopeia.
Clifford E Ford August 2019
Перевод с английского официальной документации по Joomla 4:
https://docs.joomla.org/J4_Plugin_example_-_Table_of_Contents
Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)
