Tag-based views: how to redo a page without PHP

Any view of the site (home page, sign-in, registration, search, account, page) can be replaced with a tag file. It is plain HTML markup into which you insert the tags {name}, the conditions [if:name]…[/if] and the repeats [each:list]…[/each] (the common tag language, the same as in “News → Post templates”).

How to turn it on

In your theme, put a file at the path of the view, ending in .tpl.html instead of .php:

If there is no tag file or it is broken (for example, a block is not closed), the regular PHP view works and the page does not break. A tag file in the theme's common folder takes precedence over a module's view, just like a PHP file.

Main layout: an example in 15 lines

<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}">Sign in</a>[/if]
</header>
<main>{content}</main>
<aside>{region:sidebar}</aside>
<footer>© {year} {site_name}</footer>

Put this in themes/<name>/views/layouts/main.tpl.html and the page gets your header with the menu, language switcher, search and sign-in, the content, a sidebar and a footer. <head>, the engine scripts and the “back to top” button stay with the engine; styles and fonts are connected through theme.json and assets — you do not need to write them in the tag file.

Common tags for any page

Tags from view data, conditions, repeats

Next come the data the view received from the engine: {name}, {a.b}, [each:list] with {item}, {item.key}, {index}, the conditions [if:name], [if:name=value], [ifnot:name], and the option limit=N. Secrets (form protection keys, passwords, tokens, sessions) and objects are not exposed through tags.

Core views on tags

A form in parts

In views with a form (sign-in, registration, recovery, password reset, second factor, email confirmation, rules, search, account) you can output the whole form with the {form} tag, which is the safe way, or assemble it from parts to place the fields in the order you want:

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

A field that is not in your template does not appear in the form: the arrangement is the theme's choice. Do not leave out the required fields or the “not a robot” check, or the form will not pass validation.

The word {t.tail} gives an interface label “<view prefix>.<tail>” in the visitor's language, so the texts in the template are not duplicated for different languages.

Discussion (comments) on tags

The theme's file views/comments/thread.tpl.html replaces the discussion view under a post, a page and other materials. If the file is missing or fails validation, the regular view works.

Example:

<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>

Filtered lists, archive, tags, categories and site numbers (“News” module)

These tags work in any tag file: in the main frame, on a page, in a feed. The filter is written in the list name itself as “key:value” pairs separated by colons; several values are joined with “_”. Protection keys, email addresses and anything private never get into lists; posts are selected by the same query as the feed (permissions, password, language, validity period).

In the news_list item: {item.id} {item.title} {item.url} {item.excerpt} {item.date} {item.cover} {item.cover_large} {item.category} {item.category_url} {item.by} (the author, if the site shows authors) {item.views} {item.rating} {item.rating_count} {item.comments} {item.pinned} {item.locked} (a password-protected post: only the title is visible) {item.first} {index}. In comments_list: {item.name} {item.text} (up to 160 characters, no markup) {item.url} {item.date} {item.title} (post title) {item.avatar}. In news_archive: {item.title} {item.url} {item.count}. In news_tags: {item.title} {item.url} {item.count} {item.weight} (1–5, for the font size). In news_categories: {item.title} {item.url} {item.count} {item.active} (the current category) {item.level} (0 is the top level) {item.parent} {item.id} [if:item.has_children].

Site numbers: {stat.news} {stat.news_day} {stat.news_week} {stat.news_month}, and the same for comments and users ({stat.comments_week}, {stat.users_month}).

Example of “Categories with post counts” and “Popular this 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>Popular</h3>
[each:news_list:days:30:sort:views:limit:5]<p><a href="{item.url}">{item.title}</a> · {item.views}</p>[/each]
<p>Posts: {stat.news}, this week: {stat.news_week}</p>

“Downloads” on tags

A template for a category. News, “Downloads”, the forum (section) and the shop (category) tell the engine the category of the page (a category address in Latin letters, digits and hyphens, up to 40 characters). Then the file <view>.<category-slug>.tpl.html (for example, views/news/show.tech.tpl.html or views/forum/section.api.tpl.html) is taken before the general <view>.tpl.html; for the other categories the general one stays. The module also passes the page category's description (without markup) into the common page data; the core provides the {category.description} tag. Text trimming in post tags: limit=N characters, words=N words, wordsafe=1 to cut at a word boundary.

The theme's files views/downloads/index.tpl.html (catalog and category) and views/downloads/show.tpl.html (release page) replace the module's PHP views. Downloading goes through the engine's regular addresses: the counter, access restrictions and passwords work as before.

Example of a release page:

<h1>{item.title}</h1><p>v{item.version} · {date} · downloaded {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>What's new</h2><p>{item.changelog}</p>
<h2>Requirements</h2><p>{item.requirements}</p>
[each:sums]<code>{item.name}: {item.checksum}</code>[/each]

Banners on tags

In any tag file a banner is placed by number or as a whole place. The display rules are the same as for regular banners: period, schedule, device, pages, roles, countries, “first page only”.

The places between_feed and between_comments are drawn by the news and comments views themselves: a banner appears after every third feed post and after every fifth comment. In the panel, a banner has roles (guest is a guest), countries (RU, UA means only those; -BY means everywhere except) and “first page of the section only”. A page that has such a banner does not go into the shared cache, because the response depends on the viewer.

Insert catalog: any module element with one tag

Each module declares everything that can be moved to any page and inserted anywhere in the theme's tag file: ready-made blocks, lists for your own markup, numbers, forms and buttons. It is a single catalog, and from it are built the “Output on the site” tab in the module's panel (a table of elements, parameters, an example and the “Copy” button, view files), the template editor's hints and this table.

How to insert:

• a block, form, button or number: {block:module.name param=value}, for example {block:news.count what=news period=week}; up to four parameters;
• a list for your own markup: [each:list:module_name:param:value:…] … {item.field} … [/each], for example [each:list:news_latest:cat:3:sort:views:limit:5]; several values are joined with “_”, in the list name “module_name” (a dot in a tag name does not work).

A rule for the module: an element of the kind block, button or form is responsible for escaping its own output (through e() and the engine's views, like any view); a number and text (value) are only escaped text without markup; a list returns rows, and the tags escape them. The catalog validates parameters but does not sanitize foreign markup. Parameters are validated against the element's description: a number must be within bounds, a choice only from the list, identifiers only digits; anything extra is dropped. A failure, a missing permission, or exceeding the time or size limit gives an empty insert, and the page stays intact. The old tags (news_list…, {banner:5}, [each:comments]) keep working.

How a module declares an element (the filter theme.blocks, the entry “module.name” → module, kind (block, list, value, form, button), title, description, params, items, example, works_in, permission, render) is described in core/Themes/BlockCatalog.php. The ready-made layout blocks of modules (what a module puts into the theme's places) get into the catalog by themselves, and their kind in the table is marked “block”. The table below is built by the script php dev/katalog-spravka.php from the catalog and is not written by hand.

Security

• Only the engine draws forms: in a tag file the <form> tag is stripped, so the protection key and the fields are always in place. The form is output by {form}.
• Template markup is sanitized against a whitelist: no script, style, iframe, event handlers or data-* attributes; addresses may only be http(s)://, /path, #.
• Values are escaped in place (differently in text, in an attribute and in an address).
• The limits are the same as for the tag language: template size 20000 characters, 400 tags, nesting 6, repeats 200.
• Emails are not needed in tag files: their texts are edited in “Mail → Site emails”.

Extra fields of news: where they work (after the move to “Extra fields”)

Fields are created in the “Extra fields” section (host “News”, can be limited to categories). An empty field is not shown anywhere: neither the value nor the label.

An address with field=…&value=… shows a “Label: value” badge above the feed and a “Clear filter” button. Closed fields (staff only, by role) are not exposed through tags or in RSS.

“Suggest an entry” on tags (“News” module)

Theme files: views/news/suggest.tpl.html (the form for a signed-in user) and views/news/suggest-login.tpl.html (for a guest: an explanation and sign-in buttons). If there is no file, the page works as before.

The form is written by the engine (protection key, robot trap, validation): as a whole with {form}, or in parts with {form_open} … {form_close}:

The page for a guest: {login_url}, {register_url}, [if:can_register], the words {t.guest_title} {t.guest_text} {t.guest_login} {t.guest_register}.