API областей контента

После подключения Loader::includeModule('kokhanenko.hlblocks') доступны два способа вывода: фасад Content для чтения и ContentItemWrapper для редактируемой области.

Фасад Content

Пространство имён: Kokhanenko\Hlblocks\Facade\Content.

Метод	Результат
`get(string\\|int $key): ?string`	Отрисованное значение в текущем контексте или `null`
`show(string\\|int $key): void`	Вывод значения; при отсутствии ничего не выводит
`has(string\\|int $key): bool`	Есть ли значение для текущего языка и сайта
`getForContext(string\\|int $key, ContentContext $context): ?string`	Чтение для явно заданного контекста

PHP

use Kokhanenko\Hlblocks\Facade\Content;
use Kokhanenko\Hlblocks\Content\Value\ContentContext;

Content::show('footer.address');
$english = Content::getForContext('home.intro', new ContentContext('en', 's2'));

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

Возвращаемое значение уже подготовлено по типу области: text экранирован, у textarea сохранены переносы, html возвращается как доверенная разметка. Не используйте результат как произвольное значение HTML-атрибута. Для атрибутов требуется отдельная проверка и экранирование.

has() отличает отсутствие значения от сохранённой пустой строки: пустая строка существует и даёт true. Ошибка чтения не должна трактоваться как разрешение создать данные.

ContentItemWrapper

Пространство имён: Kokhanenko\Hlblocks\Template\ContentItemWrapper.

Метод	Назначение
`setScope(?string $scope)`	Установить префикс; `null` сбрасывает его
`showBlock(int\\|string $key, ?string $tagName = null, ?string $tagCssClass = null)`	Вывести содержимое и доступную редактору обёртку
`prepareData(array $keys)`	Предварительно прочитать несколько областей

PHP

ContentItemWrapper::setScope('footer');
ContentItemWrapper::prepareData(['address', 'hours']);
ContentItemWrapper::showBlock('address', 'div', 'footer-address');
ContentItemWrapper::showBlock('hours', 'div', 'footer-hours');
ContentItemWrapper::setScope(null);

Пример обращается к footer.address и footer.hours. Для полного кода footer.address префикс повторно не устанавливайте. Числовые ключи — ID определений; для переносимости используйте текстовые коды.

В отличие от чистого чтения Content::get(), showBlock() может создать отсутствующее определение при доступном редакторе с правом записи. При этом тип по умолчанию — text, исходное значение — переданный ключ. Существующее определение без перевода автоматически не перезаписывается.

Публичные begin()/end() сохранены для административной обёртки совместимости. Для нового публичного редактора произвольных записей используйте HlElementEditWrapper, а не ContentItemWrapper. Области и записи HL имеют разные формы и правила доступа.

Кеширование и контекст

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

Если область выводится внутри собственного кешируемого компонента, зарегистрируйте зависимости в соответствующем контексте тегированного кеша. Отдельный HTML-кеш страницы Битрикса живёт по своим правилам; см. хранение и кеш.