Файлы манифеста (Manifest files) в Joomla 2.5, 3.x и 4.x

Информация о материале: Родительская категория: CMS — движки сайтов; Категория: Joomla 3

Введение

В Joomla есть файлы манифестов для всех расширений. Эти файлы содержат общую информацию об установке, а также параметры конфигурации самого расширения. Начиная с Joomla 2.5, существует очень мало различий между форматами файлов манифеста для различных типов расширений, что позволяет каждому типу получить доступ к полной мощности установщика Joomla.

Соглашения об обозначениях.

Файл манифеста должен иметь имя manifest.xml или <extension_name>.xml и находиться в корневом каталоге установочного пакета.

Синтаксис файлов манифеста Joomla.

Корневой элемент.

Основная информация
Новый тег <extension> заменяет старый <install></install> из Joomla 1.5

Основным тегом установочного файла является:

<extension></extension>

Этот открывающий и закрывающий тег. Он одинаков для всех расширений. В теге разрешены следующие атрибуты:

Атрибут	Значения	Область применения	Описание
`type`	`component` `file` `language` `library` `module` `package` `plugin` `template` `element`	Все расширения	Этот атрибут описывает тип расширения для установщика. На основе этого типа применяются дополнительные требования к подтегам.
`version`	`2.5` `3.0`	Все расширения	Строка, идентифицирующая версию Joomla, для которой разработано это расширение. Не используется в Joomla 3.x и было удалено из Joomla 4.0 и выше.
`method`	`install` `upgrade`	Все расширения	Значение по умолчанию `install` будет использоваться, если атрибут `method` не определён (не прописан в манифесте). Значение `install` означает, что программа установки изящно остановится, если найдет любой существующий файл/папку с новым расширением.
`client`	`site` `administrator`	Модули	Атрибут `client` позволяет указать, для какого клиента приложения доступен новый модуль (для пользовательской части сайта или для админки).
`group`	string	Плагины	Атрибут `group` указывает, для какой группы плагинов доступен новый плагин. Существующие группы - это имена папок в каталоге `/plugins`. Установщик создаст новые папки с именами групп, которые еще не существуют.

Метаданные.

Для вставки метаданных можно использовать перечисленные ниже элементы. Ни один из этих элементов не является обязательным; если они присутствуют, они должны быть дочерними по отношению к корневому элементу.

Элемент	Описание
`<name>`	необработанное имя компонента (например, `com_banners`).
`<author>`	имя автора (например, `MoonBase Inc.`)
`<creationDate>`	дата создания или выпуска (например, `ноябрь 2021 года`)
`<copyright>`	заявление об авторских правах (например, `© 2006—2021 Лунная База`)
`<license>`	заявление о лицензии (например, `NU General Public License версии 2 или более поздней; см. LICENSE.txt`)
`<authorEmail>`	адрес электронной почты автора (например, `muba4@yandex.ru`)
`<authorUrl>`	URL-адрес веб-сайта автора (например, `https://mb4.ru`)
`<version>`	номер версии расширения (например, `4.8.12`)
`<description>`	описание компонента. Это поле может быть текстовой константой. (Например, `COM_BANNERS_XML_DESCRIPTION`)
`<element>`	внутреннее имя компонента. Если опущено, будет использовано значение элемента `<name>`

Примечание: Теги <name> и <description> могут содержать языковые константы, так что имя и описание расширения могут быть показаны пользователю на его родном языке.

Файлы пользовательской части сайта на CMS Joomla.

	<files folder="from-folder">
		<filename>example.php</filename>
		<folder>examples</folder>
	</files>

Файлы для копирования во внешний каталог следует размещать в элементе <files>. Вы можете использовать дополнительный атрибут folder, чтобы указать каталог в ZIP-пакете для копирования. Каждый копируемый файл должен быть представлен элементом <filename>. Если вы хотите скопировать всю папку сразу, вы можете определить ее как <folder> без перечисления всех вложенных в неё файлов. Тогда папка будет скопирована целиком.

Важно знать, что пустые папки в установочном пакете вызывают ошибку. Для избежания этого, вкладывайте в папки файл index.html, даже без кода в нём.

Для плагинов необработанное имя плагина должно быть помещено в атрибут plugin элемента <filename>, который указывает на файл, содержащий класс плагина. Например, в случае системного плагина под названием "example" (полное имя plg_system_example) используйте <filename plugin="example">example.php</filename>.

Медиафайлы.

	<media folder="media" destination="com_example">
		<filename>com_example_logo.png</filename>
		<folder>css</folder>
		<folder>js</folder>
	</media>

В этом примере будут скопированы файлы (файлы) (/media/com_example_logo.png) и папки (/media/css/ и /media/js/), перечисленные в /media/com_example/, при необходимости создав папку com_example. Вы можете использовать необязательный атрибут folder, чтобы указать каталог в ZIP-пакете для копирования (в данном случае media).

Расширения должны хранить ресурсы, которые должны быть доступны в Интернете (JS, CSS, изображения и т.д.) в media. Среди прочего, эта фича была добавлена в качестве шага в продвижении к поддержке нескольких сайтов и возможному перемещению файлов кода (PHP) из доступных в Интернете областей сервера.

Примечание: раздел media не анализируется для расширений типа "package".

Ссылки по теме:

Админка Joomla.

	<administration>
		<!-- различные элементы -->
	</administration>

Раздел админки определен в элементе <administration>. Поскольку только компоненты применяются как к сайту, так и к админке, только манифесты компонентов могут включать этот элемент.

Файлы админки CMS Joomla.

Файлы для копирования во внутренний каталог админки следует размещать в элементе <files> в разделе <administration>. Вы можете использовать дополнительный атрибут folder, чтобы указать каталог в ZIP-пакете для копирования. Дополнительные правила см. в файлах сайта.

Ссылки меню и подменю.

Примечание к версии: До Joomla 3.4 отсутствие тега <menu> в XML-файле манифеста по-прежнему приводило к созданию пункта меню. Эта ошибка была исправлена в Joomla 3.4, поэтому, если в вашем файле манифеста нет тега <menu>, то для компонента не создается пункт меню администратора.

	<menu>COM_EXAMPLE</menu>
	<submenu>
		<!--
			Обратите внимание, что все & должны быть экранированы в &amp;, чтобы файл
			был действительным XML и был проанализирован установщиком
		-->
		<menu link="anoption=avalue&amp;anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
		<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
	</submenu>

Текст для пункта главного меню компонента определяется в пункте <menu>, дочернем элементе <administration>. Также может присутствовать элемент <submenu> (также дочерний элемент <administration>), который может содержать больше пунктов меню, определенных <menu>.

Кроме того, каждый пункт <menu> может определять следующие атрибуты:

Атрибут	Описание
`link`	Ссылка при нажатии на пункт меню. Вместо этого вы можете использовать `view` (см. ниже)
`img`	(Относительный) путь к изображению (16x16 пикселей), которое должно отображаться рядом с пунктом меню. URL-адрес должен быть соотнесён с файлом (обязательно, без пробелов)!
`alt`
`view`	Параметр URL для добавления в ссылку. Например, `<menu view="cpanel">COM_EXAMPLE</menu>` в XML-манифесте `com_example` приведет к тому, что URL-адрес элемента меню будет `index.php?option=com_example&view=cpanel`. Вместо этого вы можете использовать `link` (см.выше).

Значение внутри тега - это метка меню. В отличие от Joomla 1.5, вы не можете использовать строку на естественном языке. Например, если вы введете "Example Component" вместо COM_EXAMPLE, это приведет к тому, что имя вашего компонента появится в меню как example-component, и вы не сможете предоставить перевод. Чтобы предоставить перевод, вам необходимо создать файл с именем en-GB.com_example.sys.ini в папке administrator/languages/en-GB (вы можете использовать тег манифеста <languages>, чтобы скопировать его во время установки) или в папке administrator/components/com_example/language/en-GB. В последнем случае вы не должны включать файл перевода в тег <languages>. Если вы разместили языковой каталог в теге <files>, он будет скопирован вместе с компонентом при установке.

Содержимое этого файла должно быть:

COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

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

Joomla 1.6 и более поздних версий сортирует пункты меню компонентов на основе фактического перевода ключа, который вы указываете в своем XML-манифесте. Это означает, что порядок сортировки является правильным независимо от того, как вы называете свой ключ перевода и на каком языке отображается сайт. По сути, в Joomla 1.6 исправлена неправильная сортировка меню компонентов в Joomla 1.5 для большинства (не говорящих по-английски и не желающих знать этот странный язык!) пользователей Joomla.

Информационные панели (Dashboards).

Важная информация
Этот код работает только в Joomla 4.0 и более поздних версиях

Указывает сведения для отображения информационной панели для компонента в админке Joomla 4.x.

Это приведет к появлению иконки информационной панели рядом с пунктом меню администратора для компонента.
Иконка информационной панели при клике на ней, отобразит модули, назначенные для позиции cpanel-example модуля админки.
Заголовок и иконка, определенные в XML-файле, будут использоваться в качестве заголовка и иконки в верхней части страницы информационной панели компонента.

	<dashboards>
		<dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard>
	</dashboards>

Конфигурация.

Ахтунг!
Компоненты не поддерживают определения конфигурации в манифесте. Это был способ, реализованный в Joomla 1.5. Они могут определять параметры конфигурации для нескольких уровней с помощью файла config.xml. О том, как добавить это в свой компонент, читайте в Руководстве по разработке компонента MVC.

Элемент <config>, дочерний элемент корневого, описывает параметры конфигурации для расширения. Если применимо, параметры будут показаны соответствующим Менеджером (Менеджером плагинов, Менеджером модулей или Менеджером шаблонов). Параметры конфигурации компонентов определяются в отдельном файле с именем config.xml. Его корневым элементом должен быть <config>, плагины и модули используют раздел <config> в файле манифеста расширения.

Каждый набор полей должен содержать один или несколько элементов <field>, каждый из которых представляет одно поле формы с меткой. Список разрешенных типов полей формы и примеры определений полей XML-формы см. в разделе Стандартные типы полей формы.

Пространство имен.

Важная информация
Этот код работает только в Joomla 4.0 и более поздних версиях

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

SQL

    <install>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.install.sql</file>
        </sql>
    </install>
    <uninstall>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
        </sql>
    </uninstall>

В приведенном выше примере мы помещаем файлы SQL в папку admin/sql установочного пакета. Вы должны включить папку sql в файлы администрирования (как описано в разделе Файлы админки CMS Joomla).

Вы можете выполнить SQL во время установки и/или удаления, используя элементы <install> и <uninstall> соответственно. Элемент <sql> должен отображаться как дочерний элемент этих элементов. <sql> может содержать любое количество элементов <file>, каждый из которых определяет файл SQL для выполнения. Типы драйверов их баз данных описываются атрибутом driver, их наборы символов - атрибутом charset.

Обновление схемы SQL

Начиная с версии Joomla 1.6, также существует тег <update>, который позволяет вам предоставить серию файлов SQL для обновления текущей схемы.

	<update>
		<schemas>
			<schemapath type="mysql">sql/updates/mysql</schemapath>
			<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
		</schemas>
	</update>

Например, чтобы перейти от версии 1.0.0 к версии 1.0.1 в базе данных MySQL, файл 1.0.1.sql должен быть создан в папке sql/updates/mysql, а тег <version> манифеста должен быть обновлен до

<version>1.0.1</version>

Окончательная структура папки sql будет выглядеть следующим образом (при условии наличия базы данных MySQL)

sql
 |-->example.install.sql
 |-->example.uninstall.sql
 |-->updates
     |-->mysql
        |-->1.0.1.sql

Аналогичные файлы должны быть созданы для последующих версий.

Языковые файлы.

Начиная с Joomla 1.5, разработчики расширений должны были помещать языковые файлы расширений в основную языковую папку Joomla, используя тег <languages>...</languages>, как показано ниже. Этот метод по-прежнему можно использовать во всех версиях Joomla.

<!-- Joomla! language tag -->
<languages folder="langfiles">
	<language tag="en-GB">en-GB.com_example.ini</language>
</languages>

Однако, начиная с Joomla 1.6, рекомендуется размещать языковые файлы вашего расширения в папке расширения. Затем Joomla автоматически загрузит языковые файлы вашего расширения.

Сохраняя языковые файлы расширения в папке расширения, вы получаете выгоду от изоляции и защиты языковых файлов вашего расширения. Например, администратор удаляет язык из своей установки Joomla. Языковые файлы вашего расширения не будут удалены. Они останутся на месте и будут доступны, если язык будет установлен снова.

Структура папки с файлами языковых констант для сайта и для анминки одинакова. Вы помещаете их в языковой тег (например, en-GB) каждого языка в своей языковой папке, т.е. language/en-GB/. Вы также должны указать эти папки как для сайта, так и для админки.

В своем манифесте просто включите папку language в раздел files. Подкаталоги для каждого языка будут автоматически скопированы. Внутри группы <files> добавьте элемент <folder> рядом с элементами в группе <files>, как показано в этом примере:

<files>
	<filename plugin="alpha">alpha.php</filename>
	<folder>sql</folder>
	<folder>language</folder>
</files>

Обратите внимание, что оба способа могут работать вместе. Вот пример из кода ядра Joomla:

<files>
	<filename plugin="languagecode">languagecode.php</filename>
	<filename>index.html</filename>
	<folder>language</folder>
</files>
<languages>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>

Преимущества этого решения заключаются в следующем:

Все файлы .ini, присутствующие в основной папке, имеют приоритет над файлами в папке language/ расширения. Например, файл .sys.ini всегда будет загружаться из основных папок в админке, если он существует, за исключением случаев установки расширения, содержащего файл .sys.ini в языковой папке. В этом случае и только в этом случае файл .sys.ini в папке расширения будет отображать переведенное содержимое во время установки. Это очень удобно. Так как разработчик может иметь два файла .sys.ini с разным содержимым.

Кроме того, пользователю, которому требуется файл .ini для расширения, которое не предоставляет его на нужном языке, намного проще добавить его в основные папки. Нет никакого риска, что он будет удален в случае удаления расширения по ошибке или по любой другой причине.

Смотрите также:

Во время разработки вы можете включить отладку языка в глобальной конфигурации Joomla. Вы можете исследовать, если возникнет проблема. Начиная с версии 3.2, это необходимо для облегчения отладки, так как en-GB всегда загружается первым, когда он не находится в режиме отладки, чтобы предотвратить отображение констант.

Файл сценария.

    <scriptfile>example.script.php</scriptfile>

Дополнительный файл сценария (PHP-код, который запускается до, во время и/или после установки, удаления и обновления) может быть определен с помощью элемента <scriptfile>.

Этот файл должен содержать класс с именем <element_name>InstallerScript, где <element_name> - это имя вашего расширения (например, com_componentname, mod_modulename и т.д.). Плагины должны указывать группу (например, plgsystempluginname).

В Joomla 4.0 и более поздних версиях структура класса выглядит следующим образом:

<?php

use Joomla\CMS\Installer\InstallerAdapter;

class com_componentnameInstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   InstallerAdapter  $adapter  Объект, ответственный за выполнение этого сценария
	 */
	public function __construct(InstallerAdapter $adapter)
	{
	}
	
	/**
	 * Вызывается перед любым действием
	 *
	 * @param   string  $route  Какое действие происходит (install|uninstall|discover_install|update)
	 * @param   InstallerAdapter  $adapter  Объект, ответственный за выполнение этого сценария
	 *
	 * @return  boolean  True on success
	 */
	public function preflight($route, InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Вызывается после любого действия
	 *
	 * @param   string  $route  Какое действие происходит (install|uninstall|discover_install|update)
	 * @param   InstallerAdapter  $adapter  Объект, ответственный за выполнение этого сценария
	 *
	 * @return  boolean  True on success
	 */
	public function postflight($route, $adapter)
	{
		return true;
	}
	
	/**
	 * Вызывается при установке
	 *
	 * @param   InstallerAdapter  $adapter  Объект, ответственный за выполнение этого сценария
	 *
	 * @return  boolean  True on success
	 */
	public function install(InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Вызывается при обновлении
	 *
	 * @param   InstallerAdapter  $adapter  Объект, ответственный за выполнение этого сценария
	 *
	 * @return  boolean  True on success
	 */
	public function update(InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Вызывается при удалении
	 *
	 * @param   InstallerAdapter  $adapter  Объект, ответственный за выполнение этого сценария
	 */
	public function uninstall(InstallerAdapter $adapter)
	{
		return true;
	}
}

?>

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

Манифесты библиотек.

Важная информация
Раздел относится к Joomla 4.0 и более поздних версий.

Простой манифест библиотеки может выглядеть следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="4.0">
    <name>My Test library.</name>
    <libraryname>mytest</libraryname>
    <files>
        <folder>Classes</folder>
        <folder>language</folder>
        <filename>mytest.php</filename>
    </files>
</extension>

Это приведет к установке библиотеки в папку JPATH_SITE/libraries/mytest.

Что делать, если в вас есть несколько библиотек, и вы хотите сгруппировать их вместе в папке JPATH_SITE/libraries/mycompany?

Просто - укажите название вашей компании в свойстве libraryname каждой библиотеки, например так:

    <libraryname>mycompany/mylibrary1</libraryname>

    <libraryname>mycompany/mylibrary2</libraryname>

Затем эти библиотеки будут установлены в папках JPATH_SITE/libraries/mycompany/mylibrary1 и JPATH_SITE/libraries/mycompany/mylibrary2.

При удалении mylibrary1, mylibrary2 все равно останется установленной на вашем сайте.

При использовании script files с такими индивидуальными библиотеками имя класса установщика должно выглядеть следующим образом:

class mycompanymylibrary1InstallerScript

class mycompanymylibrary2InstallerScript

Серверы обновлений.

    <updateservers>
        <server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
        <server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
    </updateservers>

Серверы обновлений могут быть определены в элементе <updateservers>, дочернем по отношению к корневому элементу. Этот элемент может содержать один или несколько элементов <server>, каждый из которых описывает расположение, из которого загружаются обновления. Каждый элемент <server> может определять следующие атрибуты:

Атрибут	Значение	Описание
`type`	`extension` `collection`	Тип сервера обновления
`priority`	integer	Приоритет сервера обновлений
`name`	string	Имя сервера обновлений

Дополнительная информация:

Поддержка ключей загрузки.

Начиная с версии Joomla 4.0.0 пользователи могут вводить свои ключи загрузки в список сайтов обновления. Это дает им единое место для управления ключами загрузки. Когда пользователь собирается обновить расширение, Joomla проверит, есть ли ключ загрузки. Если есть ключ загрузки, Joomla добавит ключ загрузки в URL-адрес обновления.

Для поддержки ключей загрузки необходимо включить тег dlid в файл манифеста. Тег dlid принимает 2 аргумента:

prefix
suffix

Тег dlid будет выглядеть так в вашем файле манифеста:

<dlid prefix="dlid=" suffix="&amp;dummy=my.zip"/>

Префикс prefix будет добавлен перед ключом загрузки, а суффикс suffix - после ключа загрузки. Используя приведенный выше пример, полный запрос, добавленный в ссылку для загрузки, будет:

dlid=KEY&amp;dummy=my.zip

Ключ добавляется до запуска установщика onInstallerBeforePackageDownload, поэтому полный URL-адрес будет передан событию.

Примеры файлов манифеста Joomla.

Пример из реальной жизни см. в манифесте компонента Баннера в последней версии Joomla 3.9.16.

Еще несколько примеров можно найти в репозитории автономных веб-ссылок:

Перевод с английского официальной документации Joomla:
https://docs.joomla.org/Manifest_files
от 5 ноября 2021, 12:32

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)