Подготовить ссылки на примеры конфигурацийlink

Чтобы в документации быстро «прыгать» к нужному примеру, удобно завести постоянные якоря на ключевые части страницы про грид и ссылаться на них из соседних разделов (настройки, view, блоки, визуальный редактор).

Рекомендуемый набор ссылок:

• Шаблон вызова компонента (скелет IncludeComponent + куда класть плоские ключи) — раздел «Шаблон вывода».
• Мини-пример (показывает, как выглядят ROW_* / COL_* / AREA_*, массивы и пр.) — раздел «Мини-пример».
• Маппинг ключей в $arParams (правила именования) — раздел «Жёсткие правила маппинга → $arParams».
• Валидация (контроль ширин/счётчиков/типов значений) — раздел «Валидация перед выводом».

Если хотите, чтобы ссылки были стабильными независимо от генерации slug’ов, можно прямо в заголовки добавить HTML-якоря, например:

### <a id="sf-grid-php-template"></a>Шаблон вывода
### <a id="sf-grid-mini-example"></a>Мини-пример
### <a id="sf-grid-mapping"></a>Жёсткие правила маппинга → `$arParams`
### <a id="sf-grid-validation"></a>Валидация перед выводом

Тогда ссылки будут простыми и не зависят от движка документации: #sf-grid-mini-example, #sf-grid-mapping и т.д.

Использовать паттерны имен как таблицу с пояснениямиlink

Ниже — компактная «таблица-памятка», которую удобно вставлять в документацию рядом с описанием view/редактора. Она объясняет как читаются параметры и какие ключи за что отвечают.

Отдельное правило типизации (его тоже удобно вставить в виде маленькой памятки рядом с таблицей):

• bool → 'Y'/'N'
• числа → строки
• multiple-значения → PHP-массив

Вставлять выдержки и формат параметровlink

Базовый «скелет» вызова компонента (как сниппет для документации) удобно держать отдельным блоком — его вставляют в Quick Start, в раздел про view и в раздел про диагностику.

<?php
declare(strict_types=1);

$APPLICATION->IncludeComponent(
    'simai:sf.grid',
    '.default',
    [
        // Плоские ключи параметров:
        'BLOCK_SECTION' => 'header',
        'ROW_COUNT'     => '…',
        // … все ROW_*/COL_*/AREA_* и глобальные ключи
    ],
    false,
    [
        // Типичный приём для UI: скрывать иконки, если не включён режим редактирования
        'HIDE_ICONS' => (Property::getValue(SF_SITE_DIR, 'grid_edit_mode') === 'Y' ? 'N' : 'Y'),
    ]
);

К этому сниппету обычно добавляют 2–3 строки пояснения прямо в тексте:

• BLOCK_SECTION задаёт «контекст» области страницы (шапка/подвал/…).
• ROW_COUNT + семейство ROW_* / COL_* / AREA_* описывают структуру и содержимое.
• Доп.параметры вызова (HIDE_ICONS) используются, чтобы поведение страницы менялось в зависимости от режима редактирования.

При вставке кода — фрагменты формата параметров и примеры блоковlink

Ниже — показательный фрагмент реального view, где одновременно видны:

1. multiple-параметр (массив соцсетей),
2. серийные параметры (счётчик + CODE_n / VALUE_n),
3. «обычные» параметры блока.

Пример того, как это выглядит в {site_dir}/simai.data/grid/view/header/005/template.php (сокращено до смысловой части):

$APPLICATION->IncludeComponent(
    'simai:sf.grid',
    '.default',
    [
        'BLOCK_SECTION' => 'header',

        // multiple-параметр (массив)
        'ROW_4_COL_1_AREA_0_TEMPLATE' => 'social.share',
        'ROW_4_COL_1_AREA_0__SOCIAL_SHARE__SOCIAL' => [
            'facebook',
            'twitter',
            'vkontakte',
            'odnoklassniki',
            'print',
        ],

        // обычные параметры блока
        'ROW_0_COL_0_AREA_0_TEMPLATE' => 'banner.single',
        'ROW_0_COL_0_AREA_0__BANNER_SINGLE__SECTION_CODE' => 'header',
        'ROW_0_COL_0_AREA_0__BANNER_SINGLE__USE_FILTER' => 'Y',

        // серийные параметры (счётчик + CODE_n/VALUE_n)
        'ROW_0_COL_0_AREA_0__BANNER_SINGLE_FILTER_COUNT' => '1',
        'ROW_0_COL_0_AREA_0__BANNER_SINGLE_CODE_0' => 'PROPERTY_MAIN',
        'ROW_0_COL_0_AREA_0__BANNER_SINGLE_VALUE_0' => 'false',
    ]
);

Чтобы у читателя не было «магии» вокруг серийных параметров, полезно рядом вставлять короткий фрагмент логики из .parameters.php блока (он объясняет, почему появляются *_FILTER_COUNT, *_CODE_0, *_VALUE_0):

if ($arCurrentValues[$tmpCode . '__USE_FILTER'] == 'Y')
{
    $params[$nameTemplate . '_FILTER_COUNT'] = [
        'TYPE'    => 'LIST',
        'VALUES'  => [1 => 1, 2 => 2, 3 => 3, 4 => 4],
        'DEFAULT' => '1',
        'REFRESH' => 'Y',
    ];

    for ($i = 0; $i < $arCurrentValues[$tmpCode . '_FILTER_COUNT']; $i++)
    {
        $params[$nameTemplate . '_CODE_' . $i] = [ 'TYPE' => 'STRING', 'DEFAULT' => 'PROPERTY_MAIN' ];
        $params[$nameTemplate . '_VALUE_' . $i] = [ 'TYPE' => 'STRING', 'DEFAULT' => 'false' ];
    }
}

Эти два сниппета вместе хорошо закрывают типовой вопрос читателя: «Откуда взялись такие ключи в view и как понять, какие ещё бывают?».