Пользовательские блоки

Тема Seller 2.0 использует блочную архитектуру для построения страниц. Через панель управления темой можно управлять блоками на главной странице, в сайдбаре, карточке товара и других местах.

Блоки главной страницы

Состав и порядок блоков главной страницы задаётся в настройке «Блоки» (раздел «Сортировка блоков», ключ home__items_type_json). Каждый блок имеет собственную группу настроек с префиксом home__ и один или несколько вариантов отображения (типов).

Блоки с настройками в панели темы

Дополнительные шаблоны блоков

В каталоге html/blocks/ темы есть также блоки без собственных групп настроек в панели — их можно подключать вручную через include_template с параметрами props или как пользовательский блок в сортировке:

Медиа-блоки

Помимо блоков главной страницы, в теме есть медиа-области (раздел настроек media__):

Архитектура блоков

Все блоки следуют единой архитектуре:

1. Централизация — блоки хранятся в директории html/blocks/ темы
2. Дефолтные настройки — берутся из $theme_settings
3. Переопределение — через параметр $props
4. Типизация — разные типы отображения в отдельных файлах

Структура файлов блока

html/blocks/{block_name}/
├── {block_name}.html          # Основной файл с логикой
├── {block_name}_01.html       # Тип отображения 1
├── {block_name}_02.html       # Тип отображения 2
└── ...

Основной файл блока ({block_name}.html)

Основной файл отвечает за:

• Сбор дефолтных настроек из $theme_settings
• Переопределение настроек через $props
• Декодирование JSON-данных
• Вывод заголовка через компонент block-header
• Подключение нужного типа отображения

Шаблон основного файла:

{* DEFAULT PROPS *}
{$block_type = $theme_settings["home__block_type"]}

{$default_props = [
    "type" => $block_type,
    "subtitle" => $theme_settings["home__block_subtitle"]|default:"",
    "title" => $theme_settings["home__block_title"]|default:"",
    "items" => $theme_settings["home__block_items_type_json"]|default:[],
    "container" => true
]}

{* MERGE WITH PASSED PROPS *}
{if !empty($props)}
    {foreach $props as $key => $value}
        {$default_props[$key] = $value}
    {/foreach}
{/if}

{$block_props = $default_props}

{* Декодирование JSON *}
{if is_string($block_props["items"])}
    {$items_data = json_decode($block_props["items"], true)}
{else}
    {$items_data = $block_props["items"]}
{/if}

{* RENDER *}
{if !empty($items_data)}
    <div class="block-name">
        {call include_template template="html/components/block-header"
            subtext=$block_props["subtitle"]
            title=$block_props["title"]
            align=$block_props["align"]}

        {call include_template template="html/blocks/{block_name}/{$block_props["type"]}"
            items_data=$items_data block_props=$block_props}
    </div>
{/if}

Файлы типов отображения

Файлы типов ({block_name}_01.html, {block_name}_02.html и т.д.) отвечают только за верстку. Они получают готовые данные через переменные:

• $items_data — декодированные данные элементов
• $block_props — все настройки блока

Настройки блоков

Настройки блоков описываются в файле theme.xml темы и доступны в Smarty-шаблонах через $theme_settings:

{$theme_settings["home__block_name_setting"]}

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

• home__ — префикс для настроек главной страницы
• {block_name}_ — имя блока
• {setting_name} — имя настройки
• _type_{type} — суффикс для специальных типов контролов

Типы контролов (суффиксы):

Картинки для выбора типа отображения хранятся в каталоге темы assets/img/themesettings/blocks/{block_name}/types/; в настройках типа image select значением служит путь к такой картинке.

Передача параметров из home.html

Файл home.html перебирает JSON сортировки home__items_type_json и передает в каждый блок объект $item:

{call include_template template=$item["template"]
    wrapper_classes=$wrapper_classes item=$item app=$item["app"]}

Доступные поля объекта $item:

• item["id"] — ID блока (например, home__products_01)
• item["name"] — название блока
• item["template"] — путь к шаблону
• item["app"] — приложение
• item["fields"] — настраиваемые поля: фон (background), фон тёмной темы (background_dark), разделитель (divider), отступы (spacer_top, spacer_bottom)
• item["active"] — активен ли блок
• item["custom"] — пользовательский блок или нет

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

{$settings_prefix = "home__products_01"}
{if !empty($item["id"])}
    {$settings_prefix = $item["id"]}
{/if}

{$default_props = [
    "title" => $theme_settings["`$settings_prefix`_title"]|default:""
]}

Компонент block-header

Универсальный компонент для вывода заголовка блока. Расположен в html/components/block-header.html.

Параметры:

• subtext — текст над заголовком
• title — основной заголовок (поддерживает выделение через [слово])
• icon — иконка слева от заголовка, например lucide/star
• text — описание под заголовком
• align — выравнивание: left (по умолчанию) или center
• link — ссылка в заголовке
• link_text — текст ссылки-кнопки (выводится при align=center)

Создание пользовательского блока

Через панель управления темой можно создавать новые блоки на главной странице и в других местах.

Параметры блока будут доступны после сохранения настроек темы. В поле Путь к шаблону или id блока (или ID блока) нужно указать id блока из приложения Сайт — Блоки.

Блок в приложении Сайт

Подключение файла из темы дизайна

В поле Путь к шаблону или id блока нужно ввести данные для подключения файла через запятую — путь к файлу (без расширения .html, оно добавляется автоматически) и приложение. Данный функционал работает только для блоков главной страницы.

Пример: html/blocks/advantages/advantages,site

Подключение блока через Smarty

{call include_template template="html/blocks/advantages/advantages"}

С параметрами:

{call include_template template="html/blocks/advantages/advantages" props=[
    "title" => "Заголовок",
    "type" => "advantages_02"
]}

Пошаговое создание нового блока

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

1. Верстка и логика блока

Создайте директорию html/blocks/{block_name}/ и разместите в ней файлы:

• {block_name}.html — основной файл, который собирает настройки, обрабатывает props и подключает типы отображения
• {block_name}_01.html, {block_name}_02.html и т.д. — файлы типов отображения (при необходимости)

2. Настройки в theme.xml

Опишите настройки блока в theme.xml темы: группу-разделитель (group_divider) и сами настройки с префиксом home__{block_name}_.... Если используются картинки для выбора типа отображения, разместите их в assets/img/themesettings/blocks/{block_name}/types/.

3. Подключение в сортировку

Добавьте блок в JSON настройки «Блоки» (home__items_type_json) с полями id, name, template, app, fields (background, background_dark, divider, spacer_top, spacer_bottom), active, custom.

4. Данные

Если блок загружает данные (товары, посты и т.п.), в основном файле {block_name}.html:

• Соберите значения из $theme_settings
• Разрешите переопределение через $props
• При отсутствии данных в $props загрузите их из API (shop, blog и т.д.)

5. Поддержка множественных экземпляров (опционально)

Для нескольких независимых экземпляров блока с разными настройками:

• Опишите в theme.xml отдельные группы настроек с префиксами home__{block_name}_01_*, home__{block_name}_02_*
• Определяйте префикс динамически через $item["id"] (передается автоматически из home.html)
• Добавьте каждый экземпляр в сортировку home__items_type_json с разными id

6. Проверка

• Включите блок в сортировке и убедитесь, что include_template находит файл
• Проверьте отображение на главной странице
• Проверьте адаптивность на мобильных устройствах

Настройка внешнего вида блоков

Каждый блок на главной странице поддерживает настройки через панель темы:

• Тип отображения — выбор варианта отображения блока
• Заголовок — заголовок блока (поддерживает выделение через [слово])
• Подзаголовок — подзаголовок блока
• Описание — текстовое описание
• Выравнивание — выравнивание заголовка (left / center)
• Элементов в строке — количество элементов в ряду
• Фон, фон тёмной темы, отступы, разделитель — настраиваются через поля каждого блока в сортировке

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