Свойства страницы и раздела

Свойства страницы и раздела хранят служебные значения для шаблона сайта, компонентов и кода страницы. Через свойства задают SEO-метаданные, заголовок окна браузера и другие значения, которые отличаются на страницах и в разделах сайта.

Свойства страницы действуют только на текущей странице. Свойства раздела задают значения для папки сайта и наследуются вложенными страницами и подразделами, если у них нет собственных значений.

Как устроены свойства

Свойство страницы. Относится к одному файлу страницы. Например, страница каталога хранит значение свойства description, которое шаблон выводит в HTML-метатег.

Свойство раздела. Относится к папке сайта и хранится в файле .section.php этой папки. Если вложенная страница не задает собственное значение, система берет значение из ближайшего раздела выше.

Тип свойства. Это код, по которому система записывает, читает и выводит значение. Администратор настраивает набор типов свойств отдельно для каждого сайта.

Добавить тип свойства

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

  1. В административном разделе откройте страницу Настройки > Настройки продукта > Настройки модулей > Управление структурой.

  2. На вкладке Настройки в секции Настройки для сайтов найдите параметр Типы свойств.

  3. В колонке Тип введите код свойства латинскими буквами. В колонке Название укажите понятное название. Например, для SEO добавьте keywords — Ключевые слова и description — Описание страницы.

Для SEO-метаданных тип свойства должен совпадать с именем HTML-метатега:

  • keywords для тега <meta name="keywords">,

  • description для тега <meta name="description">.

Чем свойства отличаются от заголовка страницы

Основной заголовок страницы хранится отдельно от свойств страницы и раздела. Его задают методом SetTitle() и получают методом GetTitle().

Свойство title — зарезервированное свойство страницы. Обычно его используют для заголовка окна браузера, который выводится в теге <title> шаблона сайта. Это не второй самостоятельный заголовок, а обычное свойство страницы с особым назначением.

Подробнее о разнице между основным заголовком и свойством title читайте в статье Заголовки страницы: на сайте и в браузере.

Задать свойства страницы

Свойства страницы задают через интерфейс или в коде. Значение страницы имеет приоритет над значением раздела с таким же типом свойства.

Свойства страницы через публичную часть

  1. Откройте страницу на просмотр в публичном разделе сайта.

  2. Нажмите Изменить страницу > Заголовок и свойства страницы на административной панели.

  3. Заполните свойства и сохраните страницу.

Свойства страницы через административную часть

  1. Откройте Контент > Структура сайта > Файлы и папки.

  2. Перейдите в папку, в которой размещена страница.

  3. Нажмите Редактировать как HTML или Редактировать как текст в меню нужной страницы.

  4. Заполните свойства и сохраните страницу.

Свойства страницы через API

Чтобы задать свойство текущей страницы, вызовите SetPageProperty(property_id, property_value, Options) в коде страницы или компонента.

  • property_id — код свойства.

  • property_value — значение свойства.

  • Options — массив с дополнительными настройками свойства, необязательный параметр.

Чтобы форма Заголовок и свойства страницы могла прочитать и изменить свойства, разместите вызовы в первом PHP-блоке файла страницы. Запишите каждый вызов на одной строке и передайте код и значение свойства строковыми литералами, без переменных, конкатенации и третьего аргумента.

Добавьте свойства после подключения /bitrix/header.php, до закрывающего ?> первого PHP-блока.

<?php
require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php');

$APPLICATION->SetPageProperty('keywords', 'Ключевые слова');
$APPLICATION->SetPageProperty('description', 'SEO описание');
$APPLICATION->SetPageProperty('title', 'Заголовок окна браузера');
?>

Свойства страницы можно задавать динамически в коде страницы или компонента. Такие вызовы работают при выполнении PHP, но форма редактирования не извлекает из них значения. Управляйте ими в коде.

Пример. Компонент передает в description значение свойства элемента инфоблока с кодом META_DESCRIPTION. Массив $arIBlockElement содержит данные элемента и его свойства.

<?php
$APPLICATION->SetPageProperty(
    'description',
    $arIBlockElement['PROPERTIES']['META_DESCRIPTION']['VALUE']
);
?>

Задать свойства раздела

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

Свойства раздела через публичную часть

  1. Откройте раздел в публичной части сайта.

  2. Нажмите Изменить раздел > Заголовок и свойства страницы на административной панели.

  3. Заполните свойства и сохраните изменения.

Свойства раздела через административную часть

  1. Откройте Контент > Структура сайта > Файлы и папки в административном разделе.

  2. Перейдите к папке, которая содержит ваш раздел.

  3. Нажмите Свойства папки в меню раздела.

  4. Заполните свойства и сохраните изменения.

Свойства раздела через API

Чтобы сохранить свойства раздела для следующих запросов, отредактируйте файл .section.php соответствующей папки или сохраните свойства через интерфейс. В файле массив $arDirProperties задает свойства, а переменная $sSectionName — название раздела для навигационной цепочки. Форма Свойства папки записывает в $sSectionName значение поля Заголовок. Эта переменная не заменяет свойство title для окна браузера.

Создайте файл /products/.section.php со свойствами и названием раздела.

<?php
$sSectionName = 'Продукция';
$arDirProperties = [
    'description' => 'SEO описание для всего раздела',
    'keywords' => 'Ключевые слова для всего раздела',
    'title' => 'Заголовок окна браузера для всего раздела',
];
?>

Метод SetDirProperty(property_id, property_value, path) меняет значение только в памяти на время текущего запроса. Он не записывает данные в .section.php. Используйте его, чтобы временно переопределить свойство раздела перед чтением или выводом, например задать описание из данных компонента.

  • property_id — код свойства.

  • property_value — значение свойства.

  • path — путь к разделу. Если путь не передан, метод использует текущий раздел.

Задайте описание текущего раздела без параметра path.

<?php
$APPLICATION->SetDirProperty('description', 'Описание раздела для текущего запроса');
?>

Методы GetProperty(), ShowProperty() и ShowMeta() учтут это значение, если страница не задает собственное свойство description.

Если передаете путь другого раздела в SetDirProperty(), передайте тот же путь в GetDirProperty() при чтении. Без пути GetDirProperty() читает текущий раздел, поэтому установка значения для /products/ не меняет описание страницы из другого раздела.

Пример. Код задает и получает временное описание раздела /products/ независимо от расположения текущей страницы.

<?php
$APPLICATION->SetDirProperty('description', 'Временное описание продукции', '/products/');
$description = $APPLICATION->GetDirProperty('description', '/products/');
?>

Получить свойства в коде

Если значение используется в логике страницы или компонента, получите его одним из методов чтения.

GetPageProperty()

Метод GetPageProperty(property_id, default_value) возвращает свойство страницы.

  • property_id — код свойства.

  • default_value — значение по умолчанию. Метод возвращает его, если свойство страницы не найдено.

<?php
$keywords = $APPLICATION->GetPageProperty('keywords');
$description = $APPLICATION->GetPageProperty('description', 'Значение по умолчанию');
$title = $APPLICATION->GetPageProperty('title');
?>

GetDirProperty()

Метод GetDirProperty(property_id, path, default_value) возвращает свойство раздела.

  • property_id — код свойства.

  • path — путь к разделу. Если путь не передан, метод использует текущий раздел.

  • default_value — значение по умолчанию.

<?php
$keywords = $APPLICATION->GetDirProperty('keywords');
$description = $APPLICATION->GetDirProperty('description', false, 'Значение по умолчанию');
$title = $APPLICATION->GetDirProperty('title');
?>

GetProperty()

Метод GetProperty(property_id, default_value) сначала проверяет свойство текущей страницы. Если свойство не найдено, метод ищет свойство раздела с учетом наследования.

  • property_id — код свойства.

  • default_value — значение по умолчанию. Метод возвращает его, если свойство не найдено ни на странице, ни в разделе.

<?php
$keywords = $APPLICATION->GetProperty('keywords');
$description = $APPLICATION->GetProperty('description', 'Значение по умолчанию');
$title = $APPLICATION->GetProperty('title');
?>

Вывести свойства в шаблоне сайта

Выберите способ вывода по назначению свойства. ShowProperty() выводит само значение, а ShowMeta() формирует HTML-метатег.

Вывод значения свойства

Чтобы вывести свойство, используйте ShowProperty(property_id, default_value). Метод отображает значение свойства страницы с учетом свойств раздела.

  • property_id — код свойства.

  • default_value — значение по умолчанию. Система выведет его, если свойство не найдено.

<?php $APPLICATION->ShowProperty('description', 'Описание по умолчанию'); ?>

Отдельных методов вывода только свойства страницы или только свойства раздела нет. Метод ShowProperty() работает с общим результатом: сначала учитывает свойство страницы, затем свойство раздела и значение по умолчанию.

ShowProperty() выводит значение без HTML-экранирования. Для вывода обычного текста экранируйте значение через htmlspecialcharsbx(). Если свойство задают ниже по коду страницы, выполните чтение и экранирование в отложенной функции через AddBufferContent(), как в примере ниже.

Вывод свойства в виде метатега

Для SEO-метаданных используйте ShowMeta(id, meta_name, bXhtmlStyle).

  • id — код свойства. По умолчанию метод использует код как значение атрибута name в HTML-метатеге.

  • meta_name — другое значение для атрибута name.

  • bXhtmlStyle — признак использования XHTML-формата для тега.

В шаблоне с ShowHead() метатеги keywords и description уже входят в общий вывод содержимого <head>. Дополнительные вызовы ShowMeta() для этих свойств создадут дубли. Используйте отдельные вызовы, если шаблон формирует содержимое <head> без ShowHead().

Разместите отдельные вызовы внутри тега <head> в файле шаблона header.php.

<head>
    <?php $APPLICATION->ShowMeta('keywords'); ?>
    <?php $APPLICATION->ShowMeta('description'); ?>
</head>

Система сформирует HTML-метатеги:

<meta name="keywords" content="женская одежда, мужская одежда, доставка" />
<meta name="description" content="Мы доставляем нашу продукцию собственной службой доставки" />

ShowMeta() экранирует значение свойства для атрибута content и имя метатега для атрибута name. Если значение свойства не задано или пустое, метод не выведет метатег.

Учесть отложенный вывод

Методы GetPageProperty(), GetDirProperty() и GetProperty() сразу возвращают значение свойства в момент вызова. Если компонент установит свойство позже через SetPageProperty(), ранний вызов GetPageProperty() вернет значение по умолчанию или false. В тех же условиях GetProperty() в header.php вернет значение раздела с учетом наследования, а если его нет — значение по умолчанию. После SetPageProperty() новый вызов GetProperty() вернет значение страницы.

Для вывода в шаблоне используйте ShowProperty() и ShowMeta(). Эти методы откладывают чтение свойства до завершения формирования страницы, поэтому учитывают значения, которые компонент задает после подключения header.php.

Как работает буферизация

В обычном запросе публичной страницы Bitrix Framework накапливает HTML в буфере вывода PHP. Буфер хранит результат выполнения шаблона и страницы до отправки в браузер.

Метод AddBufferContent(callback, ...args) регистрирует отложенную функцию в месте вызова. Первый аргумент — вызываемая функция или метод, остальные аргументы система передает этой функции при выполнении.

  1. AddBufferContent() сохраняет накопленный HTML, место для результата функции и ее аргументы.

  2. PHP продолжает выполнять страницу и компоненты. Они могут установить или изменить свойства.

  3. При завершении буферизации EndBufferContent() вызывает зарегистрированные функции и вставляет возвращенные строки на сохраненные места.

  4. Система объединяет фрагменты HTML и отправляет готовую страницу в браузер.

ShowProperty() регистрирует через AddBufferContent() вызов GetProperty(), а ShowMeta() — вызов GetMeta(), который читает свойство и формирует метатег. ShowHead() также использует этот механизм для метатегов.

Если константа BX_BUFFER_USED не определена или не равна true, AddBufferContent() выполняет функцию сразу. Значения, которые код задаст позже, в таком режиме не попадут в ранний вывод.

В header.php вызовите ShowHead() внутри <head>.

<head>
    <?php $APPLICATION->ShowHead(); ?>
</head>

В файле страницы после подключения /bitrix/header.php задайте описание.

<?php
$APPLICATION->SetPageProperty('description', 'SEO описание из компонента');
?>

При включенной буферизации метатег description получит значение SEO описание из компонента, хотя вызов ShowHead() расположен выше установки свойства.

Вывести свойство с экранированием

Для обычного текста зарегистрируйте свою функцию через AddBufferContent(). Функция должна возвращать готовую строку, а не выводить ее через echo. Читайте свойство внутри функции, чтобы получить его значение после выполнения компонентов.

Добавьте в header.php отложенный вывод описания с HTML-экранированием.

<?php
$APPLICATION->AddBufferContent(function () use ($APPLICATION)
{
    return htmlspecialcharsbx($APPLICATION->GetProperty('description', ''));
});
?>

Если получить значение через GetProperty() заранее и передать готовую строку в отложенную функцию, последующая установка свойства не изменит эту строку.

Учесть приоритет значений

Для одного типа свойства система использует самое близкое значение к текущей странице.

  • Если значение задано на странице, оно имеет наивысший приоритет.

  • Если на странице значения нет, система проверяет свойства текущего раздела.

  • Если в текущем разделе значения нет, система проверяет вышестоящие разделы до корня сайта.

  • Если значение не найдено, система использует значение по умолчанию, которое передают в метод.

  • Если значение по умолчанию не передали, свойство остается незаданным.

Такой порядок позволяет задать общие свойства для раздела и переопределить их на отдельных страницах.

Предыдущая
Шаблоны страницы
Следующая
Заголовки страницы