Библиотека Битрикс BX

1С-Битрикс разработал для платформы библиотеку под названием BX, которая примерно на 80% повторяет всеми любимый jQuery с рядом отличий, среди которых как достоинства, так и недостатки. До определенного момента разработчики под битрикс мало смотрели в сторону библиотеки, но появился order_ajax.js который перевернул всё.

Достоинства

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

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

Библиотека BX имеет низкий уровень конфликтности с другими библиотеками или скриптами. В отличии от тех же плагинов jQuery, которые могут конфликтовать на уровне разных версий библиотеки.

Очень крутым плюсом на мой взгляд является надстройка с утилитами в библиотеке, которые позволяют повторить ряд функций PHP https://dev.1c-bitrix.ru/api_help/js_lib/kernel/utilits/bx_util.php. Значительно упрощает разработку.

Как это работает

Все файлы, скрипты и стили библиотеки находятся в папке /bitrix/js/main/core/, файл core.js это ядро самой библиотеки. Ядро определяет глобальный объект BX, который содержит статические методы для работы с событиями. По сути это аналог $ в jquery, с него начинаются все действия. Из папки /bitrix/js/main/core/ в большинстве нужны следующие файлы:

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

Для того чтоб это все заработало на страницах нужно подключить эти библиотеки через:

<? CUtil::InitJSCore(array(‘jquery’, ‘window’, ‘popup’, ‘ajax’, ‘date’)); ?>

Функция принимает параметры, названия бибилиотек из /bitrix/js/main/core/, которые нужно подключить в данный момент, только без префикса core. Если нам надо подключить всплывающие окна и аякс, вызов будет следующий:

<? CUtil::InitJSCore(array(‘popup’, ‘ajax’)); ?>

Приведенный выще код, подключит core_ajax.js и core_popup.js.

Функции JS API

Событие готовности DOM, подробнее
Утилиты PHP, подробнее
Функции поиска элементов в DOM, подробнее
Создание элементов в DOM, подробнее
Манипуляции с классами, подробнее
Data-атрибуты, подробнее
Манипуляции со стилями, подробнее
Функции обработки форм, подробнее
Обработка событий, подробнее
Proxy-функции, подробнее
Функции AJAX, подробнее
Система кастомных событий, подробнее
Работа со свойствами, подробнее
Ширина и высота элемента в DOM, подробнее
Изменение прозрачности элемента, подробнее

Событие готовности DOM

Событие готовности DOM-структуры

BXBX(function(){ });

jQuery$(function(){ });

BXBX.ready(function(){ });

jQuery$().ready(function(){ });

Аналоги PHP

BXBX.util.array_values(array);

BXBX.util.array_keys(array);

BXBX.util.array_merge(array);

BXBX.util.array_unique(array);

BXBX.util.in_array(array);

BXBX.util.array_search(array);

BXBX.util.trim(array);

BXBX.util.htmlspecialchars(array);

BXBX.util.htmlspecialcharsback(array);

BXBX.utill.preg_quote(array);

BXBX.util.str_pad(array);

BXBX.util.strip_tags(array);

Функции поиска элементов в DOM

Поиск по идентификатору:

BXlet object = BX('my_id');

jQuerylet array = $('#my-id');

Множественный рекурсивный поиск в DOM-структуре объекта:

BXlet array =
BX.findChildren(obParent, { tag: 'td', className: 'class-name' }, true);

let object = BX.findChild(obParent, { tag: 'td', className: 'class-name' }, true, true);

jQuerylet array = arParent.find('td.class-name');

Немножественный рекурсивный поиск в DOM-структуре объекта:

BXlet object = BX.findChild(obParent, {tag: 'div', className: 'class-name'}, true);

jQuerylet array = arParent.find('td.class-name:first');

let array = arParent.find('td.class-name').first;

Немножественный нерекурсивный поиск в DOM-структуре объекта:

BXlet object = BX.findChild(obParent, {tag: 'div', className: 'class-name'});

jQuerylet array = arParent.children('td.class-name:first');

Поиск по атрибутам (немножественный, нерекурсивный):

BXlet object = BX.findChild(obParent, {tag: 'div', attribute: { data-id:'167' }});

jQuerylet array = arParent.children('div[data-id=167]');

Поиск по свойствам (немножественный, нерекурсивный):

BXlet object = BX.findChild(obParent, {tag: 'div', property: { data-id:'167' }});

jQuerylet array = arParent.children('div[data-id=167]');

Поиск со сложной логикой (немножественный, нерекурсивный):

BXlet object = BX.findChild(obParent, function(el) { return !!el.tagName
&&
el.tagName.toUpperCase()==='DIV'
&&
el.hasAttribute('data-id'); });

jQuerylet array = arParent.children('div[data-id]');

Поиск среди родительских элементов DOM-структуры объекта:

BXlet parent = BX.findParent(object, {className : 'class-name'});

jQuerylet arParent = array.parents('.class-name:first');

Поиск предыдущих/следующих элементов DOM-структуры:

BXlet ob = BX.findNextSibling(object, {className : 'class-name'});

let ob = BX.findPreviousSibling(object, {className : 'class-name'});

jQuerylet ar = array.next();

let ar = array.prev();

Создание элементов в DOM

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

BXlet object = BX.create({
    tag: 'div',
    props: {name: 'val'},
    attrs: {'data-name': 'val'},
    style: {name: 'val'},
    events: {},
    children: {},
    text: '', // or
    html: '', // or
});

jQuery$('div')
.prop(name,val)
.data('name','val')
.css(name,val)
.on(…)
.append(…)
// or
.text('')
// or
.html('');

Устанавливает параметры объекта:

BXlet object = BX.adjust({
    node: object,
    props: {name: 'val'},
    style: {name: 'val'},
    events: {},
    children: {},
    // or
    text: '',
    // or
    html: '',
});

jQuery$(object)
.prop(name,val)
.css(name,val)
.on(…)
.append(…)
// or
.text('')
// or
.html('');

Добавляет объект внутрь другого объекта:

BXBX.append(object,parent);

jQuery$(object).appendTo(parent);

Удаляет объект из структуры:

BXBX.remove(object);

jQueryarray.remove();

Очищает объект от всех вложенных элементов:

BXBX.cleanNode(object);

jQueryarray.empty();

Манипуляции с классами

Добавляет класс к элементу:

BXBX.addClass(object, 'class-name');

jQueryarray.addClass('class-name');

Удаляет класс у элемента:

BXBX.removeClass(object, 'class-name');

jQueryarray.removeClass('class-name');

Переключает класс у элемента:

BXBX.toggleClass(object, 'class-name');

jQueryarray.toggleClass('class-name');

Проверяет наличие класса у элемента:

BXlet bHasClass = BX.hasClass(object, 'class-name');

jQuerylet bHasClass = array.hasClass('class-name');

Функция переключает наличие/отсутствие CSS-класса className у узла node или производит ротацию CSS-классов, если className массив:

BXBX.ready(function () {
    var body = document.querySelector("body")
    var btn = document.querySelector(".switch")

    BX.bindDelegate(
        document.body, 'click', {className: 'switch__label'},
        function () {
            BX.toggleClass(body, 'switch-bg');
            BX.toggleClass(btn, 'switch-border');
        }
    )
})

Data-атрибуты

Получает значение Data-атрибута:

BXlet value = BX.data(object,'name');

jQuerylet value = $(object).data('name');

Устанавливает значение Data-атрибута:

BXBX.data(object,'name','value');

jQuery$(object).data('name','value');

Манипуляции со стилями

Устанавливает css свойство у элемента:

BXBX.style(object,'name','value');

jQuery$(object).css('name','value');

Функции обработки форм

Отправляет форму на сервер:

BXBX.submit(obForm);

jQueryarForm.submit();

Устанавливает фокус на поле ввода:

BXBX.focus(object);

jQuery$(object).focus();

Передав id формы, функция найдет все элементы формы (input, select, textarea, button и др) и вернет их в виде массива:

BXlet dataForm = BX.findFormElements(BX("userForm"));

Обработка событий

Устанавливает функцию обработки события для элемента:

BXBX.bind(object, 'click', function() {});

jQuery$(object).on('click',function(){});

Proxy-функции

Инициализирует функцию с кастомной переменной this:

BXBX.proxy(function(params){ }, object);

jQuery$.proxy(function(params){}, object);

Пример получения исходного объекта в Proxy-функции:

BXBX.bindDelegate(object, 'click', {tagName : 'a'}, BX.proxy(onClick, this));
let onClick = function() {
    let target = BX.proxy_context;
}

jQuery$(object).on('click', $.proxy(onClick, this));
let onClick = function (event) {
    let target = event.target;
}

Функции AJAX

Отправляет POST запрос:

BXBX.ajax.post(url,{},function(res) {});

jQuery$.post(url,{},function(res) {});

Отправляет POST запрос и получает результат в виде объекта:

BXBX.ajax.loadJSON(url,{},function(res){});

jQuery$.getJSON(url,{},function(res) {});

Отправляет запрос и вставляет результат в объект (можно указать id):

BXBX.ajax.InsertToNode(url,object);

Система кастомных событий

Инициализирует глобальный обработчик события:

BXBX.addCustomEvent(window, 'onEvent', function_name);

jQuery$(document).bind('my.onEvent', function_name);

Отключает глобальный обработчик события:

BXBX.removeCustomEvent(window, 'onEvent', function_name);

jQuery$(document).unbind('my.onEvent', function_name);

Выполняет глобальный обработчики события:

BXBX.onCustomEvent(window, 'onEvent',[arg1,arg2,arg3]);

jQuery$.event.trigger('my.onEvent', [arg1,arg2,arg3]);

Инициализирует обработчик события для объекта:

BXBX.addCustomEvent(object, 'onEvent', function_name);

jQueryobject.on('my.onEvent', function_name);

Отключает обработчик события для объекта:

BXBX.removeCustomEvent(object, 'onEvent', function_name);

jQueryobject.off('my.onEvent', function_name);

Выполняет обработчики события для объекта:

BXBX.onCustomEvent(object, 'onEvent',[arg1,arg2,arg3]);

jQueryobject.trigger('my.onEvent', [arg1,arg2,arg3]);

Работа со свойствами

Функция BX.adjust() позволяет изменить свойства узла node:

BXBX.ready(function () {
    // деактивируем кнопку отправить
    var btn = document.querySelector(".form__submit");

    BX.adjust(btn, {
        props: {
            disabled: true
        }
    });

    // устанавливаем обработчик на отслеживание введенных данных
    BX.bindDelegate(document.body, 'keyup', {
        className: 'form__text'
    }, function () {
        var inputName = document.querySelector("[name='name']");
        inputName = inputName.value.length;
        var inputPhone = document.querySelector("[name='phone']");
        inputPhone = inputPhone.value.length; // Проверка на кол-во символов

        if (inputName && inputPhone >= 5) {
            BX.adjust(btn, {
                props: {
                    disabled: false
                }
            });
        } else {
            BX.adjust(btn, {
                props: {
                    disabled: true
                }
            });
        }
    });
});

Ширина и высота элемента в DOM

Функция BX.width() возвращает, или задает ширину, функция BX.height() возвращает, или задает высоту элемента DOM. Первым параметром передаётся элемент DOM. Если не передавать второй параметр, целое число, вернется значение ширины или высоты. Если передать, значение задается:

BXBX.ready(function(){
    const blocks = document.querySelectorAll(".width-item");
    BX.bindDelegate(document.body, 'click', {
        className: 'btn-showSize'
    }, function () {
        // пробегаемся по всем блокам
        blocks.forEach(function(item) {
            // ищем нужный блок по классу для определении ширины и высоты
            const block = BX.findChild(item, {
                "tag": "div",
                "class": "width-block"
            }, true);

            // ищем нужный блок по классу для вставки ширины
            const width = BX.findChild(item, {
                "tag": "span",
                "class": "res-width"
            }, true);

            // ищем нужный блок по классу для вставки ширины
            const height = BX.findChild(item, {
                "tag": "span",
                "class": "res-height"
            }, true);

            // предварительно очистим
            width.innerHTML = " ";
            height.innerHTML = " ";

            // Применяем функцию и добавляем результат
            width.insertAdjacentHTML("beforeend", "Ширина - " + BX.width(block));
            height.insertAdjacentHTML("beforeend", "Высота - " + BX.height(block));
        });
    })
})

Изменение прозрачности элемента

Метод BX.setOpacity() устанавливает уровень прозрачности элемента веб-страницы:

BXBX.ready(function () {
    var btn = document.querySelector(".resultOpacityDemo");
    BX.bindDelegate(document.body, 'change', {
        className: 'setOpacity-demo'
    }, function () {
        BX.setOpacity(btn, this.value / 100);
    });
});