Використання можливостей 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