Bitrix произвольные поля

ОПИСАНИЕ УСТАНОВКИ И НАСТРОЙКИ РЕШЕНИЯ

Bitrix произвольные поля (bitrix custom fields)
Идентификатор модуля: rozmuar.bcf


1. ТРЕБОВАНИЯ

Продукт: 1С-Битрикс: Управление сайтом или Битрикс24 в коробке, ядро D7.
Модули: «Информационные блоки» (iblock) — должен быть установлен.
PHP: 7.4 или новее.
СУБД: MySQL.
Права: администратор портала.

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


2. УСТАНОВКА

2.1. Откройте в панели управления раздел Marketplace — Установленные решения
(адрес /bitrix/admin/partner_modules.php).

2.2. Найдите в списке «Bitrix произвольные поля (bitrix custom fields)» и
нажмите «Установить». Подтвердите установку.

При установке модуль:
- регистрируется в системе;
- создаёт таблицу rozmuar_bcf_value (развёрнутый снимок значений) и индекс
 по полям ELEMENT_ID, PROPERTY_ID;
- регистрирует пользовательский тип свойства инфоблока и обработчики событий
 информационных блоков (OnIBlockPropertyBuildList,
 OnBeforeIBlockElementAdd, OnBeforeIBlockElementUpdate,
 OnBeforeIBlockElementDelete, OnAfterIBlockElementAdd,
 OnAfterIBlockElementUpdate);
- запускает отсчёт демонстрационного периода (5 дней).

2.3. ОБЯЗАТЕЛЬНО ПОСЛЕ УСТАНОВКИ — СБРОСИТЬ КЕШ.

Поле «Выбор элементов инфоблока» использует AJAX-контроллер, который
регистрируется через файл .settings.php. Чтобы платформа его увидела, после
установки (или после обновления с версии ниже 0.2.0) очистите кеш:

Настройки — Настройки продукта — Автокеширование
(адрес /bitrix/admin/cache.php) — кнопка «Очистить весь кеш».

Без этого шага в поле «Выбор элементов инфоблока» левая колонка «Все элементы»
будет пустой (в ней выводится сообщение о причине).


3. СОЗДАНИЕ СВОЙСТВА

3.1. Откройте Контент — Информационные блоки — тип инфоблока — нужный
инфоблок — Свойства (или «Настроить», вкладка «Свойства»).

3.2. Добавьте свойство. В колонке «Тип» выберите
«Произвольные поля (конструктор форм)».

3.3. Задайте код свойства (по нему значение читается в шаблоне, например ACF)
и символьный код, сохраните.

Свойство всегда одиночное (не множественное) — один набор полей на элемент.
Множественность обеспечивают типы «Повторитель» и «Галерея» внутри набора.


4. НАСТРОЙКА НАБОРА ПОЛЕЙ

Откройте свойство на редактирование и перейдите на вкладку «Дополнительно».
Здесь находится конструктор полей. Кнопка «Добавить поле» добавляет строку.

Для каждого поля задаются:
- Код — латиница, цифры, знак подчёркивания; ключ поля в значении;
- Метка — подпись поля в форме элемента;
- Тип — один из типов (см. пункт 4.1);
- Инструкция — подсказка под полем для редактора;
- Обязательное — проверка заполнения при сохранении элемента.

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

4.1. Дополнительные настройки по типам полей:

- Число, Ползунок — минимум, максимум, шаг.
- Список, Флажки, Переключатель, Группа кнопок — список вариантов построчно
 в формате «значение : подпись», признак множественности, признак
 «разрешить пустое значение».
- Галерея — максимальное количество изображений.
- Сообщение — текст сообщения (выводится в форме как есть, значение не
 хранится).
- Видео — отдельных настроек нет; редактор вставляет ссылку в карточке
 элемента.
- Выбор элементов инфоблока — инфоблок из списка (показываются только
 доступные вам), признак «несколько» (по умолчанию включён), лимит
 количества.
- Группа полей, Повторитель — вложенный конструктор подполей (та же форма,
 вложенность до 5 уровней).

Сохраните свойство.


5. ЗАПОЛНЕНИЕ В КАРТОЧКЕ ЭЛЕМЕНТА

Откройте Контент — инфоблок — элемент на редактирование. У свойства
отображается форма настроенных полей:

- Изображение, Файл, Галерея — стандартный выбор файла платформы (не вставка
 ссылки). Файлы сохраняются в каталог /upload/rozmuar.bcf/.
- Видео — вставьте ссылку на YouTube, Vimeo или прямую ссылку на видеофайл;
 под полем появится предпросмотр.
- Выбор элементов инфоблока — две колонки: слева «Все элементы» (с
 постраничной подгрузкой и поиском по названию сверху), справа «Выбранные».
 Перенос — перетаскиванием или двойным щелчком, крестик — убрать, порядок в
 «Выбранных» задаётся перетаскиванием.
- Повторитель — кнопка добавления группы, удаление и сортировка групп.

5.1. Ограничение на объём загрузки.

Одновременная загрузка большого количества или объёма файлов ограничена
настройками PHP post_max_size и upload_max_filesize. При превышении форма
предупредит и не сохранит изменения (чтобы не потерять данные). Крупные файлы
загружайте частями или увеличьте лимиты PHP.


6. ВЫВОД ЗНАЧЕНИЯ В ШАБЛОНЕ

Значение приходит плоским массивом «код => значение» в элементе VALUE:

   $res = CIBlockElement::GetByID($elementId);
   $element = $res->GetNextElement();
   $props = $element->GetProperties();
   $data = $props['ACF']['VALUE'];

Примеры по типам:

   // строка, текст, число, дата, цвет — скалярное значение
   echo htmlspecialcharsbx($data['headline']);

   // визуальный редактор — уже санитизированный HTML
   echo $data['body'];

   // изображение — идентификатор файла
   $img = CFile::GetPath($data['photo']);

   // галерея — массив идентификаторов файлов
   foreach ($data['gallery'] as $fileId) {
       echo '<img src="' . CFile::GetPath($fileId) . '">';
   }

   // выбор элементов инфоблока — массив идентификаторов в заданном порядке
   $ids = $data['related'];
   $rs = CIBlockElement::GetList(['SORT' => 'ASC'], ['ID' => $ids], false, false,
       ['ID', 'NAME', 'DETAIL_PAGE_URL']);
   while ($row = $rs->GetNext()) { /* ... */ }

   // группа полей — вложенный массив
   echo $data['author']['name'];

   // повторитель — массив вложенных массивов
   foreach ($data['features'] as $item) {
       echo $item['title'], ': ', $item['text'];
   }

Для отчётов и произвольных SQL-выборок доступен развёрнутый снимок значения в
таблице rozmuar_bcf_value (колонки ELEMENT_ID, PROPERTY_ID, GROUP_INDEX,
FIELD_CODE, FIELD_TYPE, VALUE_TEXT, VALUE_FILE_ID).


7. ОБНОВЛЕНИЕ МОДУЛЯ

Обновления приходят через систему обновлений 1С-Битрикс
(адрес /bitrix/admin/update_system.php) и устанавливаются автоматически.
После обновления с версий ниже 0.2.0 повторите сброс кеша (пункт 2.3).


8. УДАЛЕНИЕ

Marketplace — Установленные решения — модуль — «Удалить».

- Без флага «Сохранить данные» удаляется таблица rozmuar_bcf_value; события
 и тип свойства снимаются с регистрации.
- Значения в свойствах инфоблока и загруженные файлы при удалении модуля не
 стираются.
- Счётчик демонстрационного периода намеренно сохраняется (переустановка не
 продлевает демо-период).


9. ДИАГНОСТИКА

- В поле «Выбор элементов инфоблока» левая колонка пустая.
 Причина: не сброшен кеш после установки или обновления. Решение: пункт 2.3.
 В самой колонке выводится точная причина (не выбран инфоблок, контроллер
 недоступен, нет доступных элементов).

- Сообщение «BX.ajax недоступен на этой странице».
 Причина: страница открыта вне стандартной административной панели.
 Решение: используйте штатную карточку элемента.

- Не сохраняются значения при загрузке многих файлов.
 Причина: превышен post_max_size. Решение: пункт 5.1.

- Некорректные символы в значениях на сайте с кодировкой cp1251.
 Модуль поддерживает cp1251; проверьте, что константы SITE_CHARSET и
 LANG_CHARSET заданы корректно.

- В карточке элемента показана плашка «режим просмотра».
 Причина: истёк демонстрационный период (5 дней). Решение: приобретите
 решение на Marketplace. Сохранённые данные и вывод на сайте продолжают
 работать в любом случае.

Техническая поддержка: info@rozmuar.ru
Время работы с 9:00 до 19:00
сайт rozmuar.ru.

Техподдержка по почте info@rozmuar.ru
или в telegram @shaadanio