Перейти к содержимому
BXWiki

Натяжка вёрстки на шаблон сайта - разрез, пути, компоненты

Переносим готовую вёрстку в шаблон сайта: разрез, обязательные вызовы, пути к файлам и замена статических блоков компонентами.

Механика

Шаблон сайта - это не страница, а два куска одной страницы. Всё, что идёт до содержимого, живёт в шапке, всё после - в подвале, а между ними платформа подставляет содержимое конкретной страницы.

Точку разреза задают меткой рабочей области прямо в разметке шаблона. При создании шаблона в админке разметку вставляют целиком и ставят метку там, где начинается содержимое; платформа сама разложит её на два файла.

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

Пути к файлам вёрстки считаются от каталога шаблона, а не от страницы. Это самая частая поломка после переноса: на главной всё на месте, а на внутренней странице пропадают стили и картинки.

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

Куски содержимого, которые правит редакция, выносят во включаемые области. Тогда контент-менеджер правит текст, а не разметку с обёртками, и вёрстка остаётся целой после первой же правки.

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

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

Шаги

  1. Вставить разметку в новый шаблон и поставить метку рабочей области.
  2. Добавить в шапку служебные вызовы заголовка, ресурсов и панели управления.
  3. Перевести пути к стилям, скриптам и картинкам на каталог шаблона.
  4. Заменить статические блоки навигации и списков вызовами компонентов.
  5. Вынести правимые куски содержимого во включаемые области.
  6. Натянуть шаблоны компонентов на готовую разметку по одному.

Код

Размечаем точку разреза:

<div class="page">
  <header class="header">...</header>
  <main class="content">
    #WORK_AREA#
  </main>
  <footer class="footer">...</footer>
</div>
<!-- всё до метки уедет в шапку, всё после - в подвал шаблона -->

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

Ставим обязательные вызовы шапки:

<?php if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) die(); ?>
<!DOCTYPE html>
<html lang="<?= LANGUAGE_ID ?>">
<head>
    <?php $APPLICATION->ShowHead(); ?>    <!-- метатеги, стили и скрипты платформы -->
    <title><?php $APPLICATION->ShowTitle(); ?></title>
</head>
<body>
<?php $APPLICATION->ShowPanel(); ?>       <!-- без этого нет режима правки -->

Первая строка отсекает прямое обращение к файлу шаблона. Без неё файл открывается по прямой ссылке и отдаёт кусок разметки без платформы, а иногда и ошибку с путями на сервере.

Подключаем стили и скрипты через платформу:

$asset = \Bitrix\Main\Page\Asset::getInstance();
$asset->addCss(SITE_TEMPLATE_PATH . '/css/style.css');
$asset->addJs(SITE_TEMPLATE_PATH . '/js/app.js');
// платформа сама добавит метку версии по времени изменения файла
// и учтёт настройку объединения файлов, если она включена

Путь строится от каталога шаблона, а не от текущей страницы. Относительные пути в готовой вёрстке работают только на главной и отваливаются на первой же внутренней странице.

Заменяем статическое меню компонентом:

$APPLICATION->IncludeComponent('bitrix:menu', 'top', [
    'ROOT_MENU_TYPE' => 'top',
    'MENU_CACHE_TYPE' => 'A',
        'USE_EXT' => 'Y',                      // подключать разделы с собственными меню
    'MAX_LEVEL' => 2,                      // сколько уровней вложенности показывать
]);
// разметку меню переносят в шаблон компонента, а не оставляют в шапке

Выносим правимый кусок во включаемую область:

$APPLICATION->IncludeFile(SITE_DIR . 'include/phones.php', [], [
    'MODE' => 'html',                      // редактируется визуальным редактором
        'NAME' => 'Телефоны в шапке',
]);
// область создаётся при первой правке: пустой файл заводить заранее не нужно
// обёртки остаются в шаблоне, внутри области - только текст

Редакция должна править текст, а не разметку. Область с обёртками снаружи переживает любые правки контент-менеджера, а вставленный в контент блок с классами - нет.

Натягиваем шаблон компонента:

Окно терминала
cp -r bitrix/components/bitrix/news.list/templates/.default \
      local/templates/main/components/bitrix/news.list/cards
# в template.php оставляют верхнюю строку с проверкой пролога
# дальше кладут голую вёрстку и только потом подставляют данные результата

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

Шаблон компонента живёт в каталоге проекта, рядом с шаблоном сайта. Оригинал в каталоге платформы не трогают вовсе: он нужен как образец при обновлении и как источник, из которого копируют новые версии разметки.

Включаем показ ошибок на время работы:

// bitrix/.settings.php - только на стенде, не на боевом сайте
'exception_handling' => ['value' => [
    'debug' => true,                       // показывать текст ошибки на странице
    'handled_errors_types' => E_ALL & ~E_NOTICE & ~E_DEPRECATED,
]],

Белый экран - это фатальная ошибка при выключенном выводе. Включённый показ превращает двухдневный поиск в чтение одной строки с именем файла и номером строки.

Ограничения

Готовая вёрстка почти никогда не ложится на компоненты один в один. Списки, пагинация и фильтры в макете нарисованы «как красиво», а компонент отдаёт свою структуру данных, и часть разметки приходится переделывать.

Режим правки работает только со штатными механизмами. Блок, собранный своим кодом или клиентским приложением, редактируется через админку, а не кнопкой на странице, и это стоит объяснить заказчику заранее.

Кэш компонентов прячет свежие правки шаблона до момента своего сброса. Правка не видна до сброса кэша, и на стенде его либо отключают на время работы, либо сбрасывают после каждой заметной правки.

Страницы разделов каталога не появляются от вёрстки. Их даёт настройка адресов комплексного компонента, и ошибку «страница не найдена» после натяжки разбирают именно там, а не в разметке.

Каталог шаблонов самой платформы при натяжке трогать не нужно вовсе. Свой шаблон кладут в каталог проекта: шаблон рядом с системными переживёт только до ближайшего обновления продукта.

Вёрстка со своей сборкой требует отдельной договорённости. Где лежат исходники, что попадает в репозиторий и кто собирает бандл при выкладке - решают до начала натяжки, а не после неё.

Типичные проблемы

После установки шаблона сайт отдаёт белый экран.

В файле шаблона фатальная ошибка, а вывод ошибок выключен. Показ ошибок включают на стенде и читают имя файла со строкой.

На внутренних страницах пропали стили и картинки.

Пути к файлам оставлены относительными и считаются от адреса страницы. Пути строят от каталога шаблона, а не от адреса текущей страницы.

В админке нет панели управления и режима правки.

В шапке шаблона нет вызова панели управления или он стоит не на своём месте. Он ставится сразу после открывающего тега тела страницы.

Заголовок страницы и метатеги не подставляются.

В шапке нет вызова заголовка и вывода ресурсов платформы. Без них не работают ни метатеги, ни подключение стилей компонентов.

Меню в шапке не меняется при правке структуры.

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

Разделы каталога отдают «страница не найдена».

Адреса комплексного компонента не настроены или не совпадают с правилом обработки. К натянутой вёрстке эта ошибка никакого отношения обычно не имеет.

Частые вопросы

Где ставить точку разреза шаблона?

Там, где начинается содержимое страницы: всё выше уедет в шапку, всё ниже - в подвал. Обёртки содержимого оставляют в шаблоне, чтобы каждая страница не повторяла их своими руками.

Как натянуть вёрстку на комплексный компонент?

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

Почему после натяжки белый экран?

Почти всегда это фатальная ошибка в коде шаблона: пропущенная скобка, лишний тег закрытия или обращение к несуществующему объекту. Включённый на стенде показ ошибок отвечает точнее любых догадок.

Куда девать статические блоки из макета?

Навигацию и списки - в компоненты, правимые куски текста - во включаемые области, оформление - в стили шаблона. В разметке шаблона остаётся каркас, а не содержимое.

Можно ли положить шаблон в каталог платформы?

Технически можно, но обновление продукта его перезапишет. Свои шаблоны держат в каталоге проекта - это то же самое место, где живёт остальной свой код.

Смежное

Первоисточник