Сайт справки

Файл манифеста, параметры и точка входа

Файл манифеста (файл установки)

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

Вот как будет выглядеть наш файл манифеста mod_latest_users.xml для Joomla 2.5:

<?xml version="1.0"?>
<extension type="module" version="2.5" method="upgrade" client="site">
	<name>MOD_LATEST_USERS</name>
	<author>Вася Пупкин</author>
	<creationDate>Дата создания</creationDate>
	<authorEmail>Ваш e-mail</authorEmail>
	<authorUrl>Ваш сайт</authorUrl>
	<copyright>Информация о копирайте</copyright>
	<license>Информация о лицензии</license>
	<version>1.0.0</version>
	<description>MOD_LATEST_USERS_DESCRIPTION</description>

	<files>
		<filename module="mod_latest_users">mod_latest_users.php</filename>
		<filename>helper.php</filename>
		<folder>language</folder>
		<folder>tmpl</folder>
	</files>

	<media destination="mod_latest_users" folder="media">
		<folder>css</folder>
	</media>

	<config>
		<fields name="params">
			<fieldset name="basic">
				<field 
					name="display_mode"
					type="list"
					default="0"
					label="MOD_LATEST_USERS_DISPLAY_MODE_LABEL"
					description="MOD_LATEST_USERS_DISPLAY_MODE_DESC">
					<option value="0">MOD_LATEST_USERS_MODE_0</option>
					<option value="1">MOD_LATEST_USERS_MODE_1</option>
					<option value="2">MOD_LATEST_USERS_MODE_2</option>
				</field>
				<field 
					name="count"
					type="text"
					default="10"
					label="MOD_LATEST_USERS_COUNT_LABEL"
					description="MOD_LATEST_USERS_COUNT_DESC"
				/>
				<field
					name="include_css"
					type="radio"
					default="1"
					label="MOD_LATEST_USERS_INCLUDE_CSS_LABEL"
					description="MOD_LATEST_USERS_INCLUDE_CSS_DESC">
					<option value="1">JYES</option>
					<option value="0">JNO</option>
				</field>
			</fieldset>

			<fieldset name="advanced">
				<field 
					name="layout"
					type="modulelayout"
					label="JFIELD_ALT_LAYOUT_LABEL"
					description="JFIELD_ALT_MODULE_LAYOUT_DESC"
				/>
				<field 
					name="moduleclass_sfx"
					type="text"
					label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
					description="COM_MODULES_FIELD_MODULECLASS_SFX_DESC"
				/>
				<field 
					name="cache"
					type="list"
					default="1"
					label="COM_MODULES_FIELD_CACHING_LABEL"
					description="COM_MODULES_FIELD_CACHING_DESC" >
					<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
					<option value="1">JGLOBAL_USE_GLOBAL</option>
				</field>
				<field
					name="cache_time"
					type="text"
					default="900"
					label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
					description="COM_MODULES_FIELD_CACHE_TIME_DESC" 
				/>
				<field
					name="cachemode"
					type="hidden"
					default="static">
					<option value="static"></option>
				</field>
			</fieldset>
		</fields>
	</config>

</extension>



Метаданные

Метаданные включают в себя общую информацию о модуле, такую как: название, имя автора, дату создания, описание и т.п. Обратите внимание, что элементы <name> и <description> являются переводимыми полями, поэтому название и описание модуля могут быть отображены на родном языке пользователя.

Файлы для установки

Файлы и папки, которые будут установлены, должны располагаться в элементе <files>. Каждый отдельный файл располагается в элементе <filename>. У самого первого элемента <filename> также имеется атрибут module, определяющий имя модуля и указывающий файл для загрузки при выполнении модуля. Папки располагаются в элементе <folder>.

Файлы медиа

Обратите внимание, каким образом была внесена информация о файлах медиа (в нашем случае это CSS-файл style.css):

<media destination="mod_latest_users" folder="media">
    <folder>css</folder>
</media>


Папка css со всем содержимым будет скопирована в папку /media/mod_latest_users/css/ установки Joomla, при этом, если папки /media/mod_latest_users/css/ несуществует, она будет создана. Атрибут folder указывает, из какой папки нужно скопировать файлы. У нас это папка media. Таким образом, мы позволяем переопределять медиа-файлы на уровне шаблона. Подробнее об этом вы можете прочитать в материале "Используйте папку media для разрешения переопределения медиаданных".

Параметры

Параметры модуля прописываются в секции config и располагаются в внутри элемента fields с атрибутом name, значение которого равно params. С помощью элемента fieldset мы группируем параметры, и в нашем случае мы используем две группы: basic и advanced.

В группе basic находятся поля основных параметров модуля:

  • display_mode – режим отображения списка
  • count – количество отображаемых пользователей
  • include_css – использовать или не использовать CSS-файл
В группе advanced обычно находятся расширенные параметры. В нашем примере это:

  • layout – альтернативный макета вывода
  • moduleclass_sfx – суффикс класса модуля
  • cache – включение кэширования
  • cache_time – время кэширования (в секундах)
  • cachemode – скрытое поле режима кэширования. У нас выбран режим static, который означает, что будет использоваться один кэш-файл для всех страниц с одинаковыми параметрами модуля. Кроме этого режима можно использовать режим Itemid – изменяется при смене Itemid. Такой режим больше всего подходит для динамических модулей, которые изменяются от страницы к странице, например: меню, изображения и т.п.

Файл манифеста для Joomla 3

Файла манифеста для Joomla 3 не сильно отличается от Joomla 2.5. Нужно поменять значение атрибута version у элемента extension на 3.2 (либо на другую текущую версию Joomla):

<extension type="module" version="3.2" method="upgrade" client="site">


Остальные изменения касаются стилизации полей, так как в административной панели Joomla 3 используется Bootstrap. В нашем случае это поле include_css:

<field
        name="include_css"
        type="radio"
        class="btn-group btn-group-yesno"
        default="1"
        label="MOD_LATEST_USERS_INCLUDE_CSS_LABEL"
        description="MOD_LATEST_USERS_INCLUDE_CSS_DESC">
        <option value="1">JYES</option>
        <option value="0">JNO</option>
</field>


Мы видим, что полю просто были добавлены специфичные для Bootstrap классы:

btn-group btn-group-yesno На этом различия файла манифеста между Joomla 2.5 и Joomla 3 заканчиваются.

Точка входа

Точка входа модуля занимается необходимой инициализацией, такой как подключение хелпера, файлов медиа (CSS / JS) и т.п., вызывает хелпер для получения данных, а также подключает файл макета вывода, который отобразит выходные данные модуля.

Ниже приведен код точки входа mod_latest_users.php нашего модуля:


<?php
/**
 * @package     Joomla.Site
 * @subpackage  mod_latest_users
 *
 * @copyright   Информация о копирайте
 * @license     Информация о лицензии
 */
 
defined('_JEXEC') or die;
 
// Подключаем хелпер
require_once __DIR__ . '/helper.php';
 
// Получаем данные
$users = ModLatestusersHelper::getUsers($params);
 
// Получаем суффикс класса модуля из параметров и экранируем его
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));
 
// Подключаем стили
if ($params->get('include_css', 1))
{
    JHtml::stylesheet('mod_latest_users/style.css', false, true);
}
 
// Подключаем макет вывода
require JModuleHelper::getLayoutPath('mod_latest_users', $params->get('layout', 'default'));


В целом по комментариям в коде должно быть понятно, за что отвечает каждая строка, но я все же рассмотрю некоторые моменты.

Параметры модуля доступы нам через переменную $params, которая является объектом типа JRegistry. Кроме их использования в точке входа, мы также передаем их в метод getUsers() нашего хелпера, так как в нем мы будем использовать параметр count – количество отображаемых пользователей.

Другой интересный момент - это подключение стилей. Во первых, мы позаботились о конечном пользователе и стили подключаются в зависимости от параметра. Во вторых, используя класс JHtml для подключения, мы даем возможность переопределить файл стилей на уровне шаблона. Подробнее об этом Вы можете прочитать в материале "Используйте папку media для разрешения переопределения медиаданных".

Совет - если Вы не будете подключать медиа-файлы, используя параметры модуля, то лучше всего их подключать непосредственно в макете вывода. Таким образом пользователь сможет переопределить макет вывода и отключить ненужные ему стили или JS-файлы. Думаю, что Вы не раз встречали такие модули, в которых подключение стилей происходит в точке входа, например вот так:

$document = JFactory::getDocument();
$document->addStyleSheet(JUri::base() . 'modules/mod_example/css/style.css');


И получается, что пользователь никак не может отключить вывод стилей, так как точку входа переопределить невозможно. Поэтому никогда так не делайте.

Файл макета вывода данных подключается с помощью метода getLayoutPath() класса JModuleHelper. В метод передается два параметра:

  • навзание модуля, в нашем примере - это "mod_latest_users"
  • название файла макета вывода, в нашем примере мы берем его из параметров модуля
Далее метод на основании полученных параметров пытается найти и подключить файл макета вывода в следующем порядке:

  • JPATH_THEMES/текущий_шаблон/html/mod_latest_users/название_файла.php
  • JPATH_BASE/modules/mod_latest_users/tmpl/название_файла.php
  • JPATH_BASE/modules/mod_latest_users/tmpl/default.php
Таким образом реализуется поддержка переопределения макета вывода на уровне шаблона.

На этом пока все. В следующей части мы рассмотрим хелпер, макеты вывода и языковые файлы.

Наверх

© Сайт справки 2024