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

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

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

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

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

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

Папка 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):

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

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

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

Точка входа

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

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

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

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

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

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

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

Файл макета вывода данных подключается с помощью метода 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

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

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