# Блоки

← [К разделу «Как собирается сайт»](README.md)

Блок — переиспользуемый фрагмент содержимого или проектной логики. Один блок
можно вставить в шаблон сайта, рубрику, запрос или другой блок.

## Создание блока

Для блока задаются название, уникальный alias, группа, описание, активность и
режим редактора. Группа нужна только для организации списка и не влияет на
публичный вызов.

| Режим | Когда использовать |
| --- | --- |
| Обычный текст | Строки без HTML-редактирования. |
| Rich text | Контент, который меняет редактор без работы с разметкой. |
| HTML | Управляемая разметка, теги полей, запросов и других блоков. |
| PHP | Небольшая проектная логика, которой действительно нужен серверный код. |

Переключение режима меняет редактор и способ обработки. PHP-код проходит
проверку синтаксиса перед сохранением. Для большой или повторно используемой
логики создавайте сервис и hook модуля.

Обычное право `manage_blocks` управляет HTML, rich text и plain text блоками.
Исполняемый режим дополнительно требует `manage_php_blocks`: без него PHP-блок
нельзя открыть, изменить, скопировать или восстановить из ревизии. Изменения
фиксируются в общем журнале аудита без записи исходного кода в событие.

## Вставка в шаблон

Основной публичный тег использует alias:

```text
[tag:sysblock:footer]
```

Старый `[tag:block:...]` поддерживается для совместимости, но новый код следует
писать через `sysblock`.

Блок может содержать:

```text
[tag:request:latest_news]
[tag:sysblock:contacts]
[tag:fld:cover]
[tag:breadcrumb]
```

Поля документа доступны только когда блок рендерится в контексте документа.

## Параметры

Параметры передаются JSON-объектом в теге:

```text
[tag:sysblock:banner:{"theme":"dark","limit":4}]
```

Внутри блока значение читается так:

```text
[sys:param:theme]
[sys:param:limit]
```

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

## Внешний и AJAX-вызов

Флаг внешнего вызова разрешает получить блок отдельным публичным запросом. AJAX
может дополнительно ограничить такой вызов ожидаемым режимом. Не включайте эти
флаги для внутреннего блока без необходимости: внешний endpoint увеличивает
публичную поверхность системы.

## Вложенность и рекурсия

Блоки могут включать другие блоки, но не должны ссылаться сами на себя напрямую
или по цепочке. Runtime останавливает повторный вход и ограничивает максимальную
глубину, однако циклическая схема всё равно является ошибкой проекта.

## Кеш и ревизии

После сохранения, копирования, удаления или восстановления система очищает кеш
по ID и alias блока. Ручная очистка нужна после внешнего изменения БД или для
диагностики.

Ревизии сохраняют содержимое и основные настройки. Перед восстановлением старой
версии создаётся снимок текущей. Удаление всех ревизий не удаляет сам блок.

## Проверка блока

1. Выполните проверку синтаксиса.
2. Сохраните и откройте страницу, где блок реально используется.
3. Проверьте гостя и авторизованного пользователя, если есть условия доступа.
4. Проверьте вложенные запросы и поля документа.
5. Для внешнего блока отдельно проверьте запрещённый и разрешённый вызов.