Использование возможностей 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