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

13.04.2014 Joomla

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

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

Вот как будет выглядеть наш файл манифеста 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 1.5 режим oldstatic. По умолчанию используется режим itemid.

Есть еще два режима кэширования, которые должны вызываться из модуля с помощью метода JModuleHelper::moduleCache($module, $moduleparams, $cacheparams), а не из файла манифеста:

safeuri - Id кэша создается из массива URL параметров, так же как в компоненте. Используйте этот режим, если модуль зависит от параметров URL, а не Itemid (например модуль, который отображает изображение в зависимости от категории). Свойство $cacheparams->modeparams является массивом URL параметров и их типов фильтра.
Id - модуль устанавливает свой собственный кэш в зависимости от собственной формулы, которая передается через $cacheparams->modeparams

Подробнее о кэшировании мы можете узнать из нашего материала "Кэш в Joomla – разбираемся в деталях".

Файл манифеста для 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

Таким образом реализуется поддержка переопределения макета вывода на уровне шаблона.

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

/**
* @packageJoomla.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, false);
}
// Подключаем макет вывода
require JModuleHelper::getLayoutPath('mod_latest_users', $params->get('layout', 'default'));

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

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

Метаданные

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

Файлы медиа

Параметры

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

Точка входа

Документация

WP REST API - получение данных

Gantry 5 - Введение

WP REST API – настройка и использование OAuth 1.0a аутентификации

WP REST API – настройка и использование базовой аутентификации

Создание темы для Grav

Заработок в сети