Пример создания простого модуля для Joomla 4.x - Mydownmsg

  1. Инструкция по работе с модулем J4xdemos-mod-mydownmsg
  2. Назначение модуля 4xdemos-mod-mydownmsg
  3. Структура zip-файла модуля Joomla 4
  4. Файл манифеста модуля Joomla 4
  5. Языковые файлы модуля Joomla 4
    1. en-GB/en-GB.mod_mydownmsg.ini
    2. fr-FR/fr-FR.mod_mydownmsg.ini
    3. de-DE/de-DE.mod_mydownmsg.ini
  6. Код модуля Joomla 4
    1. mod_mydownmsg.php
    2. tmpl/default.php
  7. Установка модуля Joomla 4
  8. Тестирование на других языках модуля Joomla 4


Инструкция по работе с модулем J4xdemos-mod-mydownmsg

По этой ссылке есть очень хороший учебник по модулям:

Этот учебный пример проще, но предоставляет рабочий пример, который можно опробовать, отладить и изучить простой код.

Устанавливаемый zip-файл доступен на Github:

Назначение модуля 4xdemos-mod-mydownmsg

Например есть один сайт, для которого ведётся разработка, имеет пользователей по всему миру и предлагает 16 или около того языков. Когда нужно закрыть сайт для обслуживания системы, используется пользовательский модуль для создания короткого сообщения и размещения его в позиции рядом с верхней частью страницы. Модуль публикуется за час или около того до события и не публикуется по окончании обслуживания. Проблема в том, что сообщение на английском языке, который, хотя и считается международным, но по факту, не все люди его знают и понимают. Поэтому этот демонстрационный модуль выполняет ту же работу - отображает текст, но на любом языке, который подходит для пользователя сайта.

Название модуля - mydownmsg - это просто напоминание о том, что модуль отображает сообщение My Site going down.

Структура zip-файла модуля Joomla 4.

Обычно полезно знать структуру zip-файла, чтобы проверить, что все файлы и папки находятся в ожидаемых местах при распаковке:

mod_mydownmsg.zip
     mod_mydownmsg
          language
               en-GB
                    en-GB.mod_mydownmsg.ini
                    en-GB.mod_mydownmsg.sys.ini
               de-DE
                    de-DE.mod_mydownmsg.ini
               fr-FR
                    fr-FR.mod_mydownmsg.ini
          tmpl
               default.php
          mod_mydownmsg.php
          mod_mydownmsg.xml

Обратите внимание, что все администраторы обязаны использовать английский язык (хотя, и это тоже можно дописать, т.к. никто не обязан знать иностранных языков, если вы им поможете в этом, предоставив перевод создаваемых вами интерфейсов), поэтому файлы неанглоязычного перевода должны переводить только те строки, которые видят посетители сайта.

Файл манифеста модуля Joomla 4.

Файл манифеста расширения Joomla 4 (в нашем случае, модуля) управляет процессом установки расширения. Примечательные особенности:

В манифесте расширения Joomla 4 указываются некоторые существенные данные:

  • type="module"
    • является достаточно очевидным
  • version="4.0"
    • означает, что это расширение предназначено для Joomla 4 и не должно устанавливаться в предыдущие версии.
  • method="upgrade"
    • означает, что это расширение может быть установлено и обновлено, если появятся новые версии.
  • client="site"
    • говорит Joomla 4, что это модуль сайта, а не модуль администратора (админки).

Переменная version используется для управления обновлением, предотвращая перезапись старых версий новыми.

Раздел config показывает, какие параметры нужны этому модулю. Все параметры должны иметь значения по умолчанию, так как они задаются при установке. Любое изменение параметров требует повторной установки модуля из измененного zip-файла. (Проверьте это!)

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" version="4.0" method="upgrade" client="site">
	<name>mod_mydownmsg</name>
	<creationDate>August 2019</creationDate>
	<author>Clifford E Ford</author>
	<authorEmail>Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.</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>1.0</version>
	<!-- Описание является необязательным и по умолчанию соответствует имени -->
	<description>MOD_MYDOWNMSG_XML_DESCRIPTION</description>
	<namespace>J4xdemos\Module\Mydownmsg</namespace>

	<files>
		<filename module="mod_mydownmsg">mod_mydownmsg.php</filename>
        	<filename>mod_mydownmsg.xml</filename>
        	<folder>tmpl</folder>
	</files>

	<languages folder="language">
		<language tag="en-GB">en-GB/en-GB.mod_mydownmsg.ini</language>
		<language tag="en-GB">en-GB/en-GB.mod_mydownmsg.sys.ini</language>
		<language tag="de-DE">de-DE/de-DE.mod_mydownmsg.ini</language>
		<language tag="fr-FR">fr-FR/fr-FR.mod_mydownmsg.ini</language>
	</languages>

	<config>
		<fields name="params">
			<fieldset name="basic">

				<field 
					name="msg_id"
					type="list"
					label="MOD_MYDOWNMSG_PARAMS_MSG_ID_LABEL"
					description="MOD_MYDOWNMSG_PARAMS_MSG_ID_DESC"
					default="v1"
					required="true"
				>
					<option value="v1">MOD_MYDOWNMSG_PARAMS_MSG_ID_OPTION_V1</option>
					<option value="v2">MOD_MYDOWNMSG_PARAMS_MSG_ID_OPTION_V2</option>
				</field>

				<field
					name="hour"
					type="number"
					label="MOD_MYDOWNMSG_PARAMS_HOUR_LABEL"
					description="MOD_MYDOWNMSG_PARAMS_HOUR_DESC"
					default="12"
					min="0"
					max="23"
					required="true"
					></field>

				<field
					name="minute"
					type="number"
					label="MOD_MYDOWNMSG_PARAMS_MINUTE_LABEL"
					description="MOD_MYDOWNMSG_PARAMS_MINUTE_DESC"
					default="00"
					min="00"
					max="59"
					required="true"
					></field>

				<field
					name="tz"
					type="number"
					label="MOD_MYDOWNMSG_PARAMS_TZ_LABEL"
					description="MOD_MYDOWNMSG_PARAMS_TZ_DESC"
					default="0"
					min="-11"
					max="11"
					required="true"
					></field>

			</fieldset>
		</fields>
	</config>
</extension>

Языковые файлы модуля Joomla 4.

Этот модуль имеет очень мало строк. Те, что находятся в файлах sys.ini, используются при установке и для списков среди других модулей. Файлы .ini используются в форме администратора и при визуализации модуля на сайте. Обратите внимание на соглашения в идентификации строк:

MOD_[имя]_[назначение]_[использование]

Приведенные ниже файлы показывают, что немецкий и французский переводы включают только те строки, которые будут видны посетителям сайта, поскольку форма Параметров модуля всегда будет администрироваться на английском языке. Если вы не знали: строки en-GB всегда загружаются первыми по умолчанию, чтобы случайно непереведенные строки не появились в качестве ключей строк. Затем загружаются строки нужного языка и перезаписывают эквивалентные английские строки. Так работает мультиязычность в Joomla 4.

Французская и немецкая версии строк были получены с помощью Google Translation Tools. Есть предположение, что это лучше работает для предложений, чем для отдельных слов!

en-GB/en-GB.mod_mydownmsg.ini

MOD_MYDOWNMSG="My System Maintainence Message"
MOD_MYDOWNMSG_XML_DESCRIPTION="Show a message about imminent system down time."

MOD_MYDOWNMSG_MSG_V1="This site will close for a short period at %s"
MOD_MYDOWNMSG_MSG_V2="Please log out. This site will close for one hour or more at %s"

MOD_MYDOWNMSG_PARAMS_MSG_ID_LABEL="Select Message version"
MOD_MYDOWNMSG_PARAMS_MSG_ID_DESC="The short downtime or long downtime message vesion."

MOD_MYDOWNMSG_PARAMS_MSG_ID_OPTION_V1="Short < 1 hour"
MOD_MYDOWNMSG_PARAMS_MSG_ID_OPTION_V2="Long > 1 hour"

MOD_MYDOWNMSG_PARAMS_HOUR_LABEL="Hour"
MOD_MYDOWNMSG_PARAMS_HOUR_DESC="Set the hour when the site will close"

MOD_MYDOWNMSG_PARAMS_MINUTE_LABEL="Minute"
MOD_MYDOWNMSG_PARAMS_MINUTE_DESC="Set the minutes when the site will close"

MOD_MYDOWNMSG_PARAMS_TZ_LABEL="Time Zone"
MOD_MYDOWNMSG_PARAMS_TZ_DESC="Set your time zone offset from GMT"

fr-FR/fr-FR.mod_mydownmsg.ini

MOD_MYDOWNMSG_MSG_V1="Ce site sera fermé pour une courte période à %s"
MOD_MYDOWNMSG_MSG_V2="Veuillez vous déconnecter. Ce site sera fermé pendant une heure ou plus à %s"

de-DE/de-DE.mod_mydownmsg.ini

MOD_MYDOWNMSG_MSG_V1="Diese Seite wird für kurze Zeit um %s geschlossen"
MOD_MYDOWNMSG_MSG_V2="Bitte melden Sie sich ab. Diese Seite wird für eine Stunde oder länger um %s geschlossen"

Код модуля Joomla 4.

Код модуля невероятно прост. Есть два файла:

  • mod_mydownmsg.php
    • просто указывает Joomla, какой файл шаблона использовать, позволяя разработчикам шаблонов переопределить шаблон по умолчанию.
  • tmpl/default.php
    • содержит код для вывода.

Этот модуль настолько прост, что ему больше ничего не нужно!

mod_mydownmsg.php

<?php
/**
 * @package     J4xdemos.Module
 * @subpackage  mod_mydownmsg
 *
 * @copyright   Copyright (C) 2019 Clifford E Ford. All rights reserved.
 * @license     GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
 */

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;

// получить вариант сообщения

require ModuleHelper::getLayoutPath('mod_mydownmsg', $params->get('layout', 'default'));

tmpl/default.php

Шаблон модуля по умолчанию извлекает параметры модуля и берёт строку для вывода, используя строку, извлеченную из файла перевода.

<?php
/**
 * @package     J4xdemos.Module
 * @subpackage  mod_mydownmsg
 *
 * @copyright   Copyright (C) 2019 Clifford E Ford. All rights reserved.
 * @license     GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
 */

defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;

// строка $msg содержит заполнитель %s, который будет заменен в операторе sprintf
$msg = Text::_('MOD_MYDOWNMSG_MSG_' . strtoupper($params->get('msg_id')));

$tod = $params->get('hour') . ':' . $params->get('minute');
$tz = $params->get('tz');

if ($tz > 0 )
{
	$tz = '(+' . $tz . ')';
}
else if ($tz < 0)
{
	$tz = '(-' . $tz . ')';
}
else {
	$tz = '';
}

$tod .= ' GMT ' . $tz;

?>

<div class="alert alert-warning" role="alert">
	<?php echo sprintf ($msg, $tod); ?>
</div>

Установка модуля Joomla 4.

Установка через Upload Package File в меню Install / Extensions (Установка / Расширения), кажется, работает. Это сделано ...

В форме редактирования модуля

  1. Введите название модуля.
    • Помните, что у модуля может быть несколько экземпляров, поэтому они могут отображаться в разных местах или иметь разные параметры.
  2. Установите время, когда сайт будет отключен.
  3. Установите часовой пояс (возможно, есть лучший способ, чем использование GMT +- n часов).

В правом списке общих параметров при настройке модуля Joomla 4:

  1. Установите для Title значение Не показывать
  2. ВыберитеПоложение (Position) - в Cassiopeia top-a помещает сообщение над содержимым страницы, и идеально для этого модуля!
  3. Установите для параметра Статус значение Опубликовано.
  4. На вкладке Привязка к меню (Menu Assignment) выберите На всех страницах.
  5. Сохраните и всё готово к проверке внешнего вида сайта с установленным и настроенным модулем!

Замечание: Этот модуль должен быть первым в списке модулей в позиции top-a. Однако селектор Упорядочить не действует, и первой позиции для выбора нет. Когда список модулей фильтруется по позиции top-a, этот элемент можно перетащить в начало списка, но он не прикрепляется.

Установка и настройка модуля Joomla 4

Теперь вы можете проверить сообщение, которое видят посетители сайта на Joomla 4 выводимое с помощью этого модуля:

проверить сообщение, которое видят посетители сайта на Joomla 4 выводимое с помощью этого модуля

Тестирование на других языках модуля Joomla 4.

Чтобы проверить французскую и немецкую версии сообщения сайта на Joomla 4 с этим модулем, перейдите в меню Система / Управление / Языки (System / Manage / Languages) и установите язык по умолчанию на французский или немецкий. Вуаля:

Сообщение модуля для сайта на Joomla 4 на французском языке:

Сообщение модуля для сайта на Joomla 4 на французском языке

Сообщение модуля для сайта на Joomla 4 на немецком языке:

Сообщение модуля для сайта на Joomla 4 на немецком языке

Clifford E Ford, August 2019
Перевод с английского официальной документации Joomla 4:
https://docs.joomla.org/J4_Module_example_-_Mydownmsg

Заберите ссылку на статью к себе, чтобы потом легко её найти ;)

Выберите, то, чем пользуетесь чаще всего:

Спасибо за внимание, оставайтесь на связи! Ниже ссылка на форум и обсуждение ; )

Войдите чтобы комментировать

Обсудить эту статью

INFO: Вы отправляете сообщение как 'Гость'