«Арете — сервер мессенджеров, Max edition»

Руководство по шаблонизатору

Базовый пример

Создать шаблон

Допустим, в справочнике создан шаблон с кодом УведомлениеОЗаказе:

Содержимое шаблона

Поступил заказ от #клиент на сумму #сумма

Передать параметры и сформировать ответ

В обработчике создаём структуру параметров. Имена её свойств совпадают с переменными #клиент и #сумма в шаблоне. Затем вызываем ВывестиПоШаблону и передаём полученную строку в метод отправки сообщения.

Формирование ответа

ПараметрыШаблона = Новый Структура;
ПараметрыШаблона.Вставить("клиент", "ООО Ромашка");
ПараметрыШаблона.Вставить("сумма", 15000);

Текст = АСМ_Шаблонизатор.ВывестиПоШаблону("УведомлениеОЗаказе", Неопределено, ПараметрыШаблона);
Параметры = Новый Структура("text", Текст);
АСМ_М.ОтправитьСообщение(Бот, Параметры, Вход);

При выводе #клиент будет заменён значением ООО Ромашка, а #сумма — строковым представлением числа 15000.

Методы шаблонизатора

В общем модуле АСМ_Шаблонизатор предусмотрены два экспортных метода. Оба возвращают строку.

ВывестиПоШаблону

Метод получает сохранённый шаблон, обрабатывает его и возвращает готовый текст: ВывестиПоШаблону(ИдентификаторШаблона, Область, СтруктураПараметров).

Параметры метода

ИдентификаторШаблона — код элемента справочника «АСМ — Шаблоны».
Область — имя нужной области или Неопределено. Если областей в шаблоне нет, значение этого параметра не влияет на результат.
СтруктураПараметров — структура или соответствие со значениями для подстановки, условий и циклов.

Вывод всего шаблона или отдельной области

Если в шаблоне есть области, Неопределено выводит все области по порядку, а имя — только выбранную область. Пустая строка не означает «вывести всё» и не совпадает ни с одной областью.

Вывод всего шаблона

Текст = АСМ_Шаблонизатор.ВывестиПоШаблону("УведомлениеОЗаказе", Неопределено, ПараметрыШаблона);

Вывод выбранной области

Текст = АСМ_Шаблонизатор.ВывестиПоШаблону("ШаблонОбласти", "краткая", ПараметрыШаблона);

ДобавитьПоШаблону

Метод ДобавитьПоШаблону(Текст, ИдентификаторШаблона, Область, СтруктураПараметров) обрабатывает шаблон и добавляет результат к строке Текст. По сути, это сокращённая запись выражения Текст + ВывестиПоШаблону(...).

Последовательное добавление фрагментов

Параметры = ПараметрыШаблонаСборка();
Текст = "";
Текст = АСМ_Шаблонизатор.ДобавитьПоШаблону(Текст, "ШаблонСборка", "заголовок", Параметры);
Текст = АСМ_Шаблонизатор.ДобавитьПоШаблону(Текст, "ШаблонСборка", "список", Параметры);

Синтаксис шаблона

Шаблон состоит из обычного текста, переменных с префиксом # и управляющих конструкций с префиксом @. Регистр символов в именах и директивах не учитывается. Имя должно начинаться с буквы или подчёркивания; далее можно использовать буквы, цифры и подчёркивания.

Краткий справочник конструкций

Конструкция	Назначение
`#имя`	Подстановка значения из параметров
`#объект.поле`	Подстановка поля структуры, соответствия или строки таблицы значений
`@если #имя` … `@иначе` … `@конецесли`	Ветвление; `@иначе` можно опустить
`@для каждого элемент из #коллекция цикл` … `@конеццикла`	Перебор массива структур или таблицы значений
`@область имя` … `@конецобласти`	Именованный фрагмент для выборочного вывода

Обозначения # и @ используются также в роутинге, но имеют другое значение. В шаблоне #имя обозначает параметр, а @если, @для и @область являются директивами шаблонизатора.

Переменные

Простая переменная записывается как #имя. Шаблонизатор ищет одноимённый ключ в переданной структуре или соответствии и заменяет переменную строковым представлением найденного значения. Регистр имени не учитывается: #Клиент и #клиент обращаются к одному параметру.

Для обращения к полю используется запись #объект.поле. Объектом может быть структура, соответствие или строка таблицы значений. Поддерживается только один уровень: #пользователь.имя допустимо, #заказ.клиент.имя — нет.

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

Примеры подстановки переменных

Простые переменные

Здравствуйте, #клиент!
Сумма заказа: #сумма

Обращение к полям структуры

@если #пользователь.имя
Клиент: #пользователь.имя, роль — #пользователь.роль
@конецесли

Подготовка параметров для этого шаблона:

Пользователь = Новый Структура;
Пользователь.Вставить("имя", Строка(Вход.Пользователь));
Пользователь.Вставить("роль", "пользователь Max");

Параметры = Новый Структура;
Параметры.Вставить("пользователь", Пользователь);

Условия

Синтаксис и правила вычисления

Условный блок начинается с @если и завершается директивой @конецесли. Между ними можно добавить необязательную ветку @иначе.

После @если указывается ровно одна переменная: #имя или #объект.поле. Операций сравнения в языке шаблона нет. Выражение @если #сумма > 0 не поддерживается; результат такого сравнения нужно заранее вычислить в коде 1С и передать отдельным параметром.

Условие считается выполненным в следующих случаях:

значение типа Булево равно Истина;
строка заполнена;
число не равно нулю.

Пустая строка, число 0 и значение Ложь переводят выполнение в ветку @иначе. Условия можно вкладывать друг в друга. Допускаются также условие внутри цикла и цикл внутри условия.

Примеры условий

Проверка заполненности строки

@если #имя
Здравствуйте, #имя!
@иначе
Здравствуйте!
@конецесли

Проверка числового значения

@если #товаровВКорзине
Товаров в корзине: #товаровВКорзине
@иначе
Корзина пуста
@конецесли

Циклы

Синтаксис и ограничения

Цикл перебирает массив структур или таблицу значений. Общая форма записи: @для каждого элемент из #коллекция цикл … @конеццикла. После из допускается только простая переменная коллекции: запись вида #объект.коллекция не поддерживается.

Имя элемента после слова каждого можно указать с префиксом # или без него. В теле цикла обращение к элементу всегда записывается через #, обычно в форме #элемент.поле. После завершения цикла локальная переменная элемента удаляется.

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

Примеры циклов

Подготовка массива структур

Позиции = Новый Массив;

Позиция = Новый Структура("номенклатура, количество, цена", "Кофе", 2, 500);
Позиции.Добавить(Позиция);
Позиция = Новый Структура("номенклатура, количество, цена", "Чай", 1, 350);
Позиции.Добавить(Позиция);

Параметры = Новый Структура;
Параметры.Вставить("позиции", Позиции);
Параметры.Вставить("количество", Позиции.Количество());

Вывод элементов массива

Состав заказа:

@для каждого позиция из #позиции цикл
• #позиция.номенклатура — #позиция.количество шт. × #позиция.цена
@конеццикла

Итого позиций: #количество

Условие внутри цикла

@для каждого товар из #товары цикл
#товар.наименование — #товар.цена
@если #товар.скидка
скидка: #товар.скидка
@конецесли
@конеццикла

Области

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

Имя области передаётся вторым параметром в ВывестиПоШаблону или ДобавитьПоШаблону и сравнивается без учёта регистра:

Неопределено — вывести все области в порядке их расположения;
имя области — вывести только эту область;
несуществующее имя или пустая строка — вернуть пустую строку.

Если в шаблоне объявлена хотя бы одна область, текст за пределами областей в результат не включается. Области нельзя вкладывать друг в друга.

Пример именованных областей

Именованные области

@область краткая
Статус заявки #номер: #статус
@конецобласти

@область подробная
Заявка #номер
Клиент: #клиент.имя
Статус: #статус
@конецобласти

Значение "краткая" во втором параметре метода вернёт только первую область.

Сборка из нескольких фрагментов

ДобавитьПоШаблону удобно использовать, когда итоговое сообщение состоит из нескольких частей. Например, один шаблон может содержать области заголовок, список и подвал. Код выбирает нужные области и определяет порядок их добавления.

Фрагменты необязательно брать из одного шаблона. Последовательные вызовы могут использовать разные идентификаторы и разные структуры параметров. Метод не добавляет разделители автоматически: необходимые пробелы и переводы строк должны находиться в самих шаблонах либо добавляться в коде.

Хранение и версии шаблонов

Шаблоны хранятся в справочнике АСМ — Шаблоны. Код элемента используется как идентификатор в вызовах ВывестиПоШаблону и ДобавитьПоШаблону. Содержимое можно редактировать в режиме 1С:Предприятия.

Версии шаблона

История изменений находится в табличной части «Версии шаблона». Для версии хранятся содержание, номер, дата, комментарий и признак «Актуальная». При записи справочника используется одна актуальная версия. Для возврата к предыдущему варианту достаточно отметить нужную строку как актуальную и записать элемент.

Кэширование изменений

Разобранные шаблоны кэшируются через АСМ_НастройкиПовтИсп.ТокенизироватьШаблон. При записи элемента справочника повторно используемые значения обновляются автоматически, поэтому отдельно перезапускать сеанс после изменения текста не требуется.

Создание шаблонов обработчика

Шаблоны, необходимые обработчику бота, можно объявить в СведенияОбОбработчике. При инициализации обработчика АСМ_Служебный.СоздатьШаблоныОбработчика создаст отсутствующие элементы и добавит версию по умолчанию.

Описание шаблона в сведениях обработчика

Шаблон = Сведения.ШаблоныПоУмолчанию.Добавить();
Шаблон.Идентификатор = "УведомлениеОЗаказе";
Шаблон.Содержимое = ПолучитьМакет("УведомлениеОЗаказе").ПолучитьТекст();
Шаблон.Комментарий = "Сообщение о новом заказе";

Создание шаблонов обработчика

АСМ_Служебный.СоздатьШаблоныОбработчика(СведенияОбОбработчике());

Поведение при ошибках

Шаблонизатор по-разному обрабатывает отсутствующие данные, некорректные конструкции и запрещённую вложенность.

Если шаблон с указанным кодом не найден, ВывестиПоШаблону возвращает пустую строку.
Если простая переменная или её поле не найдены, в результате остаётся исходная запись, например #клиент.
Если не найдена переменная условия, исходный блок от @если до @конецесли выводится без обработки.
Если не найдена коллекция цикла либо она имеет неподдерживаемый тип, исходный текст цикла выводится без обработки.
Незакрытые условия и циклы также остаются в результирующем тексте.
Незакрытая область не выводится. Если перед ней были корректно закрытые области, их содержимое сохраняется в результате.
Конструкция, которая не распознана из-за неверного синтаксиса, обрабатывается как обычный текст.
Вложенный цикл, вложенная область или неподдерживаемый тип значения в условии вызывают исключение.

Частые ошибки

Вместо Неопределено в параметр области передана пустая строка. Если шаблон содержит области, результат будет пустым.
В @если записано сравнение, например #сумма > 0. Вычислите условие в коде 1С и передайте готовое значение.
Использована цепочка #заказ.клиент.имя. Поддерживается только одно обращение к полю.
В цикл передан массив строк или чисел. Используйте массив структур либо таблицу значений.
Один цикл или одна область вложены в другие. Такая вложенность запрещена.
В условие передана дата, ссылка, массив или значение другого неподдерживаемого типа. Допустимы только Булево, Строка и Число.
Конструкции роутинга использованы внутри шаблона. @ЭтоАдминистратор не является директивой шаблонизатора.
Идентификатор в вызове не совпадает с кодом элемента справочника. В этом случае метод возвращает пустую строку без исключения.