Сырой список блоков: зачем он нужен и что из него братьlink

В SF4 есть практическая потребность быстро ответить на вопросы вида:

какие вообще блоки доступны для header/footer/home/main/sidebar;
как называется блок “по коду”, чтобы подставить его в view;
какие параметры у блока существуют и какие у них дефолты.

Для этого используется машиночитаемый реестр блоков (по сути — “каталог доступных блоков и их метаданных”). В документации важно описать не “где он лежит как файл-источник”, а как им пользоваться:

как навигацией: найти блок по секции и коду;
как справочником параметров: увидеть ключи, типы, дефолты, множественность;
как базой для генерации документации: собирать таблицы/карточки блоков “по секциям” автоматически.

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

Аннотации блока: секция, код, параметры, дефолты и “multiple”link

Блок в SF4 — это не только template.php. Вокруг него есть слой описания, который и делает блок “элементом конструктора”, а не просто кусочком PHP-вёрстки:

.description.php — метаданные блока (название/описание/прочие поля, которые использует каталог/редактор).
.parameters.php — описание параметров блока: имена, типы, дефолты (и, если поддерживается, множественность/доп. настройки параметра).

Типичный паттерн параметров, который встречается в блоках SF4:

код блока берётся из имени папки (например, search, menu.sidebar, custom.text);
внутри .parameters.php ключи собираются через общий префикс $nameTemplate (обычно strtoupper(basename(__DIR__))) и суффиксы вида __PARAM_NAME.

Пример структуры параметров (укороченно, но по реальному паттерну SF4):

use Bitrix\Main\Localization\Loc;

Loc::loadMessages(__FILE__);

$nameTemplate = strtoupper(basename(__DIR__));

return [
    $nameTemplate . '__INPUT_MODIFIER' => [
        'NAME'    => Loc::getMessage('SF_GRID__' . $nameTemplate . '__INPUT_MODIFIER'),
        'TYPE'    => 'STRING',
        'DEFAULT' => '',
    ],
    $nameTemplate . '__BUTTON_MODIFIER' => [
        'NAME'    => Loc::getMessage('SF_GRID__' . $nameTemplate . '__BUTTON_MODIFIER'),
        'TYPE'    => 'STRING',
        'DEFAULT' => 'btn-link position-absolute at-0 ar-0 ',
    ],
];

Что важно объяснить в документации:

Параметры блока сохраняются на уровне конкретной “области” (AREA) внутри грида. Поэтому в view-конфигурации ключи параметров выглядят “привязанными” к ROW_x_COL_y_AREA_z, а не просто “PARAM блока”.
В редакторе это ощущается как “у каждого блока на странице — свои настройки”, что и соответствует модели данных.

На практике это выглядит так (пример ключей, которые встречаются в view-конфиге):

'ROW_0_COL_0_AREA_0_TEMPLATE' => 'custom.text',
'ROW_0_COL_0_AREA_0__CUSTOM_TEXT__TEXT' => 'Контакты',

Здесь видно:

выбран шаблон блока custom.text;
конкретному инстансу этого блока (AREA_0) задан параметр TEXT.

Группировка блоков по секциям: как оформлять в документации и примеры блоковlink

Чтобы документация была полезной, блоки стоит показывать не одним списком, а “по месту использования” — секциями (header, footer, home, main, sidebar). Внутри секции читателю обычно достаточно:

что делает блок (1 строка);
2–4 ключевых параметра (если они есть);
примечание “где обычно подключается” (через какое представление/область).

Ниже — пример “версии 0.1” каталога: по нескольку наиболее показательных блоков на секцию.

Headerlink

menu.main — верхнее меню/шапка (встречается как связка “бренд + меню”, использует меню-компонент).
nav.breadcrumb — хлебные крошки (подключает breadcrumb-компонент).
search — форма поиска (параметры чаще всего про CSS-модификаторы инпута/кнопки).
banner.single / banner.main — вывод баннера в шапке (настраивается через параметры баннера/фильтрации).
social.share — блок шаринга (подключает share-компонент, параметры — какие сети/подписи показывать).
custom.text — произвольный текстовый блок (один из базовых “строительных кирпичиков”).
empty — пустой блок-заглушка (удобен как “слот”, который можно активировать позже).

Footerlink

org.copyright — копирайт/подпись организации.
org.address, org.phone, org.social — контактные блоки (адрес/телефон/соцсети).
subscribe.light — лёгкая подписка (обычно форма/вызов компонента).
informer.sputnik — информер/виджет.
menu.footer / menu.bottom — меню в подвале.
custom.text — произвольные подписи/контакты/доп. текст.
empty — заглушка.

Homelink

news.card.rss — карточки новостей по RSS (подключает RSS-компонент).
banner.slider.multi.rss — баннер-слайдер, где наполнение приходит из RSS.
event.calendar — календарный вид событий (компонентный вывод).
photo.slider.in, video.slider.in — слайдеры фото/видео (как правило, на данных инфоблоков).
weather — виджет погоды (подключает компонент погоды).
vote — опрос/голосование (использует компонент голосований).

Mainlink

page.title — заголовок страницы (часто зависит от настроек уровня page/section).
relation.news, relation.event, relation.doc — связанные материалы (как правило, списочные компоненты с фильтрацией).
social.share — шаринг внутри контентной части.
banner.single — одиночный баннер внутри контента.
empty — заглушка.

Sidebarlink

menu.sidebar — боковое меню (меню-компонент).
banner.list — список баннеров в сайдбаре.
include.file, include.section — включаемые области (подключение контента из include-слоя).
widget.sidebar — виджет/обёртка под сайдбар-контент.
empty — заглушка.

Примеры структуры/параметров: как вставлять в документацию “понятные” фрагментыlink

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

Код блока (например, menu.sidebar) и секция (sidebar).
Назначение (1–2 предложения).
Ключевые параметры (2–5 штук): имя → смысл → дефолт (если есть).
Мини-пример использования во view: одна строка *_TEMPLATE + 1–2 параметра.

Мини-пример, который хорошо объясняет модель данных (view выбирает блок и задаёт параметры конкретному инстансу):

'ROW_first_COL_0_AREA_0_TEMPLATE' => 'menu.sidebar',
'ROW_first_COL_0_AREA_0__MENU_SIDEBAR__ROOT_MENU_TYPE' => 'left',