Вигляди на тегах: як переробити сторінку без 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}.