# Шаблоны сайта
← [К разделу «Как собирается сайт»](README.md)
Шаблон сайта — внешняя оболочка готовой страницы. Он содержит HTML-документ,
метаданные, общую шапку, навигацию, место основного содержимого и подвал.
## Минимальный контракт
```html
[tag:title]
[tag:rubheader]
[tag:navigation:main]
[tag:maincontent]
[tag:sysblock:footer]
[tag:rubfooter]
```
Обязательный смысловой тег — `[tag:maincontent]`. Без него документ будет найден
и обработан, но содержимое рубрики не попадёт на страницу.
## Что размещать в шаблоне
- общий ``, CSS и JavaScript темы;
- шапку и подвал;
- общую навигацию;
- системные блоки, одинаковые для многих страниц;
- SEO-теги текущего документа;
- места для header/footer-вставок рубрики.
Карточку конкретной статьи или товара размещайте в шаблоне рубрики. Списки
документов принадлежат запросам или каталогу. Это уменьшает количество условий в
глобальной оболочке.
## Палитра тегов
Палитра строится из реестра и показывает актуальные блоки, навигации, запросы и
системные значения. После выбора тег вставляется в текущую позицию редактора, а
панель закрывается.
Предпочитайте alias вместо числового ID:
```text
[tag:navigation:main]
[tag:request:latest_news]
[tag:sysblock:footer]
```
Так шаблон легче переносить между установками, если системные ID различаются.
## Модульные Twig-компоненты
Сложный модуль может вернуть HTML из внутреннего Twig-шаблона, но в шаблон сайта
он всё равно вставляется обычным зарегистрированным тегом:
```text
[mod_search]
[mod_basket:mini]
```
Не указывайте путь к Twig-файлу непосредственно в шаблоне. Перед созданием
нового компонента проверьте, нельзя ли решить задачу рубрикой, запросом, блоком,
навигацией или существующим модульным тегом. Полный контракт описан в главе
[«Точечные Twig-компоненты»](twig-components.md).
## PHP и проверка
Шаблон может содержать проектный PHP, но ошибка нарушит все страницы, которые его
используют. Перед сохранением запускайте проверку синтаксиса. Общую бизнес-логику
лучше держать в сервисах и hooks, оставляя в шаблоне композицию и небольшие
условия.
Не выполняйте запросы к БД в цикле карточек. Подготовьте данные запросом,
каталогом, блоком или сервисом до рендера.
## Сохранение и кеш
Источник шаблона хранится в БД. После сохранения система атомарно обновляет
файловый кеш публичного рендера. Путь кеша является внутренней деталью; не
редактируйте `.inc` вручную, иначе следующее сохранение перезапишет изменения.
Кнопка пересборки кеша создаёт файлы заново из БД. Она нужна после переноса,
восстановления файлов или диагностики, а не после каждого обычного сохранения.
## Ревизии
При создании, сохранении, копировании, импорте и восстановлении создаются
ревизии. Восстановление сначала сохраняет текущее состояние как резервное, затем
применяет выбранный снимок и обновляет кеш.
Шаблон №1 системный и не удаляется. Другой шаблон нельзя удалить, пока его
использует хотя бы одна рубрика.
## Порядок изменения дизайна
1. Создайте копию шаблона.
2. Назначьте её тестовой рубрике или документу.
3. Проверьте обычную страницу, 404, пагинацию, формы и авторизованное состояние.
4. Проверьте мобильную ширину и отсутствие горизонтальной прокрутки.
5. После проверки переключите рабочие рубрики.
6. Старый шаблон удаляйте только после периода наблюдения.