Виды на тегах: как переделать страницу без PHP

Любой вид сайта (главную, вход, регистрацию, поиск, кабинет, страницу) можно заменить файлом тегов. Это обычная HTML-разметка, в которую вставляются теги {имя}, условия [if:имя]…[/if] и повторы [each:список]…[/each] (общий язык тегов, тот же, что в «Новости → Шаблоны записей»).

Как включить

В вашей теме положите файл по пути вида с окончанием .tpl.html вместо .php:

Нет файла тегов или он сломан (например, не закрыт блок) — работает обычный PHP-вид, страница не ломается. Файл тегов в общей папке темы главнее вида модуля, как и PHP-файл.

Главная разметка: пример в 15 строк

<header class="my-head">
  <a href="{home}">{site_name}</a>
  [each:menu]<a href="{item.url}">{item.title}</a> [/each]
  {languages} {search}
  [if:user.logged]<a href="{user.url}">{user.name}</a>[else]<a href="{user.login_url}">Войти</a>[/if]
</header>
<main>{content}</main>
<aside>{region:sidebar}</aside>
<footer>© {year} {site_name}</footer>

Положите это в themes/<имя>/views/layouts/main.tpl.html — и страница получит вашу шапку с меню, выбором языка, поиском и входом, содержимое, боковую колонку и подвал. <head>, скрипты движка и кнопка «наверх» остаются от движка; стили и шрифты подключаются через theme.json и assets — в файле тегов их писать не нужно.

Общие теги любой страницы

Теги из данных вида, условия, повторы

Дальше идут данные, которые вид получил от движка: {имя}, {a.b}, [each:список] с {item}, {item.ключ}, {index}, условия [if:имя], [if:имя=значение], [ifnot:имя], опция limit=N. Секретное (ключи защиты форм, пароли, токены, сеансы) и объекты через теги не отдаются.

Виды ядра на тегах

Форма по частям

В видах с формой (вход, регистрация, восстановление, сброс пароля, второй фактор, подтверждение почты, правила, поиск, кабинет) форму можно вывести целиком тегом {form} — это безопасный путь, или собрать по частям, чтобы расставить поля в нужном порядке:

{form_open}
  {field:email}
  {field:password}
  {field:captcha}
  {submit}
{form_close}

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

Слово {t.хвост} даёт подпись интерфейса «<приставка вида>.<хвост>» на языке посетителя, поэтому тексты в шаблоне на разные языки не дублируются.

Обсуждение (комментарии) на тегах

Файл views/comments/thread.tpl.html темы заменяет вид обсуждения под записью, страницей и другими материалами. Нет файла или он не прошёл проверку — работает обычный вид.

Пример:

<section id="comments"><h2>{comments.word}: {comments.total}</h2>
[each:comments]
<article id="comment-{item.id}" class="c c-l{item.level}"><b>{item.name}</b> <time>{item.date}</time>
<div>{item.text}</div><footer>{item.actions}</footer></article>
[/each]
{pager}
[if:can_write]{compose}[else]{notice}[/if]
</section>

Списки с отбором, архив, метки, рубрики и числа сайта (модуль «Новости»)

Эти теги работают в любом файле тегов: в главной рамке, на странице, в ленте. Отбор записан в самом имени списка парами «ключ:значение» через двоеточие; несколько значений — через «_». Ключи защиты, почта и закрытое в списки не попадают; записи отбираются тем же запросом, что и лента (права, пароль, язык, срок действия).

В элементе news_list: {item.id} {item.title} {item.url} {item.excerpt} {item.date} {item.cover} {item.cover_large} {item.category} {item.category_url} {item.by} (автор, если сайт показывает авторов) {item.views} {item.rating} {item.rating_count} {item.comments} {item.pinned} {item.locked} (запись под паролем: видно только название) {item.first} {index}. В comments_list: {item.name} {item.text} (до 160 знаков, без разметки) {item.url} {item.date} {item.title} (название записи) {item.avatar}. В news_archive: {item.title} {item.url} {item.count}. В news_tags: {item.title} {item.url} {item.count} {item.weight} (1–5, для размера шрифта). В news_categories: {item.title} {item.url} {item.count} {item.active} (текущая рубрика) {item.level} (0 — верхний уровень) {item.parent} {item.id} [if:item.has_children].

Числа сайта: {stat.news} {stat.news_day} {stat.news_week} {stat.news_month}, то же для comments и users ({stat.comments_week}, {stat.users_month}).

Пример «Рубрики с числом записей» и «Популярное за месяц»:

<nav><ul>
[each:news_categories]<li class="l{item.level}"><a href="{item.url}">{item.title}</a> <small>{item.count}</small></li>[/each]
</ul></nav>
<h3>Популярное</h3>
[each:news_list:days:30:sort:views:limit:5]<p><a href="{item.url}">{item.title}</a> · {item.views}</p>[/each]
<p>Записей: {stat.news}, за неделю: {stat.news_week}</p>

«Загрузки» на тегах

Шаблон под рубрику. Новости, «Загрузки», форум (раздел) и магазин (категория) называют рубрику страницы движку (адрес рубрики латиницей, цифрами и дефисом, до 40 знаков). Тогда файл <вид>.<адрес-рубрики>.tpl.html (например, views/news/show.tech.tpl.html или views/forum/section.api.tpl.html) берётся раньше общего <вид>.tpl.html; для остальных рубрик остаётся общий. Описание рубрики страницы (без разметки) модуль тоже отдаёт в общие данные страницы; тег {category.description} подключает ядро. Обрезка текста в тегах записи: limit=N знаков, words=N слов, wordsafe=1 — по границе слова.

Файлы views/downloads/index.tpl.html (каталог и рубрика) и views/downloads/show.tpl.html (страница релиза) темы заменяют PHP-виды модуля. Скачивание идёт обычными адресами движка: счётчик, ограничение доступа и пароли работают как раньше.

Пример страницы релиза:

<h1>{item.title}</h1><p>v{item.version} · {date} · скачано {item.hits}</p>
[if:allow_download]
[each:files]<p><a href="{item.url}">{item.name}</a> {item.platform} {item.arch} {item.size} ↓{item.hits}</p>[/each]
[/if]
<h2>Что нового</h2><p>{item.changelog}</p>
<h2>Требования</h2><p>{item.requirements}</p>
[each:sums]<code>{item.name}: {item.checksum}</code>[/each]

Баннеры на тегах

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

Места between_feed и between_comments рисуют сами виды новостей и комментариев: баннер идёт после каждой третьей записи ленты и после каждого пятого комментария. У баннера в панели отмечаются роли (guest — гость), страны (RU, UA — только в них; -BY — везде, кроме) и «только на первой странице раздела». Страница, где есть такой баннер, не уходит в общий кэш: ответ зависит от зрителя.

Каталог вставок: любой элемент модуля — одним тегом

Каждый модуль объявляет всё, что можно вынести на любую страницу и вставить в любое место файла тегов темы: готовые блоки, списки для своей вёрстки, числа, формы и кнопки. Это единый каталог: из него строятся вкладка «Вывод на сайте» в панели модуля (таблица элементов, параметры, пример и кнопка «Копировать», файлы видов), подсказки редактора шаблонов и эта таблица.

Как вставляется:

• блок, форма, кнопка, число — {block:модуль.имя параметр=значение}: {block:news.count what=news period=week}; параметров до четырёх;
• список для своей вёрстки — [each:list:модуль_имя:параметр:значение:…] … {item.поле} … [/each]: [each:list:news_latest:cat:3:sort:views:limit:5]; несколько значений — через «_», в имени списка «модуль_имя» (точка в имени тега не годится).

Правило для модуля: элемент вида block, button и form сам отвечает за экранирование своего вывода (через e() и виды движка, как любой вид); число и текст (value) — только экранированный текст без разметки; список отдаёт строки, они экранируются тегами. Каталог проверяет параметры, но чужую разметку не чистит. Параметры проверяются по описанию элемента: число — в границах, выбор — только из списка, номера — только цифры; лишнее отбрасывается. Сбой, право, которого нет, превышение времени или размера — пустая вставка, страница цела. Старые теги (news_list…, {banner:5}, [each:comments]) продолжают работать.

Как модуль объявляет элемент (фильтр theme.blocks, запись «модуль.имя» → module, kind (block, list, value, form, button), title, description, params, items, example, works_in, permission, render) — описано в core/Themes/BlockCatalog.php. Готовые блоки раскладки модулей (то, что модуль кладёт в места темы) попадают в каталог сами — их вид в таблице помечен «блок». Таблица ниже собирается скриптом php dev/katalog-spravka.php из каталога, руками не пишется.

Безопасность

• Формы рисует только движок: в файле тегов тег <form> вычищается, поэтому ключ защиты и поля всегда на месте. Форму выводит {form}.
• Разметка шаблона очищается по белому списку: без script, style, iframe, обработчиков событий и атрибутов data-*; адреса только http(s)://, /путь, #.
• Значения экранируются по месту (в тексте, в атрибуте, в адресе по-разному).
• Пределы те же, что у языка тегов: размер шаблона 20000 знаков, 400 тегов, вложенность 6, повторов 200.
• Письма в файлах тегов не нужны: их тексты правятся в «Почта → тексты писем».

Доп. поля новостей: где работают (после переноса в «Доп. поля»)

Поля заводятся в разделе «Доп. поля» (хозяин «Новости», можно ограничить рубриками). Пустое поле нигде не показывается: ни значение, ни подпись.

Адрес с field=…&value=… показывает над лентой плашку «Подпись: значение» и кнопку «Сбросить отбор». Закрытые поля (только для персонала, по ролям) тегами и в RSS не отдаются.

«Предложить запись» на тегах (модуль «Новости»)

Файлы темы: views/news/suggest.tpl.html (форма для вошедшего) и views/news/suggest-login.tpl.html (гостю: пояснение и кнопки входа). Нет файла — страница как раньше.

Форма пишется движком (ключ защиты, ловушка от роботов, проверка): целиком — {form}, либо по частям {form_open} … {form_close}:

Страница для гостя: {login_url}, {register_url}, [if:can_register], слова {t.guest_title} {t.guest_text} {t.guest_login} {t.guest_register}.