Довідник Velocity
Довідник синтаксису Velocity в eSputnik.
Практичні приклади — у статтях Velocity у повідомленнях і Velocity у сценаріях.
Формати змінних
| Формат | Опис |
|---|---|
$discount | Якщо змінна не існує — виводиться буквальний текст $discount |
$!discount | Якщо значення відсутнє — нічого не виводиться |
${discount} | Фігурні дужки однозначно відокремлюють ім'я змінної від сусіднього тексту |
$!{discount} | Коректно відокремлює змінну та приглушує відсутні значення |
${discount|$otherGift} | Якщо значення змінної відсутнє, підставляє запасне значення |
Вкладені об'єкти
Для доступу до полів всередині об'єкта використовуйте крапкову нотацію:
$item.name$lastProductAdded.externalItemId$manager.phone
Масиви та індекси
Доступ до елемента за індексом (нумерація з 0):
$!arrayName[0]$!items[0].parameterName
Якщо вказаного індексу не існує — під час відправлення станеться помилка. Використовуйте цикл, якщо розмір масиву заздалегідь невідомий.
Отримати розмір масиву:
$!arrayName.size()
Перевірити, чи є значення в масиві:
$!arrayName.contains("value")— повертаєtrue, якщо значення є в масиві, іfalse, якщо немає;$!arrayName.indexOf("value")— повертає індекс значення або-1, якщо його немає.
Наприклад, щоб показати блок лише контактам, у масиві cohorts яких є значення premium:
<!--#if($cohorts.contains("premium"))-->
...
<!--#end-->
Примітка: Точний шлях доступу залежить від структури події. Деякі події містять простий масив, інші — об'єкт із полем
arrayвсередині.
Цикли
Ітерація по всіх елементах масиву через #foreach:
#foreach($item in $!arrayName)
$foreach.count: $!item.name
#end$foreach.count — лічильник циклу, починається з 1.
Зупинити цикл достроково через #break:
#foreach($item in $!arrayName)
$!item.name
#if($foreach.count > 5) #break #end
#endВ HTML-коді email директиви загортаються в коментарі: <!--#foreach(...)-->, <!--#end-->
Надання значення
Присвоїти значення змінній для повторного використання в шаблоні:
#set($var = 'value')
#set($total = $mathTool.add($price, $tax))Словники
Щоб підставляти значення залежно від ключа — наприклад, домен посилання залежно від когорти, — задайте словник замість ланцюжка #if/#elseif і отримуйте з нього значення методом get():
#set($baseUrl = {
"dev": "https://dev.example.com/",
"stage": "https://stage.example.com/",
"default": "https://example.com/"
})
#if($baseUrl.get($!cohort))
#set($url = $baseUrl.get($!cohort))
#else
#set($url = $baseUrl.get('default'))
#endЯкщо ключа в словнику немає, спрацьовує гілка #else зі значенням за замовчуванням. Щоб додати новий варіант, достатньо додати пару в словник — умови змінювати не потрібно.
В HTML-коді email директиви загортаються в коментарі: <!--#set(...)-->.
Умови
Базова умова:
#if($!param == 'value')
контент
#endЗ альтернативою:
#if($!param == 'value')
контент
#else
альтКонтент
#endКілька умов:
#if($!param == 'value1')
контент1
#elseif($!param == 'value2')
контент2
#else
альтКонтент
#endПеревірка на непорожнє значення:
#if($!param && $!param != '')
контент
#endОператори
Порівняння
| Оператор | Значення |
|---|---|
== | Дорівнює |
!= | Не дорівнює |
gt | Більше |
lt | Менше |
ge | Більше або дорівнює |
le | Менше або дорівнює |
Логічні
| Оператор | Значення |
|---|---|
&& або and | Логічне І |
|| або or | Логічне АБО |
! або not | Логічне НЕ |
Порівняння рядків
$!firstString.equals($!secondString)$!firstString.equalsIgnoreCase($!secondString)
Екранування та URL-кодування
Використовуйте $esc, щоб вивести символи, які Velocity інакше сприйняв би як синтаксис.
| Вираз | Результат | Для чого |
|---|---|---|
${esc.d} | Літеральний $ | Ціна поряд із динамічним значенням, напр. ${esc.d}59.99 → $59.99 |
$esc.url($!value) | URL-закодований рядок | Значення з пробілами чи спецсимволами в query-параметрі |
Закодуйте значення перед вставкою в посилання:
#set($program = $esc.url($!data.get('programName')))
Потім посилайтеся на $program в URL. Контекст полів посилань описано у статті Динамічні посилання в email.
Параметр події можна підставити і просто в query-рядок URL:
https://example.com/checkout?token=$esc.url($!data.get('custom_token'))
Так зручно передавати в посилання динамічні токени чи ідентифікатори з події.
Арифметика
$mathTool.add($v1, $v2)$mathTool.sub($v1, $v2)$mathTool.mul($v1, $v2)$mathTool.div($v1, $v2)
Форматування чисел
Ціле число без округлення:
$numberTool.integer($v1)
$numberTool.integer() форматує число за локаллю й додає розділювачі тисяч — наприклад, 1,772,023,737. Для значення, яке йде в посилання чи параметр, наприклад, позначки часу для зовнішнього таймера, використовуйте $mathTool.toInteger(): він повертає ціле число без розділювачів.
Грошова сума з двома десятковими знаками:
$!numberTool.format('#.00', $v1)
Дати
Виведення
Поточна дата:
$!dateTool.currentDate()$!dateTool.currentDate('dd.MM.yyyy HH:mm:ss', 'GMT+3')
Поточний Unix timestamp:
$!dateTool.currentTimeStamp()
Форматування дати з події або поля контакту:
$!dateTool.formatDate('dd.MM.yyyy', $!date)$!dateTool.formatDate('yyyy-MM-dd HH:mm:ss', $!date)
formatDate приймає й позначку часу Unix у мілісекундах — наприклад, 1495479520000, — і перетворює її на читабельну дату. $!dateTool.currentTimeStamp() так само повертає поточну дату в мілісекундах.
Форматування в часовому поясі контакту:
$!dateTool.formatInContactTimezone('dd/MM/yyyy HH:mm:ss', $!dateTime)
Вхідна дата має бути в одному з таких форматів: dd/MM/yyyy HH:mm:ss, yyyy-MM-dd'T'HH:mm:ss або yyyy-MM-dd'T'HH:mm:ss'Z'. Результат виводиться в часовому поясі контакта, а якщо в контакта його не вказано — у часовому поясі організації.
Арифметика
За умови "date": "01/01/2020 12:00":
$!dateTool.addYears($!date, 2)→ 01/01/2022 12:00$!dateTool.addMonths($!date, 5)→ 01/06/2020 12:00$!dateTool.addDays($!date, 15)→ 16/01/2020 12:00$!dateTool.addHours($!date, 7)→ 01/01/2020 19:00$!dateTool.addMinutes($!date, 15)→ 01/01/2020 12:15
Від'ємне значення — віднімання:
$!dateTool.addDays($!date, -7)
Без аргументу з форматом операції з датами розбирають такі формати: dd/MM/yyyy HH:mm, dd/MM/yyyy, yyyy-MM-dd'T'HH:mm і yyyy-MM-dd. Дату в будь-якому іншому форматі передають разом із її власним форматом в аргументі.
Щоб отримати дату через кілька днів від поточної, передайте в currentDate формат dd/MM/yyyy HH:mm. Дату, яку $!dateTool.currentDate() повертає без параметрів, addDays не розбирає, і результат буде порожнім:
$!dateTool.addDays($!dateTool.currentDate('dd/MM/yyyy HH:mm'), 28)→ 04/12/2026 10:30:00, якщо поточна дата — 06/11/2026 10:30
З користувацьким форматом вхідної дати — за умови "customDate": "12:00 2020-30-04":
$!dateTool.addYears($!customDate, 2, 'HH:mm yyyy-dd-MM')→ 12:00 2022-30-04
З користувацьким форматом вхідної та вихідної дати — за умови "dateTime": "2020-05-01T00:00":
$!dateTool.addDays($!dateTime, 2, "yyyy-MM-dd'T'HH:mm", 'dd-MM-yyyy')→ 03-05-2020$!dateTool.addHours($!dateTime, 7, "yyyy-MM-dd'T'HH:mm", 'dd/MM HH:mm')→ 01/05 07:00$!dateTool.addMinutes($!dateTime, 2, "yyyy-MM-dd'T'HH:mm", 'HH:mm')→ 00:02
Різниця між двома датами
За умови "firstDate": "01/01/2019", "secondDate": "05/05/2020":
$!dateTool.diff($!firstDate, $!secondDate, 'YEARS')→ 1$!dateTool.diff($!firstDate, $!secondDate, 'MONTHS')→ 16$!dateTool.diff($!firstDate, $!secondDate, 'DAYS')→ 490$!dateTool.diff($!firstDate, $!secondDate, 'HOURS')→ 11760$!dateTool.diff($!firstDate, $!secondDate, 'MINUTES')→ 705600
З користувацьким форматом — за умови "customDate1": "17:15 05/05/2020", "customDate2": "10:05 01/01/2019":
$!dateTool.diff($!customDate1, $!customDate2, 'HH:mm dd/MM/yyyy', 'MINUTES')→ 706030
Рядки
Обидві дати мають бути в одному форматі. Якщо він не входить у перелік типових, його передають четвертим аргументом.
Довжина рядка:
$!var.length()
Частина рядка:
$!var.substring(startIndex, endIndex)
Заміна частини рядка:
$!var.replace('oldValue', 'newValue')
Зміна регістру:
#set($example = 'Ukraine')
$example.toUpperCase() → UKRAINE
$example.toLowerCase() → ukraineОбрізання довгого значення:
#set($name0 = $!items[0].name)
#if($name0.length() gt 40)
#set($name0 = $name0.substring(0, 37) + '...')
#endЗначення надають змінній до умови, а в повідомленні виводять саму змінну, а не початковий вираз. Якщо в одному повідомленні обрізають кілька значень, наприклад, назви товарів у сітці, кожному значенню дають власну назву змінної — $name0, $name1 і так далі.
Дані зовнішніх джерел
Дані зовнішніх джерел доступні у Velocity, якщо відповідне джерело підключено і його значення доступні в поточному контексті.
Синтаксис — той самий, що використовується для інших даних в eSputnik.
Точний шлях до змінної залежить від структури даних, що повертаються джерелом, і назв полів у конфігурації джерела. Використовуйте назви полів і структуру даних, доступні в налаштуваннях джерела або тестовому запиті.
Дані вебхука
Звертайтеся до полів за назвами, що повертаються у відповіді вебхука, відповідно до її структури. Як і для інших джерел даних, доступність залежить від поточного контексту.
Updated 7 days ago