` (template.php, параметры, локализация)link

Блок в SF4 — это папка с кодом блока, внутри которой лежит минимум файл template.php, а также (по необходимости) файлы метаданных и параметров. На практике код блока часто совпадает с именем папки (например, custom.button), а дальше этот код используется как «ключ» в параметрах грида и в интерфейсе редактора.

Показательная структура блока (пример custom.button):

{site_dir}/simai.data/grid/block/<section>/custom.button/template.php
{site_dir}/simai.data/grid/block/<section>/custom.button/.parameters.php
{site_dir}/simai.data/grid/block/<section>/custom.button/.description.php
{site_dir}/simai.data/grid/block/<section>/custom.button/lang/ru/.parameters.php
{site_dir}/simai.data/grid/block/<section>/custom.button/lang/ru/.description.php

Важно: секция (<section>) обычно соответствует области/контексту (header, footer, main, sidebar и т.д.) — в этом же контексте затем будет собираться view через BLOCK_SECTION.

Параметры и дефолты: где задаются и как читаютсяlink

Параметры блока объявляются в .parameters.php. Это «контракт» блока: какие поля доступны в редакторе и какие значения ожидает шаблон. Внутри блока параметры читаются из $arBlockProperty[...] по ключам вида:

<BLOCK_CODE_UPPER>__<PARAM_CODE>

В реальном примере блок берёт код из имени папки и приводит к верхнему регистру:

$nameTemplate = strtoupper(basename(__DIR__));

Дальше использует ключи:

$arBlockProperty[$nameTemplate . "__BUTTON_TEXT"]
$arBlockProperty[$nameTemplate . "__BUTTON_LINK"]

А в .parameters.php эти же ключи возвращаются как описание полей (с типами и дефолтами):

return [
    $nameTemplate . "__BUTTON_LINK" => [
        "TYPE" => "STRING",
        "DEFAULT" => "https://simai.studio",
    ],
    $nameTemplate . "__BUTTON_TEXT" => [
        "TYPE" => "STRING",
        "DEFAULT" => "simai.studio",
    ],
    $nameTemplate . "__BUTTON_TARGET__BLANK" => [
        "TYPE" => "CHECKBOX",
        "DEFAULT" => "Y",
    ],
];

Ресурсы: стили/скрипты и как их подключать в проектеlink

В текущей схеме проекта подключение библиотек/пакетов сделано централизованно через SIMAI\Main\Page\Asset в файле шаблона сайта:

{site_dir}/simai.data/template/style.php

Там явно видно практику: подключать нужные пакеты вызовами вида:

use SIMAI\Main\Page\Asset;

Asset::getInstance()->load("lazysizes");
Asset::getInstance()->load("jquery");
Asset::getInstance()->load("popper");
Asset::getInstance()->load("simai.framework");
Asset::getInstance()->load("simai.bx-panel");

Отсюда правило для блоков:

блок рассчитывает на уже подключенные пакеты (CSS/JS фреймворка и проекта) и использует классы/модификаторы;
если блоку нужна новая библиотека/пакет — сначала пакет должен появиться в конфигурации ассетов ядра (/simai/config/.asset.config.php), а затем подключаться через Asset::load(...) на уровне шаблона сайта (а не «внутри блока хаотично»).

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

Связка с view: как “зарегистрировать” блок для использованияlink

Отдельной “регистрации в реестре” для блока обычно не требуется: блок становится доступным, когда:

папка блока существует в {site_dir}/simai.data/grid/block/...,
view ссылается на блок по коду через параметр ...AREA_*_TEMPLATE.

То есть блок “подключается” тем, что в конфигурации грида (внутри view template.php) вы выставляете:

"ROW_<...>_COL_<...>_AREA_<...>_TEMPLATE" => "custom.button",

Контекст, где искать блоки, задаётся BLOCK_SECTION в этом же view (например, header / main). Поэтому типовая логика такая: view области header работает с секцией блоков header, view области main — с main и т.д.

Правила: коды блоков, совместимость ключей, запрет правок ядраlink

Практические правила, которые реально помогают избежать “невидимых” ошибок:

Код блока — латиница, без пробелов; точка в имени (custom.button) допустима и удобна для группировки.
Внутри блока ключи строятся от CUSTOM.BUTTON (верхний регистр), а в параметрах view точки в именах превращаются в подчёркивания (пример: CUSTOM_BUTTON). Это важно, когда вы смотрите сохранённые параметры в view/.../template.php.
Ядро и его поставку напрямую не редактировать: любую правку/вариацию блока оформлять как проектный блок в {site_dir}/simai.data/grid/block/....

Примеры визуализации и паттернов блоковlink

В документации по блокам лучше показывать не “абстрактные” случаи, а 2–3 повторяемых паттерна, которые встречаются повсеместно:

простая кнопка/ссылка (как custom.button): текст, href, target, модификатор CSS-классов;
блок-обёртка (контейнер/ряд/колонка): принимает модификаторы, условия, фон/отступы;
блок, который вызывает компонент: параметры блока управляют фильтром/выборкой компонента.

Эти паттерны помогают читателю быстро понять: блок — это либо “кусок HTML”, либо “вызов компонента”, а управление всегда идёт через параметры.

Описание блоков и готовых страниц как способ понять стиль проектаlink

Когда вы описываете блоки, полезно держать одну и ту же «линию» объяснения:

что делает блок (назначение),
какие параметры у него есть (ключевые поля из .parameters.php),
как он подключается во view (пример ...AREA_*_TEMPLATE),
какие классы/модификаторы обычно используются (чтобы верстальщику было понятно, куда “подцепляться”).

Так раздел про блоки становится практическим: читатель сразу видит “что править” и “где это живёт”.

Файлы блока: `template.php`, `.parameters.php`, `.description.php`, `lang/...`link

Минимальный набор файлов и их роль:

template.php — рендер (HTML/PHP), читает $arBlockProperty и выводит результат.
.parameters.php — описание параметров блока для редактора (типы, дефолты, refresh-логика при необходимости).
.description.php — метаданные блока для UI (имя/описание/сортировка/версия).
lang/<lang>/... — локализация названий/описаний/параметров через Loc::getMessage.

На примере custom.button метаданные выглядят так:

return [
    "NAME" => Loc::getMessage("SF_GRID__" . $nameTemplate . "__NAME"),
    "DESCRIPTION" => Loc::getMessage("SF_GRID__" . $nameTemplate . "__DESCRIPTION"),
    "SORT" => 100,
    "VERSION" => "1.0.0",
];

А локализация параметров — так:

$MESS["SF_GRID__" . $nameTemplate . "__BUTTON_TEXT"] = "Текст кнопки";

Файлы view: `template.php`, `.description.php`, `lang`, `image/preview.png`link

View оформляется похожим образом на блок:

template.php — содержит итоговую конфигурацию (вызов simai:sf.grid с большим массивом параметров).
.description.php + lang/... — имя/описание представления в UI.
image/preview.png — превью, которое показывается в настройках при выборе макета (если превью есть — пользователь выбирает “визуально”).

Это напрямую связано с вашим UX: пользователь выбирает “макет области” по списку или по картинкам.

Чек-лист готовности блокаlink

Блок считается “готовым”, если:

папка блока существует в {site_dir}/simai.data/grid/block/... и есть template.php;
если блок настраиваемый — есть .parameters.php, а названия параметров локализованы в lang/...;
есть .description.php, чтобы блок корректно отображался в интерфейсах выбора/редактирования;
блок подключён во view через ...AREA_*_TEMPLATE, и при необходимости ему переданы параметры ...__<BLOCK>__<PARAM>;
view, где используется блок, реально выбран на нужном уровне (site/section/page) через grid_view_*;
страница открывается без ошибок, а результат предсказуем после очистки кэша при изменениях.