Довідник 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.

Точний шлях до змінної залежить від структури даних, що повертаються джерелом, і назв полів у конфігурації джерела. Використовуйте назви полів і структуру даних, доступні в налаштуваннях джерела або тестовому запиті.

Дані вебхука

Звертайтеся до полів за назвами, що повертаються у відповіді вебхука, відповідно до її структури. Як і для інших джерел даних, доступність залежить від поточного контексту.




Did this page help you?