Теги шаблонов: справочник

Кроме обычных подстановок, условий и циклов Smarty, теме доступны теги самого магазина. Ниже — все они.

Тег	Для чего
{money}	сумма с валютой
{qty}	дробное количество
{url}	адрес раздела витрины
{trans}	надпись темы, в том числе со склонением
{thumb}	эскиз фотографии нужного размера
{csrf_field} {csrf_token}	защита формы
{captcha}	проверка «я не робот»
{asset_css} {asset_js}	подключить свой стиль или скрипт
{assets_head} {assets_footer}	вывести собранный список файлов
{hook}	место для дополнений
{dump} {dumpc}	посмотреть, что пришло в шаблон

Деньги#

{money amount=$product.price currency=$storefront.currency}
{money amount=$order.total currency=$order.currency}
{money amount=$shop->cartTotal() currency=$storefront.currency precision=0}

Параметр	По умолчанию	Что задаёт
amount	0	сумма
currency	USD	валюта
locale	текущий язык	как разделять разряды и дробную часть
precision	как в валюте	сколько знаков после запятой

⚠️ Валюту передавайте всегда. По умолчанию тег форматирует сумму долларами, и на тестовом магазине с валютой по умолчанию ошибку не видно — а в гривневом магазине цена уедет с долларовым знаком.

precision=0 пригодится там, где копейки ломают вёрстку: сумма корзины в шапке, подпись на карточке.

Тег только форматирует число. Считать в шаблоне не нужно и нельзя — почему, написано на странице Цены, количества и валюта.

Количества#

{qty value=$item.qty} {$item.unit}     →  30,8 м²

Товары бывают дробными: метры, килограммы, площадь. Тег выводит число по-местному («30,8», а не «30.8»), отбрасывает хвостовые нули («2», а не «2,000») и не ставит разделитель разрядов — это же число подставляется в поле ввода количества, а «1 200» браузер прочитал бы как «1».

Адреса разделов#

<a href="{url path='/search'}">Поиск</a>
<a href="{url path='/'}">На главную</a>
<a href="{url path='/cart' locale='uk'}">Кошик</a>

Параметр	По умолчанию	Что задаёт
path	/	путь раздела
locale	текущий язык	язык, на котором открыть раздел
absolute	нет	полный адрес с доменом вместо пути

Тег сам добавляет языковой префикс и приводит адрес к виду, принятому в магазине. Полный адрес нужен только поисковику — для ссылок внутри сайта берите обычный.

Адреса товаров, категорий, брендов, меток и страниц уже приходят готовыми в данных ($product.url, $cat.url). Склеивать их руками нельзя: схему адресов выбирает владелец магазина. Подробности — на странице Адреса разделов и языки.

Надписи темы#

{trans key="shop.cart"}
{trans key="shop.products_count" count=$total}
{trans key="shop.hello" name=$customer.first_name}

Строка берётся из файла темы locale/<язык>.json, а если ключа там нет — из надписей самого магазина. Не нашлось нигде — выведется сам ключ: страница не падает, но в вёрстке будет висеть shop.cart.

Всё, кроме key, считается подстановкой: {trans key="shop.hello" name="Иван"} подставит имя вместо :name в строке.

Параметр count включает выбор формы по числу — «1 товар», «2 товара», «5 товаров». Как записать такую строку, написано на странице Тексты темы и языки.

Эскизы фотографий#

<img src="{thumb src=$product.image size=320}" alt="{$product.name}">
<img src="{thumb src=$product.image size=120 type='crop'}" alt="">

type	Что делает
max (по умолчанию)	вписывает картинку целиком в квадрат со стороной size
crop	обрезает до квадрата size × size
width	задаёт ширину, высота считается сама
height	задаёт высоту, ширина считается сама

Эскизы нарезаются по требованию: первый покупатель, открывший страницу, ждёт нарезку, дальше файл отдаёт веб-сервер напрямую. Если возможность выключена в настройках или файл лежит не на публичном диске, тег вернёт исходный адрес — картинка покажется, просто в полном размере.

Формы#

<form method="post" action="/reviews/submit">
    {csrf_field}
    …
    {captcha form="reviews"}
    <button type="submit">Отправить</button>
</form>

{csrf_field} ставит скрытое поле — без него форма не пройдёт. {csrf_token} отдаёт тот же ключ строкой; в каркас его вставлять не надо — мета-тег csrf-token печатает магазин, а скриптам ключ приходит в CartiX.csrf.

{captcha form="…"} сам спрашивает, включена ли проверка «я не робот» для этой формы, и рисует нужный виджет. Проверка выключена — тег не выводит ничего, и ветку {if} вокруг него писать не надо.

Подробнее — на странице Формы витрины.

Печатные формы заказа#

{assign var="invoice" value={order_document order=$order code="order.invoice"}}
{if $invoice}
    <a href="{$invoice}" target="_blank" rel="noopener">Счёт на оплату</a>
{/if}

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

order — заказ кабинета ($order на странице account/order.html), его номер или заказ, пришедший в шаблон. code — код бланка: он написан в самой форме, в «Настройки» → «Печатные формы», строкой «Код бланка» рядом с названием, и копируется кнопкой. pdf=true — та же бумага файлом:

{assign var="pdf" value={order_document order=$order code="order.delivery_note" pdf=true}}
{if $pdf}<a href="{$pdf}">Скачать накладную</a>{/if}

Печать по клику#

Обычная ссылка открывает бумагу и оставляет покупателя один на один с вопросом, чем её напечатать: на телефоне печать спрятана в меню «Поделиться». Скажите print=true — страница откроет окно печати сама, как только загрузится:

{assign var="doc" value={order_document order=$order code="order.invoice" print=true}}
{if $doc}
    <a href="{$doc}" target="_blank" rel="noopener">Распечатать счёт</a>
{/if}

Печать вызывается после полной загрузки, а не сразу: иначе лист уходит в принтер без логотипа и печати, которые не успели загрузиться. С pdf=true параметр не нужен и не действует — там окно печати открывает программа просмотра файла.

Если не хочется уводить покупателя на другую вкладку, печатайте в скрытой рамке — это те же несколько строк, библиотека для этого не нужна:

<a class="js-print" href="{order_document order=$order code="order.invoice"}">Распечатать счёт</a>

{literal}
<script>
document.addEventListener('click', function (e) {
    var link = e.target.closest('.js-print');
    if (!link) return;

    e.preventDefault();

    var frame = document.createElement('iframe');
    frame.style.cssText = 'position:fixed;right:0;bottom:0;width:0;height:0;border:0';
    frame.src = link.getAttribute('href');
    frame.onload = function () { frame.contentWindow.focus(); frame.contentWindow.print(); };
    document.body.appendChild(frame);
});
</script>
{/literal}

Рамку не убирайте сразу после print() — пока открыто окно печати, документ обязан оставаться на странице. Один и тот же приём работает для любого бланка: достаточно поменять код формы в ссылке.

Документ на другом языке#

По умолчанию бумага выходит на языке заказа: покупатель оформлял по-украински — и счёт будет украинский, даже если сейчас он смотрит магазин по-русски. Нужен другой язык — скажите об этом прямо:

{assign var="en" value={order_document order=$order code="order.invoice" locale="en"}}
{if $en}<a href="{$en}">Invoice in English</a>{/if}

Языком можно распорядиться и по-своему — например, дать бумагу на том языке, на котором покупатель сейчас смотрит магазин:

{assign var="doc" value={order_document order=$order code="order.invoice" locale=$storefront.locale}}
{if $doc}<a href="{$doc}">Счёт на оплату</a>{/if}

Вместе с pdf это тоже работает:

{order_document order=$order code="order.invoice" locale="en" pdf=true}

Просить можно только язык, на котором работает сам магазин («Основные настройки» → «Региональные настройки»). Незнакомый код тег молча пропускает мимо ушей — бумага выйдет на языке заказа, а не пустой. Если бланк на нужном языке не написан, магазин возьмёт его на своём основном: счёт на чужом языке лучше пустого листа.

Где показывать документы и какие — решает тема: в кабинете, на странице «Заказ оформлен», в письме. Магазин отвечает за две вещи, в которых тема ошибиться не может:

• ссылку получает только тот, чей это заказ — вошедший покупатель со своим заказом либо гость, оформивший его в этой же сессии;
• выключенный или пустой бланк ссылки не даёт вовсе, иначе кнопка вела бы на «страница не найдена».

В обоих случаях тег возвращает пустую строку — поэтому ссылку прячут обычным {if}, как в примерах выше.

Адрес построен на личном ключе заказа — том же, по которому покупатель попадает на оплату. Своего секрета у документа нет, и такую ссылку можно положить в письмо. Помните: кто ссылку получил, тот документ и откроет.

Стили и скрипты#

{block name="page_assets"}
    {asset_css file="css/product.css"}
    {asset_js file="js/product.js" defer=true}
{/block}

Параметр	Что делает
file	путь внутри assets/ вашей темы
inline	вставить содержимое прямо в страницу, а не ссылкой
key	имя, по которому файл не подключится дважды
head / footer	куда выводить
остальные	уезжают атрибутами в <link> или <script>

{assets_head} и {assets_footer} выводят собранный список. Подробности и подвохи — на странице Стили, скрипты и картинки темы.

Место для дополнений#

{hook name="product.buybox.end" product=$product}

Сюда дополнения выводят свою разметку. Подписчиков нет — тег не выводит ничего. Каждое дополнение вызывается отдельно и в защите от ошибок: упавшее не выводит ничего, страница остаётся живой.

Всё, что передано параметрами, уезжает дополнению — поэтому полезно передавать контекст: товар, позицию корзины. Полный список мест — на странице Точки для дополнений.

Посмотреть, что пришло в шаблон#

{dump}                    всё, что доступно этому шаблону
{dump var=$product}       одно значение
{dumpc var=$product}      то же самое в консоль браузера
{$product|dump nofilter}  привычной записью

Видит только сотрудник магазина. Покупателю блок не покажется, даже если тег забыли в теме. Пароли, ключи и подписи в выводе заменяются звёздочками, глубина ограничена шестью уровнями, длинные списки и строки обрезаются.

Теги дополнений#

Дополнение может завести собственный тег — он появится во всех темах сразу. Установленные сейчас:

Тег	Дополнение
{slider id="home-hero"}	Слайдеры и баннеры
{slider_data id="home-hero" assign=hero}	то же, отдаёт данные в переменную
{oneclick_button product=$product}	Купить в один клик
{back_in_stock product=$product}	Сообщить о поступлении
{callback_button}	Обратный звонок
{shorturl url=$product.url}	Короткие ссылки

Тег выключенного дополнения, оставленный в шаблоне, не ломает страницу — он просто ничего не выводит. Поэтому тема может ссылаться на теги дополнений, не проверяя, стоят ли они.

Что приносит установленное дополнение, видно двумя способами: в его описании в разделе «Дополнения» и по папке templates/plugins/<дополнение>/ в вашей теме — дополнение с собственной разметкой кладёт шаблоны прямо туда.

Обработчики значений#

В Smarty 5 в шаблон нельзя писать любую функцию языка. Магазин возвращает безопасный набор:

Текст. ucfirst, lcfirst, ucwords, trim, ltrim, rtrim, str_pad, str_replace, str_contains, str_starts_with, str_ends_with, sprintf, strrev, mb_strlen, mb_substr, mb_strtolower, mb_strtoupper, urlencode, rawurlencode, htmlspecialchars_decode.

Числа. abs, ceil, floor, intval, floatval, max, min, intdiv.

Списки. array_keys, array_values, array_slice, array_reverse, array_sum, array_unique, array_flip.

Отладка. dump, dumpc.

Сверх этого работает всё, что Smarty умеет сам: count, round, implode, substr, json_encode, date_format, escape, default, upper, nl2br, truncate, strip_tags.

{$product.name|mb_strtoupper}
{$product.summary|truncate:120:'…'}
{$product.price|default:0}
{$order.created_at|date_format:'%d.%m.%Y'}

Незнакомый обработчик страницу не ломает: значение проходит насквозь, а имя уходит в журнал. Так опечатка не превращается в белый экран у покупателя — но и не даёт о себе знать, поэтому перед выкладкой в журнал стоит заглянуть.

Экранирование#

Всё, что выводится, экранируется само. {$product.name} безопасен всегда, даже если в названии товара есть < или кавычки.

Там, где данные содержат готовую разметку, нужен nofilter:

{$page.content nofilter}       содержимое информационной страницы
{$product.description nofilter} описание товара
{$product.json nofilter}       карта вариантов покупки для браузера

Забыли nofilter — покупатель увидит текст с <p> вместо абзацев.

Чего в теме нет#

Теги {sum}, {in_words}, {number} и {profile} относятся к печатным бланкам — счетам, накладным, чекам, — а не к витрине. В шаблоне темы их нет. Про них написано в разделе Печатные бланки.