[ELMA3] Создание собственной функции для шаблонов оповещений

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

Пример отображения данных

Рис. 1. Значение функции Period в оповещении при создании задачи

Пример класса точки расширения

Примечание

Создание собственной функции для шаблонов оповещений происходит при помощи реализации точки расширения INotificationFunctions, у которой нет методов. Чтобы Ваша функция попала в список зарегистрированных функций – Вам необходимо создать public static метод, тип возвращаемого значения которого является FormatedValue, входящим параметром является только одна переменная типа FunctionEvaluationContext.

FormatedValue – это форматируемое значение Вашей функции.

FunctionEvaluationContext – это параметры для вычисления Вашей функции. Количество параметров может быть неограниченно. В функции параметры отделяются друг от друга точкой запятой, например, {Period({$New.StartDate};{$New.EndDate};SR(’Период’))} , где {$New.StartDate}, {$New.EndDate} и SR(’Период’) являются параметрами. Для того, чтобы получить значение нужного параметра, необходимо ссылаться на номер его позиции. Если обратиться к вышеописанному примеру, то параметр {$New.StartDate} имеет порядковый номер равный 0, {$New.EndDate} является номером 1 и так далее. Чтобы записать значение параметра необходимо привести его к правильному формату, в этом поможет функция context.GenerationContext.FormatProvider.FormatValue(context.Parameters[Номер_Позиции_Параметра]). Необходимость приведения к правильному формату обусловлена тем, что в значении переменной могут находится лишние символы, например, при передаче даты окончания пользовательской задачи без времени (дд.мм.гггг) без использования приведения к верному формату в оповещении будет дата начала равная дд.мм.гггг 23:59:50, а если использовать приведение, то дата запишется в верном формате.

Название функции будет совпадать с названием метода Вашего класса, реализующего функцию для шаблона оповещения. В данном примере использование функции в оповещении будет выглядеть следующим образом: {Period({$New.StartDate};{$New.EndDate};SR(’Период’))}, причем параметр под номером 3 является необязательным, так как название поля будет сгенерировано по умолчанию Срок выполнения.

[Component]
public class MyNotificationFunction : INotificationFunctions
{
    /// <summary>
    /// Генерирует строку, состоящую из имени свойства и значений двух дат.
    /// Параметр 1 - Значение 1 (Дата начала).
    /// Параметр 2 - Значение 2 (Дата окончания).
    /// Параметр 3 - Заголовок (необязательный), по умолчанию генерируется название "Срок выполнения".
    /// </summary>
    public static FormatedValue Period(FunctionEvaluationContext context)
    {
        string captionFinish = SR.T("Срок выполнения");
 
        if (context.Parameters.Count < 2) return new FormatedValue(string.Empty);
 
        //Значение первого параметра (Дата начала)
        var startDateValue = context.Parameters[0];
        //Отформатированное строковое значение Даты начала
        var startDateFormatedValue = context.GenerationContext.FormatProvider.FormatValue(startDateValue);
 
        //Значение второго параметра (Дата окончания)
        var endDateValue = context.Parameters[1];
        //Отформатированное строковое значение Даты окончания
        var endDateFormatedValue = context.GenerationContext.FormatProvider.FormatValue(endDateValue);
 
        //Формируем текст значений оповещения
        var formattedValue = SR.T("с {0} до {1}", startDateFormatedValue, endDateFormatedValue);
 
        if (context.Parameters.Count == 3)
        {
            //Формируем название поля
            var caption = context.Parameters[2];
            var captionFormatedValue = context.GenerationContext.FormatProvider.FormatValue(caption);
            captionFinish = captionFormatedValue;
        }
 
        //Генерируем разметку
        return new FormatedValue(string.Format("{0} {1}", captionFinish, formattedValue));
    }
}

Создание собственной функции генератора шаблонов оповещений

Реализация ITemplateGeneratorFunctionsContainer аналогична реализации INotificationFunctions. В данном примере реализована функция PriorityHight, которая возвращает true, если задача имеет приоритет Высокий. Отличие данных точек расширения в том, что INotificationFunctions используются для отображения в разметке, тогда как ITemplateGeneratorFunctionsContainer используются в условиях фильтраций Condition.

Пример:

<Filter>
  <Condition>
    (PriorityHight({$New}) = true)
  </Condition>
</Filter>

Пример класса точки расширения

[Component]
public class TemplateGenerator : ITemplateGeneratorFunctionsContainer
{
    public static FormatedValue PriorityHight(FunctionEvaluationContext context)
    {
        var result = false;
        if (context != null && context.Parameters != null && context.Parameters.Count > 0)
        {
            var ctxParam = context.Parameters[0];
            if (ctxParam != null && ctxParam.Value is ITaskBase)
            {
                var task = (ITaskBase)ctxParam.Value;
 
                if (task.Priority == TaskPriority.High)
                    result = true;
            }
        }
 
        return new FormatedValue(result);
    }
}

Данную функцию можно добавить в уже существующий шаблон оповещений Tasks.Task.xml в <Notification Name="Create">. В данном шаблоне уже существует условие, при котором оповещение отправится получателям, но если добавить and (PriorityHight({$New}) = true) – тогда будут отправляться оповещения при создании задачи, если её приоритет высокий.

Ссылки на элементы API

INotificationFunctions (для версий 3.13, 3.15, 4.0);
ITemplateGeneratorFunctionsContainer (для версий 3.13, 3.15, 4.0).

Ссылки на базу знаний

Шаблоны оповещений.