Создание установочного пакета для расширения Joomla! 3

При разработке любого из расширений для CMS Joomla! всегда возникает вопрос его дальнейшей установки на рабочий проект. Именно для этого необходимо собрать расширение в установочный пакет, что может вызвать затруднения без соответствующего опыта. В CMS Joomla! создание установочного пакета для какого-либо его расширения имеет ряд особенностей, которые подробно рассматриваются в данной статье. Наиболее важные из них: создание файловой структуры расширения, файла манифеста, обновление расширения после установки и др.

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

Оглавление

Файловая структура расширения

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

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

Общая файловая структура расширения

Чаще всего все основные файлы существующего в CMS Joomla! расширения находятся в одной папке. Например, для плагина это может быть папка plugins/system/sef, для модуля modules/mod_articles_news, для шаблона templates/protostar и т.д. Для сборки инсталляционного пакета расширения необходимо скопировать все его файлы в отдельную папку. Желательно ее назвать в соответствии с именем самого расширения.

Также в корневой директории установочного пакета могут содержаться дополнительные файлы и папки. Например, media – папка, использующаяся для хранения css стилей, изображений, js скриптов и т.д., которые используются в расширении. Она может содержать соответствующие подпапки css, images, js и др. Содержимое media директории описывается специальным тегом в установочном файле манифеста расширения (см. Медиа файлы) и копируется при установке в папку media/[имя_расширения].

В папке language размещаются языковые файлы расширения, которые могут копироваться в системную языковую директорию. Языковые файлы в папке language необходимо размещать в подпапках с именами, соответствующими тегам их языков. Например, в папке language/en-GB размещаются языковые файлы для английского языка, в language/ru-RU – русского и т.д.

Папка sql чаще всего используется для расположения sql файлов, использующихся при установке и удалении расширения, а также для хранения обновлений базы данных для каждой из версий расширения в подпапке updates. Соответствующие sql файлы вносят изменения в базу данных сайта при установке, удалении или обновлении расширения.

Файловая структура компонента для CMS Joomla!

Главным отличием компонента от других расширений Joomla! является наличие отдельной пользовательской и административной части. При создании установочного пакета принято создавать в его корне папки admin и site для размещения в них файлов и папок административной и пользовательской части компонента соответственно. В папку admin копируется структура, которая расположена или планируется располагаться в папке administrator/components/[имя_компонента] в CMS Joomla!. Папка site при этом будет содержать все файлы и папки из components/[имя_компонента].

Файл манифеста инсталляционной сборки компонента должен обязательно находиться в его корневой директории и называться [имя_компонента].xml, хотя после инсталляции он будет скопирован в административную директорию компонента. Также в корневую директорию помещается папка media, если она используется в компоненте.

Папка sql при сборке компонента обязательно должна находиться в директории admin, а папки language создаются отдельно в admin и site для административной и пользовательской части сайта отдельно. Их внутренняя структура аналогична той, что описана в общем случае.

Создание файла манифеста

Файл манифеста должен быть расположен в корне установочного пакета и иметь название manifest.xml или [имя_расширения].xml. Правильное описание тегов в файле манифеста позволит скопировать все файлы и папки расширения в соответствующие каталоги CMS Joomla!, выполнить обновление структуры в базе данных, добавить информацию о расширении в CMS, легко обновлять расширение в дальнейшем и т.д.

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

Корневым элементом файла манифеста является <extension>. Этот элемент заменил старый корневой элемент <install>, который использовался в Joomla! 1.5. Корневой тег может содержать ряд атрибутов, список которых приведен ниже:

Информация о расширении и разработчике

Чаще всего вначале корневого элемент файла манифеста расположен ряд тегов, которые определяют информацию о расширении и его разработчике.

• <name> – системное имя расширения с префиксом (например, com_banners, mod_login)
• <author> – имя автора (например, BoxApp)
• <creationDate> – дата создания расширения или выхода новой версии (например, 22.11.2014)
• <copyright> – заявление об авторском праве (например, © 2014 - 2015 BoxApp. Все права защищены.)
• <license> – лицензионное соглашение (например, GNU General Public License version 2 or later)
• <authorEmail> – e-mail адрес автора (например, info@boxapp.net)
• <authorUrl> – ссылка на сайт автора (например, http://boxapp.net)
• <version> – номер версии расширения (например, 1.2.0)
• <description> – описание расширения. Этот параметр использует стандартный механизм Joomla! для перевода текста на разные языки, поэтому можно в качестве значения использовать языковую константу. Например, COM_EXAMPLE_XML_DESCRIPTION.

Файлы и папки расширения

Чтобы при установке были скопированы файлы и папки расширения, необходимо заполнить блок <files> в файле манифеста. Например, для модуля Joomla! этот блок может иметь следующий код:

<files>
	<folder>language</folder>
	<folder>tmpl</folder>
	<filename module="[имя_модуля]">[имя_модуля].php</filename>
	<filename>helper.php</filename>
	<filename>index.html</filename>
	<filename>[имя_модуля].xml</filename>
</files>

Если собирается установочный пакет для компонента Joomla!, то файлы и папки для пользовательской части сайта помещаются в директорию site корневой папки установочного пакета. При этом блок <files> может иметь следующий вид:

<files folder="site">
	<folder>controllers</folder>
	<folder>helpers</folder>
	<folder>models</folder>
	<folder>views</folder>
	<filename>[имя_компонента].php</filename>
	<filename>controller.php</filename>
	<filename>index.html</filename>
	<filename>metadata.xml</filename>
	<filename>router.php</filename>
</files>

Здесь в качестве атрибута folder тега <files> указана директория site, соответственно в ней должны быть расположены папки, указанные во внутренних тегах <folder> (controllers, helpers, models, views) и файлы, указанные с помощью тегов <filename> ([имя_расширения].php, controller.php, index.html, metadata.xml, router.php). При этом внутренняя структура папок, указанных в тегах <folder> будет полностью скопирована вместе со всеми вложенными папками и файлами. В случае с компонентом вся указанная в теге <files> структура папок и файлов будет скопирована в директорию components/[имя_компонента].

Медиа файлы

В структуре CMS Joomla! для медиа файлов отведена отдельная папка в корне с названием media. Именно в нее инсталлятор производит копирование медиа файлов расширения, которые указываются в теге <media>. При этом, расположение файлов в медиа папке расширения соответствует определенной структуре. В корневой директории установочного пакета создается папка media. В ней должны быть расположены подпапки, если в расширении используется соответствующий тип файлов: css (для css файлов стилей), images (для хранения изображений) и js (для скриптов, использующихся в расширении). Кроме этого в папке media могут быть расположены и другие подпапки и файлы, использующиеся в работе расширения. Блок с тегом <media> в файле манифеста может иметь следующий вид:

<media folder="media" destination="[имя_расширения]">
	<folder>css</folder>
	<folder>images</folder>
	<folder>js</folder>
	<filename>index.html</filename>
</media>

В примере выше атрибуты тега <media> определяют:

• folder – имя папки в корневой директории инсталляционного пакета, в которой расположены подпапки и файлы из тегов <folder> и <filename>
• destination – имя папки расширения, в которую будет скопирована указанная ниже структура папок и файлов. Например, com_example для компонента, mod_example для модуля, plg_system_example для системного плагина.

В итоге медиа файлы и папки, указанные в <media> теге будут скопированы из папки madia установочного пакета по пути media/[имя_расширения].

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

В Joomla! 1.5 использовался подход, когда языковые файлы расширения при его установке копировались в системную папку CMS для хранения языковых файлов пользовательской части сайта language, или его административной части administrator/language. Поддержка работы этого подхода осталась и в следующих версиях Joomla! включая 3.x. Чтобы воспользоваться этим подходом, необходимо разместить тег <languages> в корневом теге файла манифеста, внутри которого нужно указать теги <language> для каждого из языков, поставляемых вместе с расширением в инсталляционной сборке. Например, этот блок может иметь следующий вид:

<languages folder="language">
	<language tag="en-GB">en-GB.[имя_расширения].ini</language>
	<language tag="ru-RU">ru-RU.[имя_расширения].ini</language>
</languages>

При этом языковые файлы должны быть расположены в папке language, а их имена обязательно должны соответствовать названию расширения вместе с префиксом, соответствующим его типу (например, com_example, plg_system_example, tpl_example и т.д.). При установке расширения Joomla! эти файлы будут скопированы в один из подкаталогов папки language, название которого соответствует указанному в теге <language> атрибуту tag. Например, файл из установочного пакета language/en-GB.[имя_расширения].ini будет скопирован в папку Joomla! по пути language/en-GB/en-GB.[имя_расширения].ini в корневой директории Joomla!.

Начиная с версии Joomla! 1.6 было предложено хранить языковые файлы непосредственно в папке расширения, а не копировать их в системные папки с языковыми файлами. При этом Joomla! автоматически загружает языковые файлы расширения при его использовании.

Новый подход с хранением языковых файлов внутри расширения имеет ряд явных преимуществ. Например, если администратор удалил один из языков в CMS Joomla!, то соответствующие языковые файлы расширения не будут затронуты. Они останутся в составе расширения и будут доступны, если язык снова будет установлен. Кроме этого, администратору сайта будет очень легко переопределить константы в языковых файлах расширения, если ему это понадобится. Достаточно просто скопировать языковой файл из папки расширения в системную директорию с языковыми файлами и переопределить нужные константы. При этом CMS Joomla! сама подключит в первую очередь файл из системной директории в соответствии с приоритетом, а при обновлении расширения изменения в языковом файле не будут перезаписаны.

Для автоматического подключения языковых файлов из папки расширения их необходимо расположить в соответствии с определенной структурой. Для пользовательской и административной части сайта эта структура одинакова, если речь идет о компоненте. Все языковые файлы размещаются в папке с именем, соответствующим языковому тегу (атрибуту tag) внутри директории language. Например, language/en-GB. И так для каждого из языков, поставляемых в установочном пакете расширения. Папка language должна быть расположена в корне инсталляционной сборки, а в теге <files> манифеста нужно добавить тег <folder> для этой папки:

<files>
    …
    <folder>language</folder>
    …
</files>

При установке расширения папка language будет скопирована в директорию расширения вместе с другими его папками и файлами.

Если необходимо, мы также можем добавить в файл манифеста и тег <language>. В соответствии с созданной структурой папок он может иметь следующий вид:

<languages>
	<language tag="en-GB">language/en-GB/en-GB.[имя_расширения].ini</language>
	<language tag="en-GB">language/en-GB/en-GB.[имя_расширения].sys.ini</language>
	<language tag="ru-RU">language/ru-RU/ru-RU.[имя_расширения].ini</language>
	<language tag="ru-RU">language/ru-RU/ru-RU.[имя_расширения].sys.ini</language>
</languages>

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

Настройки

Блок <config> является дочерним для корневого тега файла манифеста и отвечает за описание настроек для расширения, которые можно указать в административной части сайта. Настройки расширений в основном расположены в менеджере для управления соответствующим типом расширений Joomla! (например, Менеджер плагинов, Менеджер модулей или Менеджер шаблонов). В официальной документации указывается, что настройки расширения могут быть указаны в отдельном файле расширения, который должен называться config.xml и иметь корневой элемент <config>, но на практике этот подход работает только для компонентов. Для остальных типов расширений Joomla! блок <config> нужно размещать в файле манифеста.

Первым дочерним тегом у <config> должен быть <fields name="params"> (необязательно для компонентов), который в свою очередь может содержать один или более дочерних тегов <fieldset>, которые будут отображаться в виде отдельных вкладок в HTML коде станицы настроек данного расширения, и будут служить контейнерами для групп полей формы с настройками расширения. В атрибуте name тега <fieldset> можно указать имя вкладки. Атрибуты label и description используются для указания названия и краткого описания вкладки, и могут содержать языковые константы в качестве значений. Если атрибут label не указан, то языковая константа будет сформирована автоматически по шаблону COM_CONFIG_[имя_вкладки]_FIELDSET_LABEL (где имя_вкладки – это значение атрибута name) и достаточно будет лишь указать перевод в соответствующих языковых файлах расширения.

Каждый <fieldset> должен содержать один или более дочерних тегов <field>, каждый из которых описывает одно поле формы настроек. Полный список доступных полей форы в Joomla! можно найти в документации вместе с примерами использования этих полей.

Приведем пример конфигурационного файла компонента com_example.

<?xml version="1.0" encoding="utf-8"?>
<config>
	<fieldset
		name="base"
		label="COM_EXAMPLE_CONFIG_BASE_SETTINGS_LABEL"
		description="COM_EXAMPLE_CONFIG_BASE_SETTINGS_DESC">
		<field
			name="show_title"
			type="radio"
			class="btn-group btn-group-yesno"
			default="1"
			label="JGLOBAL_SHOW_TITLE_LABEL"
			description="JGLOBAL_SHOW_TITLE_DESC"
			>
			<option value="1">JSHOW</option>
			<option value="0">JHIDE</option>
		</field>
		<field
			name="link_titles"
			type="radio"
			class="btn-group btn-group-yesno"
			default="1"
			label="JGLOBAL_LINKED_TITLES_LABEL"
			description="JGLOBAL_LINKED_TITLES_DESC"
			>
			<option value="1">JYES</option>
			<option value="0">JNO</option>
		</field>
		<field
			name="spacer1"
			type="spacer"
			hr="true"
			/>
		<field
			name="any_text_option"
			type="text"
			default="Default text"
			label="COM_EXAMPLE_FIELD_ANY_TEXT_OPTION_LABEL"
			description="COM_EXAMPLE_FIELD_ANY_TEXT_OPTION_DESC"
			/>
	</fieldset>
	<fieldset
		name="permissions"
		label="JCONFIG_PERMISSIONS_LABEL"
		description="JCONFIG_PERMISSIONS_DESC">
		<field
			name="rules"
			type="rules"
			label="JCONFIG_PERMISSIONS_LABEL"
			validate="rules"
			filter="rules"
			component="com_example"
			section="component"
			/>
	</fieldset>
</config>

В этом примере описаны две группы настроек в тегах <fieldset> с именами base и permissions. Стоит обратить внимание на то, что все языковые константы, имеющие префикс COM_EXAMPLE_, необходимо определить в sys.ini языковом файле расширения. Остальные константы являются системными и их можно использовать в любом месте расширения без необходимости их описания в языковых файлах. Значения этих констант для текущего языка будут выводиться из системных языковых файлов, если соответствующий язык установлен в CMS Joomla!.

Приведем еще один пример блока <config> для системного плагина sef.

<config>
	<fields name="params">
		<fieldset name="basic">
			<field 
				name="domain" 
				type="url"
				description="PLG_SEF_DOMAIN_DESCRIPTION"
				label="PLG_SEF_DOMAIN_LABEL"
				filter="url"
				validate="url"
			/>
		</fieldset>
	</fields>
</config> 

Административная часть расширения

Все теги, касающиеся административной части расширения в файле манифеста расположены внутри тега <administration>. На практике только компоненты могут иметь как пользовательскую, так и административную часть в составе одного расширения, поэтому блок <administration> встречается только в файлах манифестов инсталляционных пакетов компонентов для CMS Joomla!. Административный блок файла манифеста может иметь несколько дочерних тегов, имеющих различное предназначение для процесса установки компонента. Рассмотрим эти блоки по порядку.

Для добавления пункта меню компонента в меню "Компоненты" главного меню Joomla! используется тег <menu> и <submenu>. Например, этот блок может иметь следующий вид:

<menu>COM_EXAMPLE</menu>
<submenu>
	<menu link="anoption=avalue">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
	<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>

В результате после установки компонента в пункт меню Компоненты основного меню Joomla! будет добавлен новый пункт и его подпункты в соответствии с указанными параметрами.

Название пункта меню, который будет добавлен в меню Компоненты после его инсталляции, указывается в качестве значения тега <menu>. В теге <submenu> можно указать ряд дополнительных пунктов меню, которые будут потомками пункта меню с названием компонента. Чаще всего подменю используются для перечисления основных функциональных разделов в компоненте или перечисления сущностей, которыми управляет компонент.

Перечислим доступные в теге <menu> атрибуты:

• link – ссылка, по которой перейдет пользователь, нажав на соответствующий пункт меню
• img – относительный путь к файлу изображения, которое будет показано возле пункта меню (16x16 пикселей)
• [текстовый_параметр] – произвольный параметр, который будет добавлен к запросу при формировании ссылки пункта меню. Например, нажав на пункт меню <menu view="cpanel">COM_EXAMPLE</menu> пользователь перейдет посылке index.php?option=com_example&view=cpanel.

Как и родительский тег <extension>, тег <administration> может иметь дочерний тег <files>. В нем перечисляются файлы и папки, которые будут копироваться в административную часть сайта при установке компонента. В корне установочного пакета создается директория admin, в которой помещается структура папок и файлов административной части компонента. Тег <files> внутри <administration> может иметь следующий вид:

<files folder="admin">
	<folder>controllers</folder>
	<folder>helpers</folder>
	<folder>models</folder>
	<folder>sql</folder>
	<folder>tables</folder>
	<folder>views</folder>
	<filename>access.xml</filename>
	<filename>[имя_компонета].php</filename>
	<filename>config.xml</filename>
	<filename>controller.php</filename>
	<filename>index.html</filename>
</files>

Вся структура папок и файлов вместе с их вложенными элементами будет скопирована по пути:

Как и корневой блок файла манифеста, блок <administration> может содержать вложенный тег <languages> с дочерними тегами <language> для описания языковых файлов для административной части компонента. Здесь логика размещения и подключения языковых файлов аналогична той, которая описана выше в разделе Языковые файлы. Наиболее современным является подход, когда языковые файлы для административной части сайта также включаются в состав компонента. При этом директория admin в корне установочного пакета должна содержать папку language, в которой языковые файлы имеют аналогичные имена и так же расположены в подпапках с названием тега языка. Для копирования директории language соответствующий тег <folder> должен содержаться в родительском теге <files folder="admin">, а при описании языковых файлов в теге <languages> они также будут добавлены в системную директорию (для административной части это administrator/language).

Приведем пример описания <files> и <languages> блоков внутри тега <administration> для копирования языковых файлов компонента:

<administration>
	...
	<files folder="admin">
		<folder>controllers</folder>
		<folder>helpers</folder>
		<folder>language</folder>
		<folder>models</folder>
		<folder>sql</folder>
		<folder>tables</folder>
		<folder>views</folder>
		<filename>access.xml</filename>
		<filename>[имя_компонета].php</filename>
		<filename>config.xml</filename>
		<filename>controller.php</filename>
		<filename>index.html</filename>
	</files>
	<languages folder="admin">
		<language tag="en-GB">language/en-GB/en-GB.[имя_компонента].ini</language>
		<language tag="en-GB">language/en-GB/en-GB.[имя_компонента].sys.ini</language>
		<language tag="ru-RU">language/ru-RU/ru-RU.[имя_компонента].ini</language>
		<language tag="ru-RU">language/ru-RU/ru-RU.[имя_компонента].sys.ini</language>
	</languages>
	…
</administration>

В файле sys.ini при этом, чаще всего описываются следующие языковые константы:

• название и описание компонента из тегов файла манифеста <name> и <description>
• константы, содержащие названия пунктов меню
• константы с названиями и описаниями полей формы настроек компонента, которые содержатся в файле config.xml

Особенностью файла sys.ini является то, что он всегда подключается в административной части компонента вне зависимости от контекста. Соответственно в него имеет смысл помещать только те языковые константы, которые используются вне компонента (список выше). Остальные константы, которые используются непосредственно внутри устанавливаемого компонента, должны находиться в языковых ini файлах без суффикса sys (en-GB.[имя_компонента].ini).

Стоит также обратить внимание, что для компонента файл config.xml должен находиться в корне директории admin и участвовать в описании файлов в теге <files>, находящегося внутри блока <administration>, как в примере выше.

Установочный SQL скрипт

Стандартный инсталлятор в Joomla! позволяет выполнить произвольный sql скрипт при установке или удалении расширения в Joomla!. Для этого нужно написать соответствующие файлы с расширением sql и поместить их в папку sql в корне расширения. Например, пусть это будут файлы sql/example.install.sql, который будет выполняться при установке расширения, и sql/example.uninstall.sql, для выполнения sql при удалении расширения. Содержание этих sql файлов может быть, например, следующее:

Для файла example.install.sql:

CREATE TABLE IF NOT EXISTS `#__example_extension_table` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(255) NOT NULL,
  `ordering` int(11) NOT NULL DEFAULT '0',
  `state` tinyint(3) NOT NULL DEFAULT '1',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB  DEFAULT CHARSET=utf8 AUTO_INCREMENT=1;

Для файла example.uninstall.sql:

DROP TABLE IF EXISTS `#__example_extension_table`;

Как видим, в инсталляционном файле создается новая таблица базы данных с именем #__example_extension_table, где префикс #_ будет заменен на префикс таблиц базы данных, указанный в настройках Joomla!, а при удалении расширения эта таблица будет удалена из базы данных.

Чтобы соответствующие скрипты были выполнены, необходимо добавить теги <install> и <uninstall> в корневой тег файла манифеста и указать папку sql в дочерних элементах тега <files>. Для этого в файл манифеста можно добавить следующий код:

<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>

<files>
	...
	<folder>sql</folder>
	...
</files>

Здесь элемент <sql> может содержать один или более дочерних <file> элементов, каждый из которых описывает один sql файл. Его драйвер базы данных описывается в атрибуте driver, а кодировка в атрибуте charset.

Для большинства расширений папка sql с соответствующими файлами должна быть расположена в корне установочного пакета расширения. Исключение составляют компоненты, для которых папка sql помещается внутрь папки admin. Ее копирование должно производиться в папку административной части компонента, поэтому папка sql участвует в перечислении файлов и папок административной части:

<administration>
	...
	<files folder="admin">
		…
		<folder>sql</folder>
		…
	</files>
	...
</administration>

SQL скрипт для обновления

Начиная с Joomla! 1.6 появилась возможность обновления расширений в соответствии с их версиями. Описание всех возможностей системы обновления расширений в Joomla! заслуживает отдельной статьи. Здесь же стоит упомянуть о том, что в корневой блок файла манифеста мы можем добавить тег <update>, который в свою очередь может содержать дочерний тег <schemas> с указание параметров для обновления базы данных. Например, этот блок может содержать код:

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

При этом в папке sql должна быть расположена подпапка updates, содержащая файлы обновления структуры и данных в базе данных приложения. Это должны быть sql файлы с названиями, точно соответствующими версии расширения. Например, если у пользователя установлено расширение 1.0.0 и он устанавливает расширение версии 1.1.0, то в папке sql/updates должен находиться файл 1.1.0.sql с изменениями для этой версии.

Инсталляционный php скрипт

Для выполнения произвольного php кода перед установкой, после установки или в процессе удаления или обновления расширения, можно указать специальный php файл в теге <scriptfile>, дочернем от корневого тега в файле манифеста. Например:

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

Этот файл должен содержать класс с именем [имя_расширения]InstallerScript. Для плагинов обязательно необходимо включать имя группы (например, plgsystempluginname). Установочные пакеты библиотек не поддерживают выполнения php скриптов. Приведем структуру этого класса ниже вместе с доступными для определения функциями:

class [имя_расширения]InstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function __construct(JAdapterInstance $adapter);
 
	/**
	 * Called before any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function preflight($route, JAdapterInstance $adapter);
 
	/**
	 * Called after any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function postflight($route, JAdapterInstance $adapter);
 
	/**
	 * Called on installation
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function install(JAdapterInstance $adapter);
 
	/**
	 * Called on update
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function update(JAdapterInstance $adapter);
 
	/**
	 * Called on uninstallation
	 *
	 * @param   JAdapterInstance  $adapter  The object responsible for running this script
	 */
	public function uninstall(JAdapterInstance $adapter);
}

Краткое описание функций:

• __construct – конструктор класса
• preflight – вызывается перед выполнением какого-либо рода действий
• postflight – вызывается после выполнения какого-либо рода действий
• install – вызывается при выполнении установки расширения
• update – вызывается при выполнении обновления расширения
• uninstall – вызывается при выполнении удаления расширения

Сервер обновлений расширения

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

Значением тега <server> должен быть url адрес xml файла с описанием версий расширения, на основе которого CMS Joomla! сможет сделать вывод о необходимости обновления данного расширения. Приведем пример блока <updateservers>:

<updateservers>
	<server type="extension" priority="1" name="BoxApp Updates">http://boxapp.net/updates/joomla/plugins/plg_content_disqusforcontent.xml</server>
</updateservers>

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

Упаковка расширения

Зачастую установочный набор файлов и папок расширения распространяется в виде zip архива. Его нужно упаковать так, чтобы файлы и папки, расположенные в корневой директории инсталляционной сборки (например, файл манифеста [имя_расширения].xml) находились в корне архива, а не в его подпапках (файловая структура в архиве аналогична созданной корневой директории инсталляционной сборки). Хорошей практикой считается называть архив, как и расширение вместе с префиксом (например, com_example.zip, plg_system_example.zip, tpl_example.zip и т.д.) в нижнем регистре.

Инсталлятор Joomla! имеет внутренние механизмы, позволяющие предварительно распаковать инсталляционный архив во временную директорию сайта перед установкой, поэтому пользователь расширения может сразу использовать собранный архив для установки расширения. Исключение составляют расширения, которые требуют для работы другое расширение и поставляются вместе. Например, для работы компонента обязательно нужно установить вместе с ним плагин. В таких случаях установочный архив может называться com_example_UNZIPFIRST.zip или com_example_UNZIPME.zip. Перед установкой его нужно предварительно распаковать. Внутри такого архива часто расположены несколько других инсталляционных архивов других расширений и инструкция по их установке. Хотя более правильным способом выхода из ситуации, когда в составе инсталляционного пакета поставляется сразу несколько расширений Joomla!, считается сборка специального установочного пакета (package), который в свою очередь является расширением Joomla!, имеет отдельный файл манифеста, набор архивов расширений и устанавливается через Менеджер расширений Joomla!. Но про этот тип расширений и особенности их сборки стоит рассказать отдельно.

Примеры

Сообщество Joomla! очень большое, что позволяет найти большое количество готовых решений для данной CMS в виде расширений. Большое количество расширений Joomla! собрано и каталогизировано на официальном сайте extensions.joomla.org. Каждое из них может служить примером для сборки и оформления собственных расширения. К тому же много расширений поставляется непосредственно в составе CMS Joomla!, они также могут служить примерами для подготовки собственных сборок.

Команда BoxApp активно занимается разработкой бесплатных расширений для CMS Joomla!, которые можно скачать в разделе загрузок. Там же можно найти описания и документацию для наших расширений. Их тоже можно использовать в качестве образца для подготовки и оформления собственных установочных пакетов.