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

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

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

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

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

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

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

$!data.get('ім'я масиву').get(0) — якщо в масиві вказані тільки значення, де 0 — індекс елемента.

$!data.get('ім’я масиву').get(0).get('ім'я параметру') — якщо масив містить об'єкти з параметрами.

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

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

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

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

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

Синтаксис:

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

$velocityCount: $item.get('name') ...

#end

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

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

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

$velocityCount: $item.get('name') ...

#if( $velocityCount > 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

Це, в принципі, і вся стисла необхідна інформація, яка може стати в нагоді під час налаштування динамічного контенту в листі. Ознайомитися з більш детальною документацією щодо Apache Velocity можна за такими адресами:

http://velocity.apache.org/engine/1.7/user-guide.html

http://people.apache.org/~henning/velocity/html/index.html