$APPLICATION в Битрикс: методы CMain с примерами

Глобальный объект $APPLICATION — экземпляр класса CMain, создающийся автоматически на каждой странице сайта. Через него проходит формирование заголовка, подключение стилей и скриптов, вывод меню и работа с включаемыми областями — почти всё, что связывает шаблон с содержимым страницы.

Разберём методы, которыми пользуются каждый день, и объясним логику отложенных функций — механизм, который в старом ядре Битрикс работает не так, как ожидает интуиция.

Заголовки и метатеги

Метод	Назначение
`SetTitle($title)`	Заголовок страницы, обычно выводится в H1
`ShowTitle()`	Вывод заголовка в шаблоне
`SetPageProperty($name, $value)`	Свойство страницы — title, description и другие
`GetProperty($name)`	Получение значения свойства страницы

<?php
$APPLICATION->SetTitle('О компании');
$APPLICATION->SetPageProperty('title', 'О компании — 20 лет на рынке');
$APPLICATION->SetPageProperty('description', 'Производим мебель с 2006 года.');

Подключение стилей и скриптов

Метод	Назначение
`SetAdditionalCSS($path)`	Подключить CSS-файл, участвует в объединении
`AddHeadScript($path)`	Подключить JS-файл
`AddHeadString($html)`	Произвольная строка в `<head>`
`ShowHead()`	Вывод всего накопленного в head — обязателен в шаблоне

Без вызова ShowHead() ни один из подключённых стилей и скриптов не попадёт на страницу — сколько бы раз ни вызывался SetAdditionalCSS.

Нужна помощь с Битрикс?

Работа с меню и панелью

<?php
$APPLICATION->ShowPanel();      // административная панель для авторизованных
$APPLICATION->IncludeComponent('bitrix:menu', 'top', ['ROOT_MENU_TYPE' => 'top']);

ShowPanel() — то, без чего у администратора не появится визуальный редактор и кнопки правки включаемых областей. Пропущенный вызов в шаблоне — частая причина «редактирование не работает», которую путают с настройками прав доступа.

Включаемые области

<?php
$APPLICATION->IncludeFile(
    SITE_DIR . 'include/phone.php',
    [],
    ['MODE' => 'html', 'NAME' => 'Телефон в шапке']
);

Это самый простой способ подключить редактируемый контент-менеджером блок. Более гибкий вариант с поиском файла по разделам и страницам разобран в отдельной статье про включаемые области.

Отложенные функции

Особенность старого ядра, которую важно понимать: часть методов не выводит значение сразу, а регистрирует «заглушку», которая заполняется позже, когда всё содержимое страницы уже сформировано. Именно так работает ShowTitle() — заголовок может быть задан в любом месте страницы, хоть после вывода header.php, и всё равно окажется там, где вызван ShowTitle() в шапке.

Похожая логика — у метода AddViewedElement для истории просмотров и у ряда других вызовов, результат которых зависит от данных, ставших известными уже после отработки header.php.

Проверки условий

Метод	Что проверяет
`GetCurPage()`	Текущий адрес страницы
`GetCurDir()`	Текущий раздел
`GetCurPageParam($add, $del)`	Текущий адрес с изменёнными GET-параметрами

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

Обработка ошибок

<?php
if (empty($arFields['EMAIL'])) {
    $APPLICATION->throwException('Не указан e-mail');
    return false;
}

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

Частые ошибки

Пропущен ShowHead(). Половина функциональности ядра выглядит так, будто не работает.
Пропущен ShowPanel(). Не появляется административная панель и режим правки.
SetTitle вызывается раньше подключения пролога. Заголовок не применяется.
Ручная сборка адреса вместо GetCurPageParam. Теряются уже установленные параметры фильтра или сортировки.

Итог

$APPLICATION — центральный объект старого ядра, через который шаблон получает заголовки, стили, скрипты, меню и режим административной правки. Три вызова обязательны в любом шаблоне: ShowHead() для стилей и скриптов, ShowPanel() для админ-панели и правильный порядок вызова SetTitle() относительно подключения пролога.

Теги: Разработка Шаблоны