Структура полной сборки модуля

Просмотров: 66785
Дата последнего изменения: 09.03.2023

Сложность урока:

3 уровень - средняя сложность. Необходимо внимание и немного подумать.

Структура полной сборки

Полная сборка модуля предназначена для первоначальной установки модуля (когда этого модуля ещё нет у клиента или партнера).

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

/install/index.php - файл с описанием модуля, содержащий инсталлятор/деинсталлятор модуля.
/install/version.php - файл с номером версии модуля. Версия не может быть равной нулю. В файле можно использовать только двойные кавычки, одинарные работать не будут.
/include.php – подключаемый файл (файл подключается при подключении модуля во время выполнения скриптов сайта), в нем должны находиться включения всех файлов с библиотеками функций и классов модуля. В этом файле также объявляются используемые модулем константы, если они общие. Если же константы относятся к какому-либо классу модуля, то они объявляются в самом классе.

Все остальные файлы могут быть включены в модуль, если это необходимо.

Примечание: подробная информация о структуре файлов модуля.

Перед загрузкой модуля на сайт необходимо запаковать полную сборку модуля в архив. Для этого выполните следующее:

Создайте папку /.last_version.
Примечание: если разработка ведётся на компьютерах Mac, то название архива должно быть без точки.
Скопируйте в неё все файлы для полной сборки.
Заархивируйте папку /.last_version в формат .zip или .tar.gz

В итоге должен получиться архив с именем .last_version.zip (.last_version.tar.gz). Для типичного модуля полная сборка может иметь следующую структуру каталогов и файлов:

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

Полная сборка не влияет на обновление модуля и вообще не используется для этого. Она нужна только для первичного скачивания и установки нового модуля. Если в силу каких-то причин необходимо запретить загрузку обновлений для каких-то пользователей (через оплаченный период, например, или при новой версии), то достаточно отвязать клиента от модуля. Модуль у него останется, но обновляться он не сможет.

Полезные методы

WizardServices::SetFilePermission($path, $permissions)	по сигнатуре эквивалентен `$APPLICATION->SetFileAccessPermission($path, $permissions)`, но с более правильной логикой добавления прав доступа (не затирает существующие права).
WizardServices::AddMenuItem($menuFile, $menuItem, $siteID)	добавление пункта меню
WizardServices::IncludeServiceLang($relativePath, $lang = false, $bReturnArray = false)	подключает произвольный языковой файл сервиса
ImportIBlockFromXML($xmlFile, $iblockXmlID, $iblockType, $siteID, $permissions = Array())	импорт инфоблока.

Если метод используется более чем в одном месте, выносите его в класс WizardServices.

Инсталлятор и деинсталлятор

Инсталлятор и деинсталлятор размещаются в файле /local/modules/ID модуля/install/index.php. В нем должен быть описан класс, название которого совпадает с ID модуля. Например, так:

01	<?
02	Class mymodule extends CModule
03	{
04	    var $MODULE_ID = "mymodule";
05	    var $MODULE_NAME;
06	 
07	    function DoInstall()
08	    {
09	        global $DB, $APPLICATION, $step;
10	        $APPLICATION->IncludeAdminFile(GetMessage("FORM_INSTALL_TITLE"),
                                               $_SERVER["DOCUMENT_ROOT"]."/local/modules/mymodule/install/step1.php");
11	    }
12	 
13	    function DoUninstall()
14	    {
15	        global $DB, $APPLICATION, $step;
16	        $APPLICATION->IncludeAdminFile(GetMessage("FORM_INSTALL_TITLE"), 
                                               $_SERVER["DOCUMENT_ROOT"]."/local/modules/mymodule/install/unstep1.php");
17	 
18	    }
19	}
20	?>

Примечание: При описании модуля нужно наследоваться именно от CModule, потому что при добавлении ведущего слеша с CModule загрузка не пройдет по маске.

Метод DoInstall будет вызываться при нажатии на кнопку Установить в списке модулей административной панели. Соответственно, DoUninstall – при нажатии на кнопку Удалить.

Также в папке /install находятся файлы step1.php и unstep1.php. Если нужен многошаговый установщик, то следует создать файлы step1.php, step2.php и т.д. Задача установщика – зарегистрировать модуль в системе. На самом деле, для этого достаточно вызвать всего лишь одну функцию:

1	RegisterModule("mymodule");

Однако скорее всего для модуля понадобятся свои таблицы в БД и файлы. В таком случае, следует создать их в шагах инсталлятора (step1.php, step2.php и т.д.). Аналогично, в деинтсталляторе нужно сделать противоположные действия (удалить таблицы и файлы).

В качестве примера можно рассмотреть инсталляторы штатных модулей. Наиболее наглядный установщик у модуля Веб-Формы.

Примечание:

Подчеркивание в ID модуля использовать нельзя. При добавлении модуля система проверяет допустимые символы в коде модуля. Можно использовать латинские буквы + цифры. Учтите, что если название модуля начинается с цифр, то работать не будет (в PHP функция/класс не могут начинаться с цифр). Также не стоит использовать смешанный регистр в коде модуля.
Название класса модуля формируется аналогично ID модуля, с заменой точки на подчёркивание. Например, если ID модуля alexey.mycar, то класс будет: Class alexey_mycar .

Сторонние библиотеки

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

Библиотеку не стоит размещать в папке /local/modules/. Необходимые для работы модуля файлы лучше положить в ваш модуль, для удобства последующего обновления. Пользовательские же файлы с подобными файлами обычно кладутся в /local/php_interface/.

Пункт в меню админки

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

Пример использования события для добавления собственного пункта в Список пользователей:

AddEventHandler("main", "OnBuildGlobalMenu", "MyOnBuildGlobalMenu"); 
function MyOnBuildGlobalMenu(&$aGlobalMenu, &$aModuleMenu) 
{ 
   foreach($aModuleMenu as $k => $v)
   { 
      if($v["parent_menu"] == "global_menu_settings" && $v["items_id"] == "menu_users")
      { 
         $aModuleMenu[$k]["items"][] = Array(
               "text" => "Кастомный пункт пользователей",
               "url" => "user_custom.php?lang=".LANG,
               "title" => "Своя страница пользователей"
            ); 
      } 
   } 
}

Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.

Развернуть комментарии