Создание модуля

Партнерские модули отличаются от стандартных модулей следующим:

• ID модуля - полный код партнерского модуля, который задается в формате: код_партнера.код_модуля.

  Часть код_партнера постоянна для партнера (задается в карточке партнера). Часть код_модуля вводится партнером при добавлении нового модуля. Эти коды должны быть алфавитно-цифровыми, но первым символом не может быть цифра, и код неким образом должен соответствовать сути модуля. Например, для модуля форума желательно задать код forum. Тогда полный код будет mycompany.forum. Использование точки для разделения кода партнера и кода модуля необходимо, иначе ваш модуль не будет виден в списке установленных решений Marketplace, а попадет в список системных модулей, что является некорректной ситуацией.

  Важно! Код модуля обязательно должен быть задан в нижнем регистре, иначе не будет работать метод IncludeModule.
  
  Код не должен начинаться с цифры - это может помешать установке модуля. Также запрещается использование подчеркивания "_".

• В файле /install/index.php кроме той информации, которая задается в любом стандартном модуле, необходимо еще указать:

$this->PARTNER_NAME = "Имя партнера - автора модуля"; 
$this->PARTNER_URI = "http://www.mysite.ru";

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

  Инфоблоки или таблицы БД?

При создании собственных модулей у разработчиков часто возникает вопрос: при написании собственного модуля что целесообразнее: использование инфоблоков или собственные таблицы? Ответ на этот вопрос зависит от решаемой задачи. Наличие в Bitrix Framework инфоблоков не означает обязательности их использования для реализации своих модулей.

Инфоблоки - это универсальность. По этой причине:

• Инфоблоки часто избыточны по своим возможностям;
• При использовании инфоблоков разработчик может работать с модулем как с обычным компонентом, не нужно дорабатывать API (и описывать его).

Собственные таблицы - это прежде всего производительность. Используя свои таблицы, разработчик:

• может сделать модуль куда более быстродействующим, чем если бы делал модуль со стандартным API;
• при разработке собственного API, принимает на себя всю ответственность по безопасной работе своего модуля;
• должен подумать о том, что с его кодом будут работать другие разработчики: комментарии и документация.

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

• Внедряемся в любой пункт меню в админке (блог).
• Marketplace (группа в социальной сети компании 1С-Битрикс)
• Пользовательские поля в собственном модуле (блог)
• Написание модуля на D7+ORM (блог)

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

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

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

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

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

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

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

• Скопируйте в неё все файлы для полной сборки.
• Заархивируйте папку /.last_version в формат .zip или .tar.gz

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

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

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

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

Если метод используется более чем в одном месте, выносите его в класс 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	?>

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

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

1	RegisterModule("mymodule");

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

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

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

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

Библиотеку не стоит размещать в папке /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" => "Своя страница пользователей"
            ); 
      } 
   } 
}

  Структура обновления модуля

Файлы папки с обновлением:

• /install/version.php - файл содержит номер версии обновления и дату его выпуска. Обязательный файл.
• description.* - содержит описание обновления, где * - идентификатор языка в системе. Например, описание обновления модуля на русском языке будет содержаться в файле description.ru, на английском - description.en. Обязательный файл.
  В описании допустимо использование html тегов: <b>,<i>,<u>,<li>,<ul>,<span>, <br>
• updater.php – файл запускается при установке обновления. С помощью этого файла выполняются действия для обновления на новую версию. Необязательный файл.
• version_control.txt - служит для организации связи между версиями модулей. Файл содержит ссылки на версии модулей, от которых зависит данное обновление. Например, файл может содержать iblock,13.8.0. Это означает, что данное обновление будет установлено, если в системе установлен модуль Информационные блоки версии не ниже 13.8.0. Либо модуль Информационные блоки не установлен вообще. Необязательный файл.

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

• Создайте каталог с названием версии обновления. Например, 0.0.2, 0.0.5 и т.д.
• Скопируйте в созданную папку файлы и каталоги обновления модуля.
• Заархивируйте папку в формат .zip или .tar.gz.

В результате должно получиться, например, 0.0.2.zip, 0.0.5.zip. Например, папка с обновлением может иметь следующую структуру:

  updater.php

Структура апдейтера

Апдейтер может создаваться в двух формах. При этом в каждом конкретном обновлении может присутствовать только какая-то одна.

• Файл /updater.php в корне папки с обновлением. Этот файл будет запускаться на выполнение в качестве апдейтера.
• Папка /updater в корне папки с обновлением. В качестве апдейтера будет запускаться файл index.php в ней.

Второй способ обычно используется если для выполнения апдейтера нужны какие-то дополнительные файлы: языковые ресурсы, файлы с данными и тому подобное.

Описание

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

В каждом обновлении может быть только один updater.php. Но может и не быть ни одного, если требуется обновить только ядро.

Апдейтер может выполнить PHP-код. При этом есть набор архитектурных ограничений, которые необходимо учитывать.

Ограничения

• Обновления устанавливаются на все модули, которые входят в лицензию и [dw]присутствуют на сайте[/dw][di]Установлен модуль или нет, не имеет значения[/di]. Это надо учитывать при написании кода апдейтера.
• Обновления могут переустанавливаться несколько раз. Соответственно код апдейтера должен учитывать возможность многократного запуска.
• Апдейтер выполняется один раз непосредственно перед копированием файлов обновления из папки обновления в ядро на одном хите. Если за один хит обновляются несколько версий одного модуля, то их апдейтеры выполняются последовательно в соответствии с их версиями. Если за один хит обновляются несколько модулей, то выполняются апдейтеры всех этих модулей, но межмодульный порядок их выполнения не определен.
• АПИ текущего обновления [dw]недоступен на хите обновления[/dw][di]В случае использования нового кода в апдейтере будет получена ошибка: Class 'Имя\Класса' not found[/di]. А если есть циклические межверсионные зависимости, которые связывают несколько версий одного модуля, то будет недоступен АПИ всех этих обновлений. Использование нового АПИ в коде updater.php невозможно. Использование любого АПИ в коде апдейтера возможно, но не рекомендуется.
• При выполнении апдейтера доступен и он, и вся папка с обновлением.

  Обновление

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

Механизм апдейтеров (updater.php) служит именно для того, чтобы применить необходимые изменения к тем частям сайта, которые не являются ядром. С помощью этого механизма можно привести структуру базы данных, системные и публичные файлы в соответствие с текущей версией ядра.

Если возникла необходимость скопировать файлы в обновлении самостоятельно, то нужно использовать:

$updater->CopyFiles("install/classes", "modules/quintura.search/classes");

В этом случае файлы из папки /install/classes, находящиеся в папке обновления, скопируются в папку /local/modules/quintura.search/classes.

При выпуске последующих обновлений может возникнуть потребность установить его зависимость от новых модулей. Ссылки на версии модулей, от которых зависит данное обновление, содержатся в файле version_control.txt. Но необходимо помнить, что само обновление с зависимостью не будет по умолчанию требовать установки указанных модулей. В этом случае возможны два варианта:

1. Обновление всё равно устанавливать, проверять присутствие нужного модуля уже в функционале модуля.
2. Добавить в код обновления проверку на нужный модуль, и при его отсутствии выводить ошибку пользователю. Обновление не будет установлено, если присвоить переменной $errorMessage строку сообщения.

  Предварительные настройки

Чтобы выполнить установку модуля через партнерскую систему обновлений необходимо:

• в карточке партнера указать Код партнера, который будет использоваться как код для собственных модулей, и Лицензионный ключ, который будет использоваться для тестирования альфа-версий обновлений, доступных только автору модуля по этому ключу.



• собрать и загрузить на сервер компании "1С-Битрикс" дистрибутив модуля и обновления.
• установить модуль (либо его обновление).

  Загрузка модуля

Для загрузки модуля выполните следующее:

• Перейдите на страницу Ваши решения.
• На странице перейдите по ссылке Добавить решение, и в открывшейся форме

  

  заполните следующие поля:
  • Код - в поле обязательно указывается полный код партнерского модуля в формате код_партнера.код_модуля. Часть код_партнера постоянна для партнера (задается в карточке партнера). Часть код_модуля вводится партнером при добавлении нового модуля. Эти коды должны быть алфавитно-цифровыми с первым алфавитным символом, и код неким образом должен соответствовать сути модуля. Например, для модуля можно задать код mycar. Тогда полный код будет alexey.mycar. Пример класса модуля, в котором этот код модуля используется, содержится в приложении.
  • Активность - при отмеченной опции модуль будет отображаться в списке модулей.
  • Бесплатное решение - при отмеченной опции модуль будут бесплатным, то есть доступным всем. При снятом флажке появятся дополнительные поля, в которых надо отобразить:
    • Наличие триального периода;
    • Срок действия триального периода;
    • Цену модуля.
      Примечание: Если необходимо сменить текущую цену, то, поменяв значение цены, вы фактически отправляете уведомление в Партнерский отдел «1C-Битрикс», который активирует новую цену.

    • Разрешить партнерские скидки. При установленной опции другим партнерам будет разрешено покупать ваш модуль со скидками соответствующими статусу партнера.
  • Логотип – с помощью кнопки Выберите файл укажите путь к изображению, которое будет отображаться в списке модулей. (В разных браузерах выглядит по разному.)
  • Редакции, с которыми работает решение (обязательный) – в списке выберите редакции для которых предназначено решение.
  • Решение включает в себя – в списке обязательно указываются сущности, которые имеются в модуле: Компоненты, Мастер создания, Модуль, Переводы или Шаблоны сайта.
  • Адаптивность – указывается поддерживает ли решение возможность работать на разных типах устройств.
  • Поддержка композита – устанавливается флажок, если решение поддерживает технологию Композитный сайт.
  • Совместимо с Сайты24 – содержит блоки или шаблоны для Сайтов24.
  • Совместимо с PHP8 – решение работает на актуальной версии языка, поддерживаемой платформой.
  • Категория – указывается категория, к которой относится решение. Если вам не хватает категорий, то вы можете написать в техподдержку компании «1С-Битрикс» с просьбой добавить необходимую категорию.
  • Архив с полной сборкой решения – сюда вы загружаете архив со своим решением.
    Примечание: система обновлений автоматически переводит языковые файлы из Win-1251 в UTF-8, если у клиента выбрана кодировка сайта UTF-8. Если разница в версиях только в кодировке языковых файлов, то размещать надо только Win-1251 версию. Если разница в коде, то рекомендуется вынести эту разницу в языковые файлы.

  • CRM-виджет Битрикс24 – скопируйте и вставьте URL из кода CRM-виджета в вашем Битрикс24, чтобы клиент мог бы вам написать прямо с витрины.
  • Описание решения на Русском языке – в данной секции задаются значения следующих полей:
  • Юридическое название продукта – юридически значимая часть лицензионного договора и сопутствующих бухгалтерских документов. Изменение названия происходит только через процедуру модерации.
  • Опциональное название лицензии – конкретная версия решения.
  • Маркетинговое название – оно выводится на витрине. Если не заполнено, то на витрине будет выводиться юридическое название.
  • Описание решения – описание решения;
  • Описание установки решения – описание установки решения;
  • Описание техподдержки и контактных данных – индивидуальные контактные данные для техподдержки решения. Если поле не заполнено, то пользователям будут показаны реквизиты из карточки партнера.
  • Ссылка на демо-версию – ссылка на сайт с демо-версией;
  • Пользовательское соглашение от разработчика – укажите собственный текст соглашения для клиентов, с которым он соглашается при установке. При пустом поле будет выводиться стандартное соглашение.
  • Видео – указывается путь к [dw]видеоролику[/dw][di]Ссылки в формате https://www.youtube.com/embed/NX6d6v3U6cA[/di].
  • Вебинары – ссылки на ваши вебинары по загружаемому решению.
  • Скриншоты – можно загрузить скриншоты решения. (5 скриншотов)
  • Счётчик Google Analytics – подключение счетчика в карточку своего решения, будут фиксироваться просмотры карточки.
  • Подключить Я.Метрику – можно подключить Яндекс.Метрика (Необходимо указание идентификатора.)
• Сортировка среди своих модулей – значение, установленное в этом поле, определит порядок приложения в списке ваших приложений.
• Сохраните внесенные изменения.

В результате модуль будет добавлен в список ваших персональных модулей.

  Загрузка обновлений

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

• Перейдите на страницу Ваши решения.
• Перейдите по ссылке Обновления в колонке действий. Откроется страница Версии решения:



• Чтобы загрузить обновление воспользуйтесь ссылкой Загрузить новую версию. На странице Загрузка обновления для решения «название_решения» с помощью кнопки Выберите файл укажите путь к архиву с обновлением.
• Нажмите кнопку Загрузить.
• После загрузки архива на странице Обновления модуля «название_модуля» в поле Тип укажите тип обновления:
  • Альфа – альфа-версия обновления, доступная для загрузки только копии продукта с ключом, который указан в карточке партнера, предназначена для тестирования обновления;
  • Бета - бета-версия обновления, которая может быть установлена, если включена соответствующая опция в настройках Главного модуля;
  • Стабильное - окончательная стабильная версия обновления:
• Нажмите кнопку Сохранить.

  Расшифровка ошибок

При загрузке модуля (или обновления) в Marketplace выдается сообщение: Неверное содержимое архива с обновлением. Возможные причины:

• В файле /install/version.php не задана версия модуля;
• В файле /install/index.php не указан $MODULE_ID;
• В файле /install/index.php не указан PARTNER_NAME (Название партнера, разработчика модуля);
• В файле /install/index.php не указан PARTNER_URI (Адрес партнера, разработчика модуля);
• В файле /install/index.php не верно указано имя класса.

  Иконки

В качестве параметра иконки для страницы и пункта меню класс CSS.

"icon" => "mnu_my_module",
"page_icon" => "my_module",

Стили прописываются в файле /local/modules/my_module/install/themes/.default/my_module.css

/*Menu icon*/
#fcmch_menu_icon {background-image:url(icons/my_module/mnu_my_module.gif);}
#fcmch_page_icon {background-image:url(icons/my_module/my_module.gif);}

Сами иконки необходимо загрузить в папку модуля /local/modules/my_module/install/themes/.default/icons/my_module/. При установке модуля содержимое папки /themes модуля должно быть скопировано в папку /local/themes/ и удалено оттуда при деинсталяции модуля.

  Кастомизация меню с помощью Событий

Вариант кастомизации административного меню - это создать свой обработчик события OnBuildGlobalMenu. Так можно вставить новые разделы, пункты или секции с подпунктами. Или изменить что угодно в уже сформированном меню. Обработчик можно прописать например в файл /local/php_interface/init.php.

// DOC: http://dev.1c-bitrix.ru/api_help/main/events/onbuildglobalmenu.php
AddEventHandler("main", "OnBuildGlobalMenu", "DoBuildGlobalMenu");

function DoBuildGlobalMenu(&$aGlobalMenu, &$aModuleMenu) {

   // пример формирования меню можно подсмотреть: /bitrix/modules/[module]/admin/menu.php
   // системные варианты parent_menu: global_menu_desktop, global_menu_content, global_menu_services, 
   //global_menu_store, global_menu_statistics, global_menu_marketplace, global_menu_settings

   // это на случай добавления новых пунктов или секций с подпунктами
   $aModuleMenu[] = array(
      "parent_menu" => "global_menu_settings", 
      "icon" => "default_menu_icon",
      "page_icon" => "default_page_icon",
      "sort"=>"900",
      "text"=>"APC Opcode Cache",
      "title"=>"APC INFO",
      "url"=>"/local/admin/apc.php",
      "more_url"=>array(),
   );

   // а это на случай вклинивания в уже существующей секции
   foreach($aModuleMenu as $key => $menu) :

      // наверно достаточно идентифицировать только по $menu["items_id"]
      if ($menu["parent_menu"] == "global_menu_settings" && $menu["section"]=="TOOLS" && $menu["items_id"]=="menu_util") :
         // пункт добавится в конец списка существующих пунктов в секции
         $aModuleMenu[$key]["items"][] = array(
            "text" => "APC Opcode Cache",
            //"title" => "APC INFO",
            "url" => "/bitrix/admin/apc.php",
            "more_url" => array(),
         );
      endif;
      
   endforeach;


   /*
   // пример своего глобального раздела меню

   // нужен хотя бы один пункт в глобальном разделе, иначе раздел не появится
   $aModuleMenu[] = array(
      "parent_menu" => "global_menu_custom",
      "icon" => "default_menu_icon",
      "page_icon" => "default_page_icon",
      "sort"=>"100",
      "text"=>"Custom Item Text",
      "title"=>"Custom Item Tille",
      "url"=>"/bitrix/admin/custom_item.php",
      "more_url"=>array(),
   );

   // если нужно добавить глобальный раздел меню, то его можно отдать тут или заранее выше добавить в $aGlobalMenu
   $arRes = array(
      "global_menu_custom" => array(
         "menu_id" => "custom",
         "page_icon" => "services_title_icon",
         "index_icon" => "services_page_icon",
         "text" => "Custom text",
         "title" => "Custom title",
         "sort" => 900,
         "items_id" => "global_menu_custom",
         "help_section" => "custom",
         "items" => array()
      ),
   );

   return $arRes;
   */

} // function DoBuildGlobalMenu

  Сохранение настроек модуля

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

<?//Save form
if($request->isPost() && $request["save"] && check_bitrix_sessid()){
    foreach($aTabs as $aTab){
        if(count($aTab['OPTIONS'])) {
            __AdmSettingsSaveOptions($module_id, $aTab["OPTIONS"]);
        }
    }
}?>

должен стоять перед выводом формы:

<!-- FORM TAB -->
<?php
$tabControl = new CAdminTabControl("tabControl", $aTabs);
?>
<? $tabControl->Begin(); ?>
<form method="post" action="<?=$APPLICATION->GetCurPage();?>?mid=<?=htmlspecialcharsbx($request["mid"]);?>&lang=<?=LANGUAGE_ID?>" name="<?=$module_id;?>">
    <? $tabControl->BeginNextTab(); ?>
        <?
        foreach ($aTabs as $aTab)
        {
            if(count($aTab['OPTIONS'])) {
                //$tabControl->BeginNextTab();
                __AdmSettingsDrawList($module_id, $aTab['OPTIONS']);
            }
        }
        ?>

    <? $tabControl->BeginNextTab(); ?>

        <?require_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/admin/group_rights.php");?>

    <? $tabControl->Buttons(array('btnApply' => false, 'btnCancel' => false, 'btnSaveAndAdd' => false)); ?>

    <?=bitrix_sessid_post(); ?>
</form>
<? $tabControl->End(); ?>
<!-- X FORM TAB --> 

  Мастер установки

Примерный порядок создания мастера установки решения:

• Создайте папку мастера, и его базовые файлы с папками. Они почти одинаковые для каждого мастера, можно взять готовые и внести в них.
• Скопируйте файлы публички в папку /public, шаблоны в папку /templates. Основная логика установки должна быть описана в файле services/.services.php. Массив $arServices содержит описание последовательности запуска файлов из соответствующих подкаталогов services.

На сами файлы никаких ограничений нет, можно, например, создать файл events.php для установки почтовых событий и написать в нем вызов API для их создания в случае, если они уже не были созданы.

В качестве примера можно рассмотреть уже готовые мастера установки решений, имеющиеся в дистрибутивах продуктов на Bitrix Framework. Например: Мастер создания интернет-магазина в «1C-Битрикс: Управление сайтом», расположенный в папке: /bitrix/wizards/bitrix/eshop.

  Особенности

Особенности, которые необходимо учитывать:

В публичной части инсталлятора файл index.php должен именоваться как _index.php - иначе будет ошибка при инсталляции. Такого именования достаточно, что бы мастер автоматом в конце установки заменил текущий index.php на ваш.

Все файлы с кодировкозависимыми символами должны располагаться внутри папки ~/lang/[ru|en]/ и должны быть созданы в языковых сообщениях, когда это требуется. Система обновлений для партнерских модулей перекодирует все файлы, путь к которым содержит /lang/. Например, для файла ./portal/site/services/.services.php путь должен быть таким: ./portal/lang/[ru|en]/site/services/.services.php. Для установщика сервиса (подключается автоматически) ./portal/site/services/папка_сервиса/установщик.php путь такой: ./portal/site/services/папка_сервиса/lang/[ru|en]/установщик.php.

  Переустановка сайта

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

В установочных скриптах необходимо проверять на существование создаваемую сущность. Если сущность уже установлена – пропускать установку. В установочных файлах можно делать return. Пример:

<?
if (!CModule::IncludeModule("iblock"))
return;
$typeResult = CIBlockType::GetByID("news");
if ($typeResult->Fetch()) //Установлен тип Новости? Пропускаем установку
return;
//Создание типа инфоблока
?>

  Инфоблоки, блоги и прочее

Чтобы прописать ID инфоблоков в файлы публичной части, надо запускать после копирования файлов публички и установки инфоблока метод CWizardUtil::ReplaceMacros, где первый параметр - это путь к файлу, а второй - массив подстановок, например, чтобы заменить #NEWS_IBLOCK_ID# на число, нужно сделать так:

CWizardUtil::ReplaceMacros(WIZARD_SITE_PATH."/news/index.php", array("NEWS_IBLOCK_ID" => $iblockID));

Пример вывода настроек инфоблока:

$iblockID = 2;
$result = CUserOptions::GetOption("form", "form_element_".$iblockID); var_export($result); 
echo "<br><br>"; 
CModule::IncludeModule("iblock");
 $arFields = CIBlock::getarraybyid($iblockID);
 foreach ($arFields["FIELDS"] as $id => $arField) unset($arFields["FIELDS"][$id]["NAME"]); var_export($arFields["FIELDS"]); 

  Многосайтовость

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

  Включаемые области

Файлы с включаемыми областями, которые подключаются в шаблоне и хранятся в папке с шаблоном сайта (/local/templates/имя_шаблона/includes/), при установке сайта мастером, не перекодируются в UTF-8. Правильно будет разместить файлы с шаблонами включаемых областей в папке /includes/ в корне.

  Другие моменты

• Чтобы мастер установки решения запускался сразу из Marketplace, после загрузки модуля, необходимо чтобы он лежал по адресу: /local/modules/модуль/install/wizards/партнер/мастер/.
• Во всех исполняемых файлах, не находящихся в публичной части, первая строка должна выглядеть так:

  if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();

• В установочных файлах можно пользоваться глобальными объектами $DB, $DBType, $APPLICATION, $USER;
• Пользователь, запускающий мастер, будет авторизован как администратор (ID=1).

  Бесплатный модуль

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

• В кабинете партнера в списке решений выбрать нужный модуль.
• На вкладке Тестирование нажать кнопку Установить и указать во всплывающем окошке адрес сайта, на который будет установлен модуль:



• После этого в новой вкладке браузера откроется страница вида http://адрес_сайта/bitrix/admin/update_system_partner.php?addmodule=код_партнера.код_модуля и будет произведена установка модуля..

Этот вариант также подходит и для установки платного модуля в демо-режиме.

  Платный модуль

Для установки платного модуля вы можете использовать 2 варианта:

1. Через активацию купона.
   • На вкладке Тестирование в карточке решения выписать купон указав ФИО, e-mail (на него будет отправлен купон с подробной инструкцией, если проставлена соответствующая галочка), решение, на которое выписывается купон.

     

     Использовать опцию Продление при первой установке не нужно. Для уведомления клиента установите флажок в Отправить купон покупателю.

   • Клиенту в административной панели сайта в разделе Marketplace > Обновление решений на вкладке Активация купона ввести купон в специальном поле. Нажать Установить и следовать инструкциям.
   
   
2. Через привязку лицензионного ключа
   • Клиенту в административном разделе сайта в раздел Marketplace > Обновление решений и скопировать код лицензионного ключа.

     

   • В карточке модуля в разделе Клиенты (http://partners.1c-bitrix.ru/personal/modules/clients.php?ID=<код_модуля>) добавьте клиента и укажите его код лицензионного ключа в соответствующем поле. Остальные поля необязательны для заполнения: информация добавится автоматически после установки модуля.
   • После этого в административном разделе на сайте клиента в разделе Обновление решений появится модуль, готовый к загрузке и установке.

  Установка решения и обновлений

Установка стороннего решения и получение обновлений по нему описана в курсе Установка и настройка

Введение

Предлагаемый вашему вниманию скрипт является больше примером для оптимизации разработки и экономии времени, чем готовым решением. Скрипт разработан сотрудниками ТП "1С-Битрикс" для облегчения рутинных операций по сборке обновлений модулей.

Скачать скрипт.

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

Возможно для кого-то это покажется простой и интересной задачей, но для других она кажется рутинной и постоянно бегать по директориям в поисках нужного файла и так пофайлово собирать обновления довольно утомительно.

  Настройки

Код модуля:

$arSettings["MODULE_ID"] = 'mail';

Директория относительно корня сайта куда будут складываться обновления:

$arSettings["U_PATH"] = '/iupdate/';

Массив директорий содержимое которого будет прочитано, но глубже чтение не будет проводиться:

$arSettings["DIR_READ_NOFOLLOW"] = array(
    $arSettings["MODULE_PATH"].'lang/',
);

Массив директорий, имя которых будет добавлено, но не будет произведено чтение их содержимого:

$arSettings["DIR_NOFOLLOW"] = array(
    $arSettings["MODULE_PATH"].'install/db/',
    $arSettings["MODULE_PATH"].'install/images/',
    $arSettings["MODULE_PATH"].'install/themes/',
);

Массив директорий, которые будут пропущены при чтении (построении списка):

$arSettings["DIR_SKIP"] = array();

Массив игнорируемых имен:

$arSettings["FILE_NAME_SKIP"] = array(
    '.',
    '..',
    '.hg',
    '.hgignore',
    '.svn',
    '.csv',
);

Массив игнорируемых файлов:

$arSettings["FILE_SKIP"] = array(
    $arSettings["MODULE_PATH"].'install/version.php',
    $arSettings["MODULE_PATH"].'version_control.txt',
);

Массив для updater.php, при наличии необходимых директорий на основании этих данных будет построен файл обновления:

$arSettings["UPDATER_COPY"] = array(
    "install/js" => "js/main/core",
    "install/components" => "components",
);

  Что же скрипт умеет?

• Собирать обновления с необходимым набором файлов;
• Создавать файл описания на основании введенного текста;
• Создавать файл version.php с номером версии указанной в поле ввода и время создания обновления;
• Создание updater.php на основании файлов обновления и настроек
• Создание архива собранного обновления

  Уведомления

Начиная с версии ядра 11.5.6 в Bitrix Framework появляется возможность уведомлять администраторов о важных действиях, например что необходимо произвести конвертацию данных. Администратор увидит стикер под панелью инструментов, как в административном интерфейсе, так и в публичной части. Если одновременно должно вывестись несколько уведомлений, то они выведутся одно над другим.

Уведомления есть двух типов: первые администратор может закрыть, вторые уйдут только после выполнения действия (например полной конвертации).

Для использования этой возможности в собственных модулях используйте методы класса CAdminNotify.

Начиная с версии 12.0.0 класс CAdminNotify дает возможность создавать уведомления, зависящие от языка. Т.е. чтобы текст сообщения менялся при переключении языка. Для использования этой возможности при вызове CAdminNotify::Add добавьте ключ LANG.

  Пример

$arFields = array(
   'MODULE_ID' => 'catalog',
   'TAG' => 'VWS',
   'MESSAGE' => '123 ENGLISH 123',
   'LANG' => array(
      'ru' => 'Русский',
      'de' => 'Deutsch'
   )
);

$intID = CAdminNotify::Add($arFields);

Для русского и немецкого языков будут показано соответственно Русский и Deutsch. Для всех остальных языков будет показано сообщение 123 ENGLISH 123.

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

  Подсказки пользователям в интерфейсе

С версии модуля Библиотека интерфейсов (UI) 17.6.3 рекомендуется использовать js-расширение ui.hint, показывающее всплывающие подсказки пользователям на странице.

Подключение на PHP-странице:

\Bitrix\Main\UI\Extension::load("ui.hint");

  Как использовать библиотеку

В html-коде достаточно указать у элемента атрибут data-hint c текстом:

В js-коде необходимо инициализировать подсказку. Будут созданы подсказки для всех дочерних элементов контейнера:

Пример:

<?
\Bitrix\Main\UI\Extension::load("ui.hint");
?>

<script type="text/javascript">
    BX.ready(function() {
        BX.UI.Hint.init(BX('my-container'));
    })
</script>

<div id="my-container">
   <div>
        Подсказка 1  
        <span data-hint="<?=Loc::getMessage('MY_HINT_1')?>"></span>
    </div>

    <div>
        Подсказка 2 
        <span data-hint="<?=Loc::getMessage('MY_HINT_2')?>"></span>
    </div>
</div>

  Использование в JavaScript

При формировании верстки в js, можно получить элемент для вставки из текста:

containerElement.appendChild(
    BX.UI.Hint.createNode("Моя вторая подсказка.")
);

  Шаг 1. Создание модуля из скрипта

На первом шаге заполняются необходимые информация:

• Заполняются группы полей данные о разработчике и данные о новом модуле;
  Внимание! Код партнера должен строго соответствовать тому, что выводится в карточке партнера. Код модуля заполняется латиницей. Название и описание будут выводиться в списке модулей. Все это подробно описано в документации для разработчиков.

• Опция Переписать существующие файлы означает, что необходимо перезаписать информацию, если такой модуль уже установлен в системе;
• При необходимости в группе настроек Компоненты модуля выбираются компоненты для включения в дистрибутив создаваемого модуля, т.е они должны быть установлены на текущей установке в папке /bitrix/components/. Эти компоненты будут скопированы в папку /install/ нового модуля. При установке автоматически скопируются из этой папки в /bitrix/components/, и соответственно удалятся при деинсталляции.
  Внимание! Все пользовательские компоненты должны находиться в папке /bitrix/components/. Системные компоненты находятся в папке /bitrix/components/bitrix/, содержимое которой обновляется системой обновлений и не должно изменяться пользователями. Об это подробно описано в документации по созданию компонентов 2.0.

• Если у модуля имеются административные страницы, то с помощью кнопки Обзор... можно их включить в дистрибутив, они попадут в папку /admin/ нового модуля. При установке будут созданы ссылки на эти страницы в папке /bitrix/admin/. Кроме того, они появятся в основном административном меню.
• Для перехода к следующему шагу служит кнопка Продолжить, после нажатия которой модуль появится в списке решений, и можно продолжать его разработку уже в ядре:

  

  Шаг 2. Выделение языковых фраз

На данном шаге происходит:

• Сканирование всех php-файлов модуля, если в коде нового модуля имеются кириллические символы, то выводится список этих страниц.

  Система автоматически определяет кодировку utf8 или cp1251. В дальнейшем скрипты будут автоматически перекодированы в кодировку сайта (а перед архивацией - в cp1251, как требует документация).

• Языковые фразы сохраняются в соответствующий lang-файл, а вместо фраз в код страниц модуля вставляется вызов GetMessage. В качестве ключа используется транслитерация исходной фразы - это позволяет в автоматическом режиме создавать понятные ключи:

  

  Будьте осторожны! В процессе такой работы исходный файл переписывается. При разборе учитывается html, php, js, css, \.

• Языковой файл создается автоматически:

  

  • Если файл был редактирован, то новые фразы дописываются в конец.
  • Если фразы были в исходном файле (или ранее по коду), то они используются повторно.
  • Если ключи совпадают, в конце дописывается цифра.
  • Для скриптов папки /admin/ в самое начало скрипта дописывается код подключения ядра, если не был найден. Это необходимо для работы языковых функций.

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

  Шаг 3. Создание архива

На данном шаге:

• Все скрипты модуля будут сконвертированы в кодировку cp1251, затем будет создан архив .last_version.tar.gz в папке /bitrix/tmp/<название.модуля>/:

  

  Здесь можно изменить версию модуля в одноименном поле.

• Далее файл .last_version.tar.gz необходимо загрузить в карточке партнера Marketplace.



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

  Шаг 4. Сборка обновления

Данный шаг автоматизирует сборку обновлений любого модуля: все файлы модуля, измененные после даты, которая хранится в install/version.php, попадают в архив обновления. Также сборка обновлений проверяет дату изменения файлов в установленных компонентах, копирует их в папку модуля, затем помещает в архив с обновлением. В обновлении лежит файл updater.php, который обновляет компоненты на сайтах клиентов. Перекодировка файлов из cp1251 в utf8 и обратно происходит автоматически.

• Если включить опцию Обновить дату и версию в ядре модуля, то исходный файл модуля будет переписан и следующие обновления будут собираться от текущей версии.
• В поле Описание обновления добавляется текстовая информация по изменениям в обновлении.
• В поле Скрипт обновления updater.php добавляется сам пользовательский скрипт обновления. По умолчанию в этом поле дан пример скрипта.
• После нажатия кнопки Продолжить будет создан архив с обновлением /bitrix/tmp/<модуль>/<версия_модуля>.tar.gz, который необходимо будет загрузить в карточке партнера Marketplace.

  Пример

У Конструктора модулей (bitrix.mpbuilder) для Marketplace есть возможность собирать обновления для своих модулей. При этом не важно, созданы они были при помощи Конструктора или "руками".

Например, имеем некий модуль, который предоставляет компоненты.

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

Выделенный серым фрагмент кода был добавлен. Обратите внимание, что слово Да уже присутствовало ранее в языковом файле.

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

  Выделение языковых фраз

Для этого открываем Шаг 2 "Выделение языковых фраз" и выбираем свой модуль в списке. Он показывает список файлов (за пределами /lang), которые содержат кириллические символы.

Нажмите Продолжить. Теперь языковые фразы оказались в языковом файле шаблона. Старые фразы были использованы, а новые дописаны в конец.

  Сборка обновления

Перейдите к Шагу 4 через меню (третий шаг сборки архива модуля пропустите). Он использует дату и версию модуля из файла /install/version.php для сборки обновления.

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

Если были изменены уже установленные компоненты модуля в /bitrix/components, на этом этапе можно автоматически скопировать изменения в модуль. Тут есть два варианта:

• если компоненты модуля лежат без указания пространства имен (как в моем примере), то надо указать пространство имен для синхронизации изменений (оно же подставится в код updater.php).
• в противном случае ничего указывать не надо (например, /install/components/bestpartner/news.line).

  Кодировки

Установка сайта на основе Bitrix Framework возможна в двух кодировках на выбор: cp1251 и UTF-8. При установке в UTF-8 система автоматически конвертирует файлы в нужную кодировку.

Конвертацию проходят все языковые файлы (находящиеся внутри папок /ID языка/ как в самом модуле, так и в мастере.

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

  Возможные ошибки

Если вы тестируете установку решения под ОС Windows, необходимо учитывать следующую особенность: файлы, начинающиеся с точки, в UNIX подобных системах считаются скрытыми. И Windows при копировании таких файлов с ftp, сетевого диска (может быть и в других случаях) ставит этим файлам атрибут «скрытый». При этом все файлы с таким атрибутом при установке в Windows обычно не находятся веб-сервером. Отсюда могут появляться ошибки:

• Установщик не находит файл .access.php (или другой системный файл), хотя тот физически присутствует на диске в нужном каталоге
• Установщик не меняет кодировку файлов .description.php, .parameters.php.

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

Еще один вариант решения этой проблемы — изначально назвать файлы без точки в начале и переименовать их во время установки. Недостатки: большой риск забыть переименовать какой-либо файл, а также некоторое увеличение времени установки за счет дополнительных обращений к файловой системе.

  Настройка сайта

Настройка сайта проводится на этапе установки сервисов и включает в себя следующие шаги:

1. Создание сайта (если он еще не создан).
2. Копирование публичной части.
3. Копирование выбранного шаблона дизайна и регистрация его в объекте сайта.
4. Копирование выбранной цветовой схемы.
5. Установка настроек модулей и подстановка пользовательских данных, введенных на шаге настройки сайта.

Копирование данных проводится стандартной функции CopyDirFiles.

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

Лучше всего при копировании шаблона добавить к нему суффикс с ID сайта (template_s1), это позволит на разных сайтах иметь одинаковые шаблоны, но с разными цветовыми схемами. Либо просто не затереть одноименные шаблоны другого сайта.

На этом же этапе копируются и подставляются все вторичные шаблоны (шаблон для печати, шаблон мобильной версии, шаблон версии для ЛОВ).

Для установки настроек модулей используется стандартный класс COption. Замена макроса директории сайта (обычно #SITE_DIR#) делается с помощью функции WizardServices::ReplaceMacrosRecursive(WIZARD_SITE_PATH, Array("SITE_DIR" => WIZARD_SITE_DIR)), где:

• WIZARD_SITE_PATH — константа полного пути к сайту,
• WIZARD_SITE_DIR — константа директории сайта.

  Подстановка данных пользователя

Подстановка данных пользователя может выполняться двумя способами:

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

  Порядок установки

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

1. Создание самого сайта и установка его настроек.
2. Копирование публичной части сайта и рекурсивная замена макроса #SITE_DIR#.
3. Копирование выбранного на этапе установки шаблона сайта
4. Копирование выбранной на этапе установки темы сайта поверх шаблона, с перезаписью.
5. Создание всех типов инфоблоков.
6. Создание инфоблоков и подстановка замена соответствующих макросов функцией CwizardUtil::ReplaceMacros(Путь к файлу, array("Имя макроса без #" => Значение на замену)). Так как второй параметр - массив, то в одном файле можно произвести сразу несколько замен.
7. Настройка блогов, форумов, статистики, рабочего стола и прочее.

  Пользователи

Импорт заранее подготовленного набора пользователей используется редко. В случае необходимости используется стандартный класс CSVUserImport, входящий в состав модуля main.

  Инфоблоки

Данные инфоблоков в мастере создания сайта хранятся в виде xml файлов, сформированных с помощью стандартного экспорта инфоблоков Bitrix Framework. Эти файлы, а также папки с дополнительными файлами, получающиеся в результате экспорта, обычно помещаются в каталог /xml/ID языка/. В самом простом случае файл установки инфоблока включает следующий код:

if(!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)
	die();
if(!CModule::IncludeModule("iblock"))
	return;

$iblockID = WizardServices::ImportIBlockFromXML(
	 WIZARD_SERVICE_RELATIVE_PATH."/xml/".LANGUAGE_ID."/feedback.xml", 
	 "iblockCode", 
	 "iblockType", 
	 WIZARD_SITE_ID, 
	 $permissions = Array(
		 "1" => "X",
		 "2" => "R",
	 )
);

if ($iblockID < 1)
 return;

CWizardUtil::ReplaceMacros(WIZARD_SITE_PATH."/feedback/new.php", array("FEEDBACK_IBLOCK_ID" => $iblockID));

Функция

WizardServices::ImportIBlockFromXML
  (function ImportIBlockFromXML
     ($xmlFile, 
      $iblockCode, 
      $iblockType, 
      $siteID, 
      $permissions = Array()
     )
) 

В случае поддержки многосайтовости (или просто решения для Bitrix Marketplace) к символьному или внешнему коду инфоблока после его установки следует добавить и ID сайта. Следует заметить, что в функцию ImportIBlockFromXML подставляется код инфоблока без добавления ID сайта, само добавление происходит уже потом через создание метод Update класса CSite.

  Шаблоны

При создании мастера с использованием файла wizard.php шаблоны располагаются в каталоге /site/templates/. Для уменьшения проблем с кодировками можно помещать их в каталог /site/templates/ID языка/, но лучше помещать русский текст в языковые файлы и вставлять через GetMessage. Кроме стандартных файлов каталог шаблона должен содержать следующие файлы:

• description.php — файл описания шаблона, содержит массив $arTemplate. Обычно содержит два ключа: NAME для названия шаблона и DESCRIPTION для его описания. Набор ключей можно расширить, например, сортировкой, и установкой шаблона по умолчанию, если вы реализовали это переопределив метод WizardServices::GetTemplates.
• screen.png — скриншот шаблона в нормальном размере. Обычно нигде не отображается.
• preview.png — скриншот шаблона в уменьшенном размере, отображается на шаге выбора шаблона.
• /themes/ - каталог с цветовыми схемами данного шаблона. Имеет ту же структуру, что и каталог самого шаблона, но содержит лишь зависящие от цветовой схемы файлы. Обычно это файлы стилей, screen.png и preview.png темы, а также некоторые шаблоны компонентов.

   Проблема дублирования и ее решение

Дублирование — одна из самых явных проблем, которая может привести к следующим последствиям:

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

Хорошим примером проблемы дублирования является [dw]решение[/dw][di] С 1 февраля 2023 года продажа данного решения прекращена. [/di] «Официальный сайт государственной организации», версия от 03.08.2010. Это решение включает себя 8 различных видов сайта, частично отличающихся как своей структурой, так и набором демо-данных. А также четыре шаблона дизайна, которые можно использовать для любого вида сайта.

Отбросим файлы самой редакции платформы Bitrix Framework и оставим для анализа только модуль gossite и мастер установки bitrix:government. Вместе они имеют размер 274 МБ и состоят из 13 867 файлов и 7 940 каталогов. Эти цифры не назовешь маленькими.

Рассмотрим основные случаи дублирования в этом решении:

1. В модуле gossite есть каталог установки следующих кастомизированных и собственных компонентов: desktop, header, iblock.wizard, menu, support.ticket.list. В то же время в папке /public мастера установки bitrix:government можно увидеть папку /bitrix, содержащую набор компонентов и гаджетов. Сравнив список компонентов, мы увидим те же самые названия, и дополнительный компонент structure.visual. Все они копируются на этапе установки сервисов в скрипте /wizards/bitrix/government/site/services/files/bitrix.php следующим кодом:

   CopyDirFiles( 
   	WIZARD_ABSOLUTE_PATH."/site/public/".LANGUAGE_ID."/bitrix/",
   	WIZARD_SITE_PATH."/bitrix/",
   	$rewrite = false, 
   	$recursive = true
   );

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

   При беглом осмотре можно заметить, что каталог /video (15,7 МБ) из общих файлов дублируется также в четырех видах сайта, причем видеофайлы идентичны. А содержимое папки /upload из общих файлов частично дублируется для сайта прокуратуры.

   В папке /upload/ сайта прокуратуры присутствует каталог /iblock, дублирующий файлы для установки инфоблоков.

   Также в каталогах разных типов сайтов были другие полностью дублирующиеся файлы и каталоги, которые можно вынести в /common.
3. В базовом шаблоне дизайна (modern) в цветовых схемах продублировано много шаблонов компонентов из самого шаблона. Часть из них дублируются полностью, для части есть несколько отличающихся файлов. В последствии очень легко не внести изменения в какую-либо из цветовых схем и в итоге запутаться, где находится актуальная версия. Да и объем работы при правке этих шаблонов возрастает в несколько раз (по числу цветовых схем в шаблоне). Поэтому все дублирующиеся части из них лучше удалить.
4. В каталоге установки сервисов для каждого типа сайта создан отдельный набор данных для инфоблоков. Выбор, какой именно набор ставить производился в файле описания сервисов .services.php. С одной стороны это удобно, но с другой стороны дублирование информации сильно увеличивается за счет дополнительных файлов инфоблоков. Например, при одинаковых альбомах в фотогалерее, или одинаковых наборах документов.

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

Над последней версией дистрибутива решения были проведены работы по устранению указанных выше проблем. В конечном итоге после замены двух шаблонов дизайна новыми, дополнения демо-данных и прочих плановых доработок, совокупный размер мастера и модуля уменьшился до 141 МБ, а количество файлов и каталогов уменьшились до 8 889 и 4 588 соответственно.

  Другие советы по уменьшению размера дистрибутива

1. Не используйте в дистрибутиве большие видео/аудио файлы.
2. Исключайте из дистрибутива все кастомизированные шаблоны компонентов, которые в ходе разработки перестали где-либо использоваться
3. Выносите общие для всех дизайнов шаблоны компонентов в отдельный каталог. Для самостоятельных решений их можно просто вынести в .default шаблон сайта. В решениях для Bitrix Marketplace их стоит вынести в отдельный каталог и копировать на шаге установки шаблона дизайна (тем самым опять же уменьшая дублирование).
4. Для самостоятельных решений выносите мастер создания сайта из модуля в каталог /bitrix/wizards/. Это позволит избежать либо дублирования, либо дополнительного копирования мастера при установке решения.

  Кодировки и языковые файлы

1. Всегда выносите русский текст в языковые файлы, иначе в будущем возможны проблемы с кодировками. Например, при установке модуля внутри него смена кодировки происходит только для языковых файлов. Таким образом, устанавливая сайт в utf-8 и оставив русский текст в файле /install/components/пространство имен/имя компонента/templates/.default/template.php вы в итоге получите набор иероглифов.
2. При разработке/тестировании в Windows предварительно снимите флаг скрытости у всех файлов. При копировании файлов, начинающихся с точки (такие файлы считаются скрытыми в Unix подобных ОС) с сетевого диска Windows ставит им флаг «скрытый». При наличии этого флага при установке сайта под Windows файлы не обрабатываются. Перед сборкой архива с дистрибутивом желательно также предварительно проверить файлы на флаг скрытости.
3. При создании решения проверяйте соответствие кодировки файла .htaccess в вашем решении и в системе. При установке решения может произойти затирание этого файла, созданного системой. В результате этого могут не создаваться инфоблоки. Решения лучше создавать в Windows-1251, как и сам Bitrix Framework.

  Ядро Bitrix

1. При разработке решения для Bitrix Marketplace не оставляйте в публичной части системные файлы, которые могут перезаписать уже имеющиеся файлы у клиента. К ним относятся:
   • файл urlrewrite.php;
   • папка /upload;
   • любые системные файлы из папки /bitrix, в том числе шаблон .default;
   • Компоненты/гаджеты вне собственного пространства имен.
   Если есть необходимость все же добавить что-либо в системную папку, то разместите эти файлы отдельно и делайте предварительно проверку на существование.
2. При разработке самостоятельного решения с поддержкой многосайтовости выносите добавляемое в папку /bitrix в отдельную папку и копируйте вручную без перезаписи. Иначе при переносе публичной части при установке второго сайта у вас получится лишний набор файлов в /папка_сайта/bitrix/.
3. При разработке самостоятельного решения не добавляйте никаких файлов в ядро Bitrix Framework напрямую. Если все же необходимо внести дополнительные файлы в ядро (например, свой шаблон бизнес-процесса), то такой файл нужно поместить внутри мастера создания сайта и переносить через копирование. В противном случае при переносе решения на более новую редакцию Bitrix Framework есть вероятность потери добавленных файлов.

  Инфоблоки, пользователи и свойства

1. Никогда напрямую не используйте ID инфоблока (пользователя, группы, значения свойства типа «список») где-либо, кроме файлов публичной части. В противном случае возможна ситуация, когда компонент/шаблон/метод класса обращается к данным по одному ID, а получает либо совершенно другие данные, либо их полное отсутствие. Возможные варианты решения:
   • Для компонентов и шаблонов передавать ID используемых инфоблоков/пользователей/групп/свойств через параметры вызова (описываются в файле .parameters.php)
   • Для собственных классов передавать необходимые ID инфоблоков/пользователей/групп/свойств либо при создании объекта класса, либо в качестве параметров его методов.
   • Если ID нигде не передается, то определять их по каким-либо признакам (обычно это символьный код (CODE) или внешний код (XML_ID)).
2. Внутри мастера установки проверяйте, что все прямые использования ID инфоблоков (пользователей, групп, значений свойств типа «список») заменены макросами. Макросы имеют вид #имя_макроса# и должны заменяться на этапе установки инфоблоков.
3. Убедитесь, что все макросы заменяются во время установки решения. Для замены можно использовать следующие функции:
   • CWizardUtil::ReplaceMacros(путь_к_файлу, Array("имя_макроса" => значение_для_замены));
   • WizardServices::ReplaceMacrosRecursive(путь_к_корневой_папке, Array("имя_макроса" =>значение_для_замены));

  Многосайтовость

Если предполагается возможность установки вторым/N-ным сайтом, то в начале всех абсолютных путей необходимо либо подставлять системную константу SITE_DIR, либо макрос (например, #SITE_DIR#), заменяемый в процессе установки решения.

Шаблоны

1. Если решение включает несколько шаблонов, следите, чтобы названия шаблонов компонентов в них были одинаковыми. Публичная часть одна и не известно какой из шаблонов сайта выберет пользователь.
2. Для уменьшения итогового размера решения выносите все одинаковые шаблоны компонентов в некоторую общую папку. В самостоятельном решении это может быть шаблон .default. В решении для Bitrix Marketplace — просто отдельная папка, из которой общие шаблоны компонентов должны быть скопированы на этапе установки шаблона сайта.

  Шаблон Битрикс24 и фрейм

При разработке приложений на основе шаблона Битрикс24, учтите, что этот шаблон нельзя открывать во фрейме.

  Почему нужна собственная документация

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

Какие проблемы решает собственная документация:

1. Трудности с подключением нового разработчика. Требуется довольно много времени на то, чтобы ему разобраться с уже реализованным функционалом.
2. Трудности с донесением изменений по архитектурной и функциональной части до других разработчиков.
3. Иногда могут возникать ошибки из-за использования устаревших функций, написанных другим разработчиком, но при беглом взгляде другого вроде решающих его задачу и так далее.
4. Сложности при планировании новых функциональных блоков.
5. Проблемы с поддержкой собственных решений в Маркетплейс.

Проблема комплексная, так как требует не только документирования исходного кода, но и написания документации для администраторов и пользователей. Другими словами, требуется сделать всё то, что делает вендор.

  Пользовательская и администраторская документация

Самое простое в этом комплексе - это создание администраторской и пользовательской документации. Причём с администраторской документацией всё может быть ещё проще, так как есть штатная возможность системы использовать подсказки к полям компонентов.

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

Создание такой документации не представляется сложным этапом в работе. Её в состоянии выполнять сотрудники с уровнем "продвинутого пользователя". Здесь больше вопрос ресурсов, оплаты их труда, многие студии пренебрегают этим этапом.

  Документация для разработчиков

Сложность создания документации для разработчиков имеет объективные и субъективные основания. Объективные:

• Писать её, кроме самого разработчика, некому. Сторонний неквалифицированный сотрудник не сможет детально разобраться в коде. Держать отдельно квалифицированного программиста на написании документации по чужому коду - даже не роскошь, а глупость.
• Функционал никогда не выходит не то что в неизменном, а даже в законченном виде. Поэтому написание документации, как правило откладывается "на потом" и успешно забывается.
• Неверная организация процесса разработки не оставляет времени на написание документации. При сжатых сроках и несоответствующем бюджете разработчик стремится снизить свои трудозатраты.

Субъективная причина одна: психологическое неприятие разработчиком необходимости писать документацию.

Объективные трудности должны преодолеваться за счёт правильной организации процесса разработки. Субъективные - за счёт постоянной разъяснительной работы, терпеливого убеждения.

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

• осуществить показ человеческих подсказок по коду на уровне IDE;
• иметь возможность посмотреть описание чужого класса и быстро с ним разобраться;
• иметь возможность генерации списков todo на следующую итерацию или для себя.

В качестве инструментов можно использовать:

• doxygen
• PHPDocumentor
• phpdoctor

При использовании любого инструмента придётся разбираться с кодировками. Это особенность, связанная с Bitrix Framework: при выставленном в настройках проекта UTF-8, в коде ядра портятся комментарии.

  Скрипт и входные параметры

Создатель модуля имеет возможность автоматической работы с клиентами своего модуля. Функционал в полном объёме доступен только для платных модулей. Для бесплатных модулей есть возможность получать информацию о клиенте после их установки клиентом (метод action=list).

Реализуется функционал с помощью специального скрипта: http://partners.1c-bitrix.ru/add_client.php.

$md5 = md5($partner_id."|".$module_id."|".$key."|".$action."|".$salt);

  Результат работы

Скрипт возвращает два типа ответа (в текстовом формате):

OK
сообщение об успешно совершенном действии

ERROR
текст ошибки

  Примеры использования

//Добавим нового клиента
http://partners.1c-bitrix.ru/add_client.php?partner_id=&module_id=&key=&action=add&name=Anton%20Ezhkov&email=anton@bitrix.ru&site_url=www.1c-bitrix.ru&contact_person=Anton%20Ezhkov&phone=123123123&comments=Оплатил безналом&is_utf=Y&hash=

//Изменим информацию о клиенте
http://partners.1c-bitrix.ru/add_client.php?partner_id=&module_id=&key=&action=update&name=Антон Ежков&email=anton@bitrix.ru&site_url=www.1c-bitrix.ru&contact_person=Антон Ежков&phone=123123123&comments=Оплатил безналом, помогал в техподдержке&is_utf=Y&hash=

//Удалим ключ из клиентов модуля
http://partners.1c-bitrix.ru/add_client.php?partner_id=&module_id=&key=&action=delete&hash=

//Получим список клиентов указанного платного модуля
 http://partners.1c-bitrix.ru/add_client.php?partner_id=&action=list&module_id=&hash=