Довідник Velocity

Довідник синтаксису Velocity в eSputnik.

Практичні приклади — у статтях Velocity у повідомленнях і Velocity у сценаріях.

Формати змінних

Вкладені об'єкти

Для доступу до полів всередині об'єкта використовуйте крапкову нотацію:

• $item.name
• $lastProductAdded.externalItemId
• $manager.phone

Масиви та індекси

Доступ до елемента за індексом (нумерація з 0):

• $!arrayName[0]
• $!items[0].parameterName

Якщо вказаного індексу не існує — під час відправлення станеться помилка. Використовуйте цикл, якщо розмір масиву заздалегідь невідомий.

Отримати розмір масиву:

• $!arrayName.size()

Примітка: Точний шлях доступу залежить від структури події. Деякі події містять простий масив, інші — об'єкт із полем 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($!param == 'value')
  контент
#end

З альтернативою:

#if($!param == 'value')
  контент
#else
  альтКонтент
#end

Кілька умов:

#if($!param == 'value1')
  контент1
#elseif($!param == 'value2')
  контент2
#else
  альтКонтент
#end

Перевірка на непорожнє значення:

#if($!param && $!param != '')
  контент
#end

Оператори

Порівняння

Логічні

Порівняння рядків

• $!firstString.equals($!secondString)
• $!firstString.equalsIgnoreCase($!secondString)

Арифметика

• $mathTool.add($v1, $v2)
• $mathTool.sub($v1, $v2)
• $mathTool.mul($v1, $v2)
• $mathTool.div($v1, $v2)

Форматування чисел

Ціле число без округлення:

• $numberTool.integer($v1)

Грошова сума з двома десятковими знаками:

• $!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)

Форматування в часовому поясі контакту:

• $!dateTool.formatInContactTimezone('dd/MM/yyyy HH:mm:ss', $!dateTime)

Арифметика

За умови "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)

З користувацьким форматом вхідної дати — за умови "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

Дані зовнішніх джерел

Дані зовнішніх джерел доступні у Velocity, якщо відповідне джерело підключено і його значення доступні в поточному контексті.

Синтаксис — той самий, що використовується для інших даних в eSputnik.

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

Дані вебхука

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

У системі eSputnik можливість динамічного контенту реалізовано за допомогою бібліотеки Apache Velocity. На цій сторінці ми розглянемо основні можливості мови Velocity.

Виведення одного параметру

Формати звернення до одного параметру такі:

Виведення елементів з масиву за індексами

Якщо ми бажаємо вивести елемент масиву за індексом, то вказуємо назву масиву та індекс елементу:

$!arrayName[0]

— якщо в масиві вказані тільки значення, де 0 — індекс елемента.

$!items[0].parameterName

— якщо масив містить об'єкти з параметрами.

Такий спосіб є прийнятним, якщо розмір масиву заздалегідь відомий. Якщо вказати індекс елементу, якого немає в масиві, то при відправленні повідомлення станеться помилка.

Отримати розмір масиву

$!arrayName.size()

Цикл для виведення всіх елементів з масиву

Для виведення всіх елементів масиву використовується цикл #foreach.

Синтаксис:

#foreach($item in $!arrayName)
$foreach.count: $!item.name …
#end

Де $item — змінна, якій буде надано поточний елемент масиву і до якої можна звертатися всередині циклу. У цьому випадку буде виведено весь список елементів у масиві по черзі, $foreach.count — за замовчуванням є ім'ям лічильника циклу і його початкове значення починається з 1.

Якщо ви бажаєте зупинити цикл #foreach, ви можете використовувати директиву #break, щоб зупинити цикл за потрібною умовою:

#foreach($item in $!arrayName)
$foreach.count: $!item.name …
#if($foreach.count > 5) #break #end
#end

Із більш детальними прикладами використання ви можете ознайомитися на прикладі передачі замовлень або покинутих кошиків.

Надання

Синтаксис:

#set($var='value')

У ролі значення можуть використовуватися конкретні значення, інша змінна або вираз.

Порівняння

Оператори порівняння та логічні оператори:

Синтаксис:

$!param1 gt $!param2

Також доступні оператори для порівняння рядків з урахуванням і без урахування регістру.

Синтаксис:

$!firstString.equals($!secondString)
$!firstString.equalsIgnoreCase($!secondString)

Умова

Умови нам можуть знадобитися з кількох причин:

• якщо треба виводити тільки певну інформацію (наприклад, тільки одну категорію товарів);
• якщо треба виводити певну кількість товарів в одному блоці, щоб не зламати верстку та ін.

Синтаксис:

#if($!params == 'value')
(content)
#end

Якщо умову не виконано, то можна вивести альтернативний варіант:

#if($!param == 'value')
(content)
#else
(altContent)
#end

Також можна перевірити кілька умов:

#if($!param == 'value1')
(content1)
#elseif($!param == 'value2')
(content2)
#else
(altContent)
#end

Можна об'єднати кілька умов за допомогою логічних операторів and та or:

#if($!param1 == 'value1' && $!param2 == 'value2')
(content)
#end

Можна інвертувати умову:

#if($!param != 'value')
(content)
#end

Арифметичні операції

Додавання: $mathTool.add($v1, $v2)

Віднімання: $mathTool.sub($v1, $v2)

Множення: $mathTool.mul($v1, $v2)

Ділення: $mathTool.div($v1, $v2)

Форматування чисел

$numberTool.integer($v1) — виведе ціле число без округлення.

Для виведення грошових сум із двома десятковими знаками можна використовувати таку функцію:

$!numberTool.format('#.00',$v1)

Виведення дати в повідомлення

Вивести поточну дату можна за допомогою функції:

$!dateTool.currentDate()

Вивести Unix TimeStamp (поточна дата в мілісекундах):

$!dateTool.currentTimeStamp()

Можна задати формат відображення дати та/або часу, другим аргументом можна задати часовий пояс за Гринвічем (GMT):

$!dateTool.currentDate('dd.MM.yyyy HH:mm:ss', 'GMT+3')

Якщо дата передається в форматі Unix TimeStamp (наприклад, 1495479520000), то її можна перетворити на читабельний формат за допомогою функції:

$!dateTool.formatDate('dd.MM.yyyy', $!date)

або із зазначенням формату:

$!dateTool.formatDate('yyyy-MM-dd HH:mm:ss', $!date)

Щоб форматувати вхідну дату з часом в потрібний формат по часовому поясу контакту, використовуйте

$!dateTool.formatInContactTimezone(String format, String dateTime) 

Вхідний формат дати має відповідати ISO 8601:

• 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

Якщо другим аргументом буде від'ємне значення, то буде повернуто результат віднімання.

За замовчуванням очікується дата в одному з перерахованих форматів.

"dd/MM/yyyy HH:mm",
"dd/MM/yyyy",
"yyyy-MM-dd'T'HH:mm",
"yyyy-MM-dd".

Якщо формат відрізняється, то як третій аргумент можна задати свій формат, наприклад якщо ви передаєте дату в форматі "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

Перевірка на не порожнє значення

Якщо необхідно перевірити, чи був переданий параметр і чи не був він порожнім, то можна використовувати такий код:

#if($!param && $!param != '')
(content)
#end

Це може бути корисним, якщо повідомлення містить звертання до підписника, але не в усіх підписників вказані імена.

Робота з рядками

Дізнатися довжину рядка:

$!var.length()

Отримати частину рядка:

$!var.substring(startIndex,stopIndex)

Замінити частину рядка іншим значенням:

$!var.replace('whatNeedsToBeChanged','valueToSetInstead')

Змінити регістр рядка:

#set ($example = "UkRaInE")  
$example.toUpperCase()  // UKRAINE
$example.toLowerCase()  // ukraine