Використання можливостей Velocity в eSputnik

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

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

Всі зовнішні дані, які надходять до повідомлення з джерела даних, потрапляють до об'єкту data, тому для виведення потрібного параметру прописуємо таким чином:

$!data.get('ім'я параметру')

📘

Зверніть увагу

Команда витягти дані data.get необхідна лише при зверненні до рекомендаційних або зовнішніх джерел даних. В усіх інших випадках ви також можете використовувати формат, описаний в документації Velocity версії 2.4.1.

Наприклад:

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

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

$!data.get('ім'я масиву')

або

$!ім'я масиву[0]

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

$!data.get('ім’я масиву').get(0).get('ім'я параметру')

або

$!items[0].ім'я параметру

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

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

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

$!data.get('ім'я масиву').size()

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

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

Синтаксис:

#foreach($item in $data.get('назва масиву'))
$foreach.count: $item.get('name') ...
#end

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

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

#foreach($item in $data.get('назва масиву'))

$foreach.count: $item.get('name') ...

#if( $foreach.count > 5 ) #break #end

#end

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

Надання

Синтаксис:

#set($var='значення')

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

Порівняння

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

Синтаксис:

$!param1 gt $!param2

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

Синтаксис:

$!firstString.equals($!secondString)

$!firstString.equalsIgnoreCase($!secondString)

Умова

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

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

Синтаксис:

#if ($data.get('params')=='значення')

(контент)

#end

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

#if($data.get('param')=='значення')

(контент)

#else

(альтернативний контент)

#end

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

#if($data.get('param')=='значення1')

(контент 1)

#elseif($data.get('param')=='значення2')

(контент 2)

#else

(альтернативний контент)

#end

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

#if ($data.get('param1')=='значення1' and $data.get('param2')=='значення2')

(контент)

#end

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

#if (!($data.get('param')=='значення'))

(контент)

#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',$!data.get('date'))

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

$!dateTool.formatDate('yyyy-MM-dd HH:mm:ss',$!data.get('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($!data.get('date'),2) -> 01/01/2022 12:00

$!dateTool.addMonths($!data.get('date'),5) -> 01/06/2020 12:00

$!dateTool.addDays($!data.get('date'),15) -> 16/01/2020 12:00

$!dateTool.addHours($!data.get('date'),7) -> 01/01/2020 19:00

$!dateTool.addMinutes($!data.get('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($!data.get('customDate'),2,'HH:mm yyyy-dd-MM') -> 12:00 2022-30-04

Подібним чином за рахунок вказування четвертого аргументу можна форматувати дату, наприклад якщо дата у форматі: "dateTime": "2020-05-01T00: 00":

$!dateTool.addDays($!data.get('dateTime'), 2, "yyyy-MM-dd'T'HH:mm",'dd-MM-yyyy') -> 03-05-2020

$!dateTool.addHours($!data.get('dateTime'), 7, "yyyy-MM-dd'T'HH:mm",'dd/MM HH:mm') -> 01/05 07:00

$!dateTool.addMinutes($!data.get('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($data.get('param') and $data.get('param')!='')

(контент)

#end

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

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

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

$!var.length()

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

$!var.substring(індекс початку,індекс кінця)

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

$!var.replace('що треба замінити','чим треба замінити')

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

#set ($example = "UkRaInE")  

$example.toUpperCase()  // UKRAINE
$example.toLowerCase()  // ukraine