Insert catalogue, extra fields and informers on tags
How to place any block, list, number or form of a module with one tag, where the extra fields of news work, and how to show a foreign feed on a page.
The insert catalogue: any module element with one tag
Every module declares everything that can be put on any page and inserted anywhere in a theme tag file: ready blocks, lists for your own markup, numbers, forms and buttons. This is one catalogue: the «On the site» tab of a module's panel (elements table, parameters, an example with a «Copy» button, view files), the template editor hints and the Help pages about each module are built from it. See the full list of elements with ready code on the module page in Help (/help/modules/module-name): it always matches what is on your site.
How to insert:
- a block, form, button or number —
{block:module.name parameter=value}:{block:news.count what=news period=week}; up to four parameters; - a list for your own markup —
[each:list:module_name:parameter:value:…] … {item.field} … [/each]:[each:list:news_latest:cat:3:sort:views:limit:5]; several values are joined with «_», in the list name «module_name» (a dot is not allowed in a tag name).
{block:news.count what=news period=week}
{block:subscribe.compact}
[each:list:shop_products:limit:4]<p>{item.title}</p>[/each]A block, button or form element escapes its own output itself (through e() and the engine views, like any view); a number or text is only escaped text without markup; a list returns rows, which the tags escape. Parameters are checked against the element's description: a number within limits, a choice only from the list, ids only digits; the rest is dropped. A failure, a missing right, an exceeded time or size — an empty insert, the page stays whole. Old tags (news_list…, {banner:5}, [each:comments]) keep working.
A module declares an element through the theme.blocks filter: a «module.name» entry with the fields kind (block, list, value, form, button), title, description, params, items, example, works_in, permission, render. Ready layout blocks of modules (what a module puts into theme places) get into the catalogue by themselves.
Tag safety
- only the engine draws forms: the form tag is stripped from a tag file, so the protection key and the fields are always in place; a form is printed with
{form}; - template markup is cleaned by a white list: no scripts, styles, frames, event handlers or
data-*attributes; addresses onlyhttp(s)://,/path,#; - values are escaped in place (in text, in an attribute, in an address — differently);
- the limits are those of the tag language: template size 20000 characters, 400 tags, nesting 6, repeats 200;
- letters are not needed in tag files: their texts are edited in «Mail → letter texts».
Extra fields of news: where they work
Fields are created in the «Extra fields» section (owner «News», can be limited to categories). An empty field is never shown: neither the value nor the label.
| Where | What to write | Condition |
|---|---|---|
| Full post | {field:name}, {fieldlabel:name}, [if:field:name], {fieldurl:name} | the field is visible to this reader |
Feed card (index.tpl.html, [each:cards]) | {item.field:name}, {item.fieldlabel:name}, {item.fieldurl:name}, [if:item.field:name] | the «in list» box; a closed post (under a password) has no fields |
Lists and blocks ([each:news_list …], [each:list:news_latest], {block:news.latest_box}) | the same tags with item. | the same |
| Selecting posts | [each:news_list field:year>2000 field:genre=drama], custom=name (filled), custom=name is=value | a field with the «filter» box (otherwise the list is empty, not the whole feed) |
| Value as a link («Director: Nolan» → all posts with this value) | automatic on the post page; in lists — {item.fieldurl:name} in a link address; the address looks like /news/category?field=name&value=value | the «filter» and «value as a link» boxes; kinds: string, choice list, number, fraction |
| Search in the panel | the search line of the post list finds field values | the «search» box |
| RSS | «Label: value» is added to the post description | the «give to RSS» box; public fields only |
| Replace across the site | «Search and replace» sees news field values | the right to replace |
An address with field=…&value=… shows a «Label: value» plate above the feed and a «Reset selection» button. Closed fields (staff only, by role) are never given by tags or in RSS.
Informers: foreign feeds on a page
In «Content → Informers» the owner connects another site's feed (RSS, Atom or JSON) under a short name. The site shows the last saved copy and does not wait for the foreign server; the copy is refreshed on a schedule. It is inserted as a block or a list anywhere in any view:
| What to write | What comes out |
|---|---|
{block:site.informer name=NAME limit=5} | a ready list of links to the feed posts (text=1 — with a short text) |
[each:list:site_informer_list:name:NAME:limit:5] … [/each] | your own view of each post |
In a list item: {item.title} {item.url} {item.date} (in the site format) {item.date_iso} {item.text} (short text, no markup) {item.by} {item.category} {item.image} (address of the first picture; empty if there is none) {item.image2} {item.image3} (second and third, if the feed has them) {item.images_count} (how many pictures, up to three). For JSON sources there are also fields named by the owner ({item.field}).
What comes from outside: only a title, a link, a date, a short text, an author, a category and a picture address — as plain text and only over http(s). The picture itself is not copied to the site: the visitor's browser takes it from the foreign server if the theme prints {item.image}. Links carry rel="nofollow noopener noreferrer ugc".
[each:list:site_informer_list:name:news:limit:3]
<article>[if:item.image]<img src="{item.image}" alt="" loading="lazy">[/if]
<a href="{item.url}" rel="nofollow noopener">{item.title}</a>
<small>{item.by} · {item.category} · <time datetime="{item.date_iso}">{item.date}</time></small></article>
[/each]