Расширения внутри Bitrix

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

Для чего нужны расширения

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

С одной стороны вы можете просто подключить скрипт там где надо, используя тег <script> или подключить через API Bitrix и не обязательно хранить JS в глобальном файле. Но тогда мы теряем возможность подгружать JS + CSS в любой момент времени используя библиотеку Bitrix.

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

Для начала стоит узнать где хранить наши расширения иначе API Bitrix работать не будет, они должны находится в папке:

local/js/папка_с_раширениями/расширение

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

Простое расширение

Чтобы наше расширение можно было подключить, у нас внутри обязательно должен быть конфигурационный файл config.php. Опишем простое подключение css и js файлов:

main/config.php<? if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();

return [
    'css' => './style.css',
    'js' => './script.js',
];

Немного стилизуем наше расширение:

main/src/style.css.hello-world {
    font-size: 40px;
    font-style: italic;
    color: blueviolet;
}

Напишем простой JavaScript код:

main/src/script.jsimport './styles.css';

document.addEventListener("DOMContentLoaded", () => {
    document.querySelector("body").innerHTML = "<h1 class='hello-world'>Hello world from ext</h1>";
});

Открываем файл где собираемся вызвать наше расширение и подключаем его:

index.php<? require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");
Bitrix\Main\UI\Extension::load("myextensions.myext");

Если все сделали правильно, на экране должны увидеть надпись.

Runtime расширений

Runtime позволяет выполнить отложенное подключение экстеншна на страницу. Может оказаться полезным, когда функционал показывается на странице не сразу, например в открывшемся pop-up.

Поучимся рантаймить наши расширения, для этого удаляем строчку с подключением нашего расширения:

index.phpBitrix\Main\UI\Extension::load("myextensions.myext");

И удалим слушатель отслеживания загрузки DOM дерева чтобы получилось так:

main/src/script.jsimport './styles.css';

document.querySelector("body").innerHTML = "<h1 class='hello-world'>Hello world from ext</h1>";

Далее открываем консоль на нашей странице и пишем следующий код:

BX.Runtime.loadExtension('myextensions.myext')

Если все сделали правильно, на экране должны увидеть надпись.

Зависимости расширений

К примеру, мы разбили функционал и написали целый общий модуль который будет использоваться для другого расширения. Так скажем сделали свое API / Библиотеку / Зависимость, не важно.

В расширение utils, размещу две функции в объекте:

utils/script.jsBX.HM.Utilis = {

    sum: function (a, b) {
        return a + b;
    },

    multiplication: function (a, b) {
        return a * b;
    },
}

В первом расширении подключу зависимости в config.php:

main/config.php<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) die();

return [
	'css' => './style.css',
	'js' => './script.js',
	'rel' => [
		'myextensions.utils'
	]
];

Теперь, можно использовать свои функции внутри первого расширения:

main/script.jsconsole.log(BX.HM.Utilis.sum(1,2))
console.log(BX.HM.Utilis.multiplication(2, 2));

Namespace в расширении

Пространства имен можно опредилить несколькими способами, в самом скрипте, например:

main/src/script.jsBX.namespace("BX.Пространство.Имен")

Или в файле bundle.config.js:

main/bundle.config.jsmodule.exports = {
    namespace: 'BX.Пространство.Имен',
};

Данная опция добавляет в window объект соответствующий строке namespace, через точку указывается вложенность объекта:

/* eslint-disable */
this.BX = this.BX || {};
(function (exports) {
    'use strict';
}((this.BX.Пространство.Имен = this.BX.Пространство.Имен || {})));
//# sourceMappingURL=dist.js.map

Plugins в расширении

main/config.phpplugins: {
// переопределяет параметры Babel, можно указать собственные параметры Babel
// подробная информация https://babeljs.io/docs/en/options
// если указать false, то код будет собран без транспиляции
babel: boolean | Object,

// дополнительные плагины Rollup, которые будут выполняться при сборке бандлов
custom: Array<string | Function>,

// в документации данное свойство не добавили, данная опция позволяет разрешать использование плагинов или отключать
// по дефолту false
resolve: Boolean
},

Minification в расширении

Данная опция будет крайне полезная если будете собирать к примеру Vue приложение. Включает или отключает минификацию, по умолчанию отключено:

main/config.php// может принимать объект настроек Terser:
// false — не минифицировать (по умолчанию)
// true — минифицировать с настройками по умолчанию
// object — минифицировать с указанными настройками
minification: boolean | object,