Теги Latte
Зведення та опис усіх вбудованих тегів Latte.
{$var} , {...} або {=...} |
друкує екрановану змінну або вираз |
{$var|filter} |
друкує з фільтрами |
{l} або {r} |
друкує символ { or } |
{if} … {elseif} … {else} … {/if} |
умова if |
{ifset} … {elseifset} … {/ifset} |
умова ifset |
{ifchanged} … {/ifchanged} |
перевірка наявності змін |
{switch} {case} {default} {/switch} |
умова switch |
n:else |
альтернативний контент для умов |
{foreach} … {/foreach} |
foreach |
{for} … {/for} |
for |
{while} … {/while} |
while |
{continueIf $cond} |
перейти до наступної ітерації |
{skipIf $cond} |
пропустити поточну ітерацію циклу |
{breakIf $cond} |
перервати цикл |
{exitIf $cond} |
ранній вихід |
{first} … {/first} |
це перша ітерація? |
{last} … {/last} |
Це остання ітерація? |
{sep} … {/sep} |
чи буде наступна ітерація? |
{iterateWhile} … {/iterateWhile} |
структурований foreach |
$iterator |
спеціальна змінна всередині циклу foreach |
{include 'file.latte'} |
включає шаблон з іншого файлу |
{sandbox 'file.latte'} |
вмикає шаблон у режимі пісочниці |
{block} |
анонімний блок |
{block blockname} |
визначення блоку |
{define blockname} |
визначення блоку для майбутнього використання |
{include blockname} |
друкує блок |
{include blockname from 'file.latte'} |
друкує блок із файлу |
{import 'file.latte'} |
завантажує блоки з іншого шаблону |
{layout 'file.latte'} / {extends} |
вказівка файлу макета |
{embed} … {/embed} |
завантажує шаблон або блок і дозволяє перезаписувати блоки |
{ifset blockname} … {/ifset} |
умова, якщо блок визначено |
{try} … {else} … {/try} |
перехоплення виключень |
{rollback} |
відкидає блок try |
{var $foo = value} |
створення змінних |
{default $foo = value} |
значення за замовчуванням, коли змінна не оголошена |
{parameters} |
Оголошення змінних, типи значень за замовчуванням |
{capture} … {/capture} |
Захоплює секцію для змінної |
{varType} |
оголошує тип змін ної |
{varPrint} |
пропонує типи змін них |
{templateType} |
оголошує типи змінних за допомогою класу |
{templatePrint} |
генерує клас із властивостями |
{_string} |
друкує переклад |
{translate} … {/translate} |
перекладає вміст |
{contentType} |
перемикає режим екранування і відправляє HTTP-заголовок |
{debugbreak} |
встановлює точку зупинки в коді |
{do} |
оцінює вираз, не виводячи його на друк |
{dump} |
скидає змінні в Tracy Bar |
{php} |
виконує будь-який PHP-код |
{spaceless} … {/spaceless} |
видаляє непотрібні пробільні символи |
{syntax} |
перемикає синтаксис під час виконання програми |
{trace} |
показує трасування стека |
n:class |
розумний атрибут класу |
n:attr |
інтелектуальні атрибути HTML |
n:tag |
динамічне ім'я елемента HTML |
n:ifcontent |
Опустити порожній HTML-тег |
n:href |
посилання в
HTML-елементах <m id=413> <a> |
</m> {link} |
друкує посилання |
{plink} |
друкує посилання на ведучого |
{control} |
друкує компонент |
{snippet} … {/snippet} |
фрагмент шаблону, який може бути відправлений за допомогою AJAX |
{snippetArea} |
конверт сніпетів |
{cache} … {/cache} |
кешує розділ шаблону |
{form} … {/form} |
друкує елемент форми |
{label} … {/label} |
друкує мітку введення форми |
{input} |
друкує елемент введення форми |
{inputError} |
друкує повідомлення про помилку для елемента введення форми |
n:name |
активує елемент введення HTML |
{formContainer} … {/formContainer} |
рендеринг контейнера форми |
Друк
{$var}
{...}
{=...}
Latte використовує тег {=...}
для друку будь-якого виразу на виході.
Якщо вираз починається зі змінної або виклику функції, то немає
необхідності писати знак рівності. Що на практиці означає, що його
майже ніколи не потрібно писати:
Ви можете записати у вигляді виразу все, що знаєте з PHP. Вам просто не потрібно вчити нову мову. Наприклад:
Будь ласка, не шукайте жодного сенсу в попередньому прикладі, але якщо ви його там знайдете, напишіть нам :-)
Ескейпінг-виведення
Яке найважливіше завдання системи шаблонів? Уникати дірок у безпеці. І саме це робить Latte, коли ви друкуєте щось на виведення. Він автоматично екранує все:
Якщо бути точним, Latte використовує контекстно-залежне екранування, яке є настільки важливою та унікальною функцією, що ми присвятили їй окрему главу безпека в першу чергу.
А якщо ви друкуєте HTML-кодований вміст із надійного джерела? Тоді ви можете легко вимкнути екранування:
Неправильне використання фільтра noescape
може
призвести до XSS-вразливості! Ніколи не використовуйте його, якщо ви не
абсолютно впевнені у тому, що ви робите, і що рядок, який ви
друкуєте, отримано з надійного джерела.
Друк у JavaScript
Завдяки контекстно-залежному екрануванню, дуже легко друкувати змінні в JavaScript, і Latte буде правильно їх екранувати.
Змінна не обов'язково повинна бути рядком, підтримується будь-який тип даних, які потім кодуються як JSON:
Генерує:
Це також причина, чому не укладайте змінну в лапки: Latte додає їх навколо рядків. А якщо ви хочете помістити строкову змінну в інший рядок, просто конкатеніруйте їх:
Фільтри
Друкований вираз може бути змінено за допомогою фільтрів. Наприклад, у цьому прикладі рядок перетворюється у верхній регістр і скорочується максимум до 30 символів:
Ви також можете застосовувати фільтри до частин виразу таким чином:
Умови
{if}
{elseif}
{else}
Умови поводяться так само, як і їхні аналоги в PHP. Ви можете використовувати ті самі вирази, які ви знаєте з PHP, вам не потрібно вивчати нову мову.
Як і будь-який парний тег, пара {if} ... {/ if}
може бути записана як n:attribute, наприклад:
Чи знаєте ви, що до n:attributes можна додати префікс tag-
? Тоді умова
зачіпатиме тільки HTML-теги, а вміст між ними завжди виводитиметься:
Чудово.
n:else
Якщо ви запишете умову {if} ... {/if}
у вигляді n:атрибута, у вас буде можливість вказати
альтернативну гілку за допомогою n:else
:
Атрибут n:else
також можна використовувати у поєднанні з n:ifset
, n:foreach
, n:try
, n:ifcontent
та n:ifchanged
.
{/if $cond}
Вас може здивувати, що вираз в умові {if}
також може бути вказано
в тезі end. Це корисно в ситуаціях, коли ми ще не знаємо значення умови на
момент відкриття тега. Назвемо це відкладеним рішенням.
Наприклад, ми починаємо виводити таблицю із записами з бази даних, і
тільки після завершення звіту розуміємо, що в базі даних не було
жодного запису. Тому ми поміщаємо умову в кінцевий тег {/if}
, і
якщо запису немає, то нічого з цього не буде надруковано:
Зручно, чи не так?
Ви також можете використовувати {else}
у відкладеній умові, але
не {elseif}
.
{ifset}
{elseifset}
Див. також {ifset block}
Використовуйте умову {ifset $var}
, щоб визначити, чи існує змінна
(або кілька змінних) і чи має вона ненульове значення. Насправді це те
саме, що й if (isset($var))
у PHP. Як і будь-який парний тег, цей може бути
записаний у вигляді n:attribute, тому покажемо його
на прикладі:
{ifchanged}
{ifchanged}
перевіряє, чи змінилося значення змінної з моменту
останньої ітерації в циклі (foreach, for або while).
Якщо ми вкажемо в тезі одну або кілька змінних, він перевірить, чи змінилося значення будь-якої з них, і надрукує вміст відповідним чином. Наприклад, у наступному прикладі під час перерахування імен як заголовок друкується перша буква імені щоразу, коли вона змінюється:
Однак, якщо аргумент не вказано, то буде перевірено сам вміст рендерингу відповідно до його попереднього стану. Це означає, що в попередньому прикладі ми можемо сміливо опустити аргумент у тезі. І, звичайно, ми також можемо використовувати n:attribute:
Ви також можете включити клаузулу {else}
всередину
{ifchanged}
.
{switch}
{case}
{default}
Порівнює значення з кількома варіантами. Це схоже на структуру
switch
, відому вам із PHP. Однак Latte покращує її:
- використовує суворе порівняння (
===
) - не вимагає
break
Таким чином, це точний еквівалент структури match
, з якою
поставляється PHP 8.0.
Пункт {case}
може містити кілька значень, розділених комами:
Цикли
У Latte доступні всі цикли, знайомі вам із PHP: foreach, for і while.
{foreach}
Ви пишете цикл точно так само, як і в PHP:
Крім того, у нього є кілька зручних твіків, про які ми зараз поговоримо.
Наприклад, Latte перевіряє, щоб створені змінні випадково не
перезаписали однойменні глобальні змінні. Це врятує вас, коли ви
припускаєте, що $lang
– поточна мова сторінки, і не розумієте, що
foreach $langs as $lang
перезаписав цю змінну.
Цикл foreach також може бути написаний дуже елегантно й економічно за допомогою n:attribute:
Чи знаєте ви, що до n:attributes можна додавати префікс inner-
? Тоді в
циклі повторюватиметься тільки внутрішня частина елемента:
Таким чином, буде виведено щось на кшталт:
{else}
Цикл foreach
може приймати необов'язкове речення {else}
,
текст якого виводиться, якщо заданий масив порожній:
$iterator
Усередині циклу foreach
ініціалізується змінна $iterator
. У
ній зберігається важлива інформація про поточний цикл.
$iterator->first
– це перша ітерація?$iterator->last
– це остання ітерація?$iterator->counter
– лічильник ітерацій, починається з 1$iterator->counter0
– лічильник ітерацій, починається з 0$iterator->odd
– ця ітерація непарна?$iterator->even
– ця ітерація парна?$iterator->parent
– ітератор, що оточує поточний ітератор.$iterator->nextValue
– наступний елемент у циклі$iterator->nextKey
– ключ наступного елемента в циклі
Лата розумниця і $iterator->last
працює не тільки для масивів, а й
коли цикл працює над загальним ітератором, де кількість елементів
заздалегідь не відома.
{first}
{last}
{sep}
Ці теги можна використовувати всередині циклу {foreach}
. Вміст
{first}
відображається під час першого проходу. Вміст {last}
відображається … можете здогадатися? Так, для останнього проходу.
Насправді це ярлики для {if $iterator->first}
і {if $iterator->last}
.
Теги також можуть бути записані як n:attributes:
Вміст {sep}
виводиться, якщо ітерація не остання, тому він
підходить для друку роздільників, наприклад, ком між елементами
списку:
Це досить практично, чи не так?
{iterateWhile}
Спрощує групування лінійних даних під час ітерації в циклі foreach, повторюючи її у вкладеному циклі, доки не буде виконано певну умову. Прочитайте детальну інструкцію.
Він також може елегантно замінити {first}
і {last}
у
прикладі вище:
Дивіться також пакетні та групові фільтри.
{for}
Ми пишемо цикл точно так само, як і в PHP:
Тег також може бути записаний як n:attribute:
{while}
Знову ж таки, ми пишемо цикл точно так само, як і в PHP:
Або як n:attribute:
Варіант з умовою наприкінці тега відповідає циклу do-while у PHP:
{continueIf}
{skipIf}
{breakIf}
Існують спеціальні теги, які можна використовувати для управління
будь-яким циклом – {continueIf ?}
і {breakIf ?}
, які переходять до
наступної ітерації та завершують цикл, відповідно, при
виконанні умов:
Тег {skipIf}
дуже схожий на {continueIf}
, але не збільшує
лічильник. Таким чином, під час друку $iterator->counter
і пропуску
деяких елементів у нумерації не буде дірок. Також речення {else} буде
виведено при пропуску всіх елементів.
{exitIf}
Завершує відмальовування шаблону або блоку при виконанні умови.
Увімкнення шаблонів
{include 'file.latte'}
Див. також {include block}
Тег {include}
завантажує і відображає вказаний шаблон. На нашій
улюбленій мові PHP це виглядає так:
Увімкнені шаблони не мають доступу до змінних активного контексту, але мають доступ до глобальних змінних.
Ви можете передати змінні до вставленого шаблону наступним чином:
Ім'я шаблону може бути будь-яким виразом PHP:
Вставлений вміст може бути змінено за допомогою фільтрів. У наступному прикладі видаляється весь HTML і коригується регістр:
Успадкування шаблону не бере участі у цьому
за замовчуванням. Хоча ви можете додавати теги блоків до включених
шаблонів, вони не замінять відповідні блоки в шаблоні, до якого вони
включені. Думайте про включення як про незалежні та екрановані частини
сторінок або модулів. Таку поведінку можна змінити за допомогою
модифікатора with blocks
:
Зв'язок між ім'ям файлу, зазначеним у тезі, і файлом на диску залежить від завантажувача.
{sandbox}
Під час увімкнення шаблону, створеного кінцевим користувачем, слід розглянути можливість його „пісочниці“ (докладніша інформація в документації щодо „пісочниці“):
{block}
Див. також {block name}
Блоки без назви слугують для можливості застосування фільтрів до частини шаблону. Наприклад, можна застосувати фільтр смуги, щоб видалити непотрібні пробіли:
Обробка винятків
{try}
За допомогою цих тегів дуже легко створювати надійні шаблони.
Якщо під час рендерингу блоку {try}
виникає виняток, увесь блок
відкидається, і рендеринг буде продовжено після нього:
Вміст необов'язкового пункту {else}
виводиться тільки в разі
виникнення винятку:
Тег також може бути записаний як n:attribute:
Також можна визначити власний обробник винятків для ведення журналу:
{rollback}
Блок {try}
також можна зупинити і пропустити вручну за допомогою
{rollback}
. Таким чином, вам не потрібно перевіряти всі вхідні дані
заздалегідь, і тільки під час візуалізації ви можете вирішити, чи є
сенс рендерити об'єкт.
Змінні
{var}
{default}
Ми створимо нові змінні в шаблоні за допомогою тега {var}
:
Тег {default}
працює аналогічно, за винятком того, що він створює
змінні, тільки якщо вони не існують. Якщо змінна вже існує і містить
null
, вона не буде перезаписана:
Ви також можете вказати типи змінних. Наразі вони є інформативними і Latte не перевіряє їх.
{parameters}
Подібно до того, як функція оголошує свої параметри, шаблон може оголосити свої змінні на самому початку:
Змінні $a
і $b
без значення за замовчуванням автоматично
мають значення за замовчуванням null
. Оголошені типи залишаються
інформативними, і Latte не перевіряє їх.
В іншому оголошені змінні не передаються в шаблон. Це відмінність від
тега {default}
.
{capture}
Використовуючи тег {capture}
, ви можете захопити виведення у
змінну:
Тег також можна записати як n:атрибут, як і будь-який інший парний тег:
Вихідні дані HTML зберігаються у змінній $var
як об'єкт
Latte\Runtime\Html
, щоб уникнути
небажаного екранування під час друку.
Інші
{contentType}
Використовуйте тег, щоб вказати, який тип вмісту представляє шаблон. Можливі такі варіанти:
html
(тип за замовчуванням)xml
javascript
css
calendar
(iCal)text
Його використання важливе, оскільки він встановлює контекстно-залежне екранування, і тільки
після цього Latte може правильно екранувати. Наприклад, {contentType xml}
перемикається в режим XML, {contentType text}
повністю вимикає
екранування.
Якщо параметр є повнофункціональним MIME-типом, наприклад,
application/xml
, він також надсилає браузеру HTTP-заголовок
Content-Type
:
{debugbreak}
Вказує місце, де виконання коду перерветься. Використовується з метою налагодження, щоб програміст міг перевірити середовище виконання і переконатися, що код виконується так, як очікувалося. Підтримується Xdebug. Крім того, можна вказати умову, за якої код має перерватися.
{do}
Виконує PHP-код і нічого не виводить. Як і всі інші теги, код PHP є одним виразом, див. Обмеження PHP.
{dump}
Вивантажує змінну або поточний контекст.
Потрібен пакет Tracy.
{php}
Дозволяє виконати будь-який PHP-код. Тег повинен бути активований за допомогою розширення RawPhpExtension.
{spaceless}
Видаляє непотрібні пробільні символи. Аналогічний фільтру без пробілів.
Вихідні дані:
Тег також може бути записаний як n:attribute:
{syntax}
Теги Latte не обов'язково повинні бути укладені тільки в одинарні
фігурні дужки. Ви можете вибрати інший роздільник, навіть під час
виконання. Це робиться за допомогою {syntax…}
, де параметр
може бути:
- double:
{{...}}
- off: повністю відключає теги Latte
Використовуючи нотацію n:attribute, ми можемо вимкнути Latte тільки для блоку JavaScript:
Latte можна дуже зручно використовувати всередині JavaScript, тільки
уникайте конструкцій, як у цьому прикладі, де буква одразу йде за
{
, див. Latte всередині JavaScript або
CSS.
Якщо ви вимкнете Latte за допомогою {syntax off}
(тобто тега, а не
атрибута n:attribute), то він буде строго ігнорувати всі теги до
{/syntax}
.
{trace}
Викидає виняток Latte\RuntimeException
, стекове трасування якого
виконано в дусі шаблонів. Таким чином, замість виклику функцій і
методів, воно включає виклик блоків і вставку шаблонів. Якщо ви
використовуєте інструмент для наочного відображення кинутих
винятків, такий як Tracy, ви чітко бачитимете стек
виклику, включно з усіма переданими аргументами.
Помічники тегів HTML
n:клас
Завдяки n:class
дуже легко згенерувати HTML-атрибут class
саме
так, як вам потрібно.
Приклад: Мені потрібно, щоб активний елемент мав клас active
:
І ще мені потрібно, щоб перший елемент мав класи first
і
main
:
А всі елементи повинні мати клас list-item
:
Дивно просто, чи не так?
n:attr
Атрибут n:attr
може генерувати довільні HTML-атрибути з тією ж
елегантністю, що й n:class.
Залежно від значень, що повертаються, він відображає, наприклад:
n:tag
Атрибут n:tag
може динамічно змінювати ім'я елемента HTML.
Якщо $heading === null
, то <h1>
тег виводиться без змін. В
іншому випадку ім'я елемента змінюється на значення змінної, так що для
$heading === 'h3'
записується:
Оскільки Latte – це безпечна система шаблонів, вона перевіряє, що нове ім'я тегу є дійсним і не містить небажаних або шкідливих значень.
n:ifcontent
Запобігає друку порожнього HTML-елемента, тобто елемента, що не містить нічого, крім пробілів.
Залежно від значень змінної $error
буде виводитися:
Переклад
Щоб теги перекладу працювали, необхідно налаштувати перекладач. Ви також можете
використовувати translate
фільтр для
перекладу.
{_...}
Перекладає значення іншими мовами.
Перекладачеві можуть бути передані й інші параметри:
{translate}
Překládá části šablony:
Тег також може бути записаний як n:attribute, щоб перекласти внутрішню частину елемента: