Шаблоны файлов и плейсхолдеры¶

Карточка шаблона файла¶

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

Создать новый шаблон файла можно с помощью правого меню системы Создать карточку -> Справочники -> Шаблон файла:

Будет открыта новая карточка шаблона файла.

Необходимо заполнить следующие поля:

Название - название шаблона файла;
Группа - группа, в которую входит шаблон (не обязательно для заполнения). Группы могут использоваться для логической группировки шаблонов (при выборе их из карточки документа), например, группа Письма:
Тип шаблона - карточка или представление. Указывается, где будет использоваться данный шаблон (для конкретных карточек документов или для представлений);
Системный - флаг указывает, что данный шаблон является системным и файл по нему не генерируется;
Доступно ролям - список сотрудников/ролей, которым будет доступно создание файлов по данному шаблону;
Типы/Представления - в зависимости от выбранного типа шаблона в данном поле указывается список типов документов или список представлений, для которых будет использоваться данный шаблон файла, причем при выборе типа, наравне с одиночными значениями, для выбора доступны группы ссылок с типами Тип карточки и Тип документа;
Конвертировать в PDF - флаг указывает, что файл, создаваемый по данному шаблону, будет сконвертирован в PDF;
Алиасы плейсхолдеров - можно определить алиас с заданным названием, затем он подставляется в текст документа вместо плейсхолдера алиаса (более подробное описание см. в разделе Алиасы плейсхолдеров);
Выполнить компиляцию - кнопка, которая производит компиляцию скриптов в тексте файла (если тип файла поддерживает скрипты) и расширений для данного шаблона;
Файлы - секция для добавления шаблонного файла. Для одного шаблона можно добавить только один файл.

Шаблонный файл может быть только одним из следующих типов: docx, xlsx (xlsm, если с макросами), html или txt.

Note

Если прикреплённый файл шаблона имеет формат html, установлен флаг Конвертировать в PDF, а в настройках сервера установлен флаг Отключить конвертацию HTML в PDF, то при генерации такого файла, флаг Конвертировать в PDF будет игнорироваться, а в карточке “Шаблон файла” будет отображено предупреждение: “Для формата прикреплённого файла в настройках сервера отключена поддержка конвертации в PDF.”.

При формировании файла по шаблону из карточки документа или представления, вместо плейсхолдеров будут подставлены данные из полей карточки/представления (или данные из связанных таблиц).

Note

Непосредственно в имени файла, приложенного к шаблону, также можно прописывать плейсхолдеры и алиасы, которые будут заменены в имени файла. При формировании имени открываемого файла символы, некорректные для файловой системы (такие как кавычки, двоеточия и др.) будут заменены на подчёркивание _, но, если файл прикладывается к карточке, то имя сохраняется как есть. Расширение файла не должно содержать плейсхолдеры. Примеры: Договор-{f:DocumentCommonInfo.FullNumber}.docx, {*alias} {$LocalizationString}.xlsx.

Important

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

Плейсхолдеры необходимо вставить непосредственно в текст файла шаблона - docx, xlsx, html или txt.

Note

Новые шаблоны файлов станут доступны для использования только после перезапуска пользователем Tessa Client.

Просмотреть список всех шаблонов файлов в системе можно на рабочем месте Администратор, в представлении Шаблоны и уведомления -> Шаблоны файлов:

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

В представлении Шаблоны файлов (вкладка -> Администратор -> Шаблоны и уведомления) можно посмотреть пример настроенных шаблонов файлов:

В формате docx - “Протокол совещания”;
В формате html - “Мои задания”;
В формате xlsx - “Мои задания (Excel)”, “Протокол совещания (Excel)”.

Алиасы плейсхолдеров¶

В списке алиасов в карточке шаблона файла можно определить алиас с заданным названием, затем он будет подставлен в текст документа вместо плейсхолдера алиаса:

Note

Имя алиаса не должно содержать пробельных символов или переводов строк (по диапазонам Unicode). Рекомендуется указывать алиасы английскими буквами.

Example

Например, в документе есть строка: Тема документа: {*subject}. И в списке алиасов шаблона есть строка: subject f:DocumentCommonInfo.Subject trim. Тогда при разборе выражения будет выполняться замена плейсхолдеров для строки: Тема документа: {f:DocumentCommonInfo.Subject trim}.

Алиасы работают для любых плейсхолдеров, в т.ч. для плейсхолдеров таблиц и плейсхолдеров, добавленных в расширениях.

Расширения¶

Для шаблона файлов есть возможность написать расширение, которое будет выполняться при генерации шаблона файлов. Данные расширения могут использоваться для изменения полученных подсистемой плейсхолдеров данных, обработки кастомных плейсхолдеров, изменения стиля полученного документа (например, выделить текст определенным цветом в документе Word, выделить ячейку в документе Excel и т.д.).

Во вкладке Расширения есть следующие кнопки:

Выполнить компиляцию - кнопка, которая производит компиляцию скриптов в тексте файла (если тип файла поддерживает скрипты) и расширений для данного шаблона.
Выполнить компиляцию всех шаблонов файлов - кнопка, которая производит компиляцию скриптов в тексте файла и расширений для всех шаблонов файлов.

Во вкладке Расширения есть следующие виды сценариев расширений:

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

Более подробно о функционале расширений замены плейсхолдеров можно посмотреть в Руководстве разработчика.

Плейсхолдеры¶

Описанные в данном разделе плейсхолдеры используются во множестве мест, например:

В шаблонах файлов (в том числе для указания имени файла)
В настройке Имя файла в карточке виртуального файла
Для указания названия последовательности и формата полного номера
Для формирования текста уведомления
Для текстового представления условия в типах условий
Для обозначения имён групп в истории заданий
В модуле потокого ввода для формирования имени файла, который был отсканирован и прикладывается к карточке документа
В настройках многих действий конструктора бизнес-процессов
В Tessa Admin для настройки дайджеста типа карточки.

Note

Не все типы плейсхолдеров могут быть использованы в указанных местах. В шаблонах файлов могут быть использованы все типы плейсхолдеров.

Список доступных плейсхолдеров с их кратким описанием представлен в таблице (а также ссылки на соответствующие разделы с подробным описанием плейсхолдеров):

Плейсхолдер	Описание
Плейсхолдер {f:…}	Универсальный плейсхолдер, который позволяет вывести значение из любого поля карточки, а также соединить любое поле карточки с данными любых других таблиц, чтобы вывести значение из этих таблиц
Плейсхолдер {t:…}	Используется для вывода нескольких значений в виде таблицы или списка, где каждая строка (или элемент списка) содержит одну или несколько колонок
Плейсхолдер {task:…}	Аналогичен плейсхолдеру {f:…}, но позволяет вывести значение из полей текущего задания
Плейсхолдеры {fv:…} и {tv:…}	Аналогичны плейсхолдерам {f:…} и {t:…} (соответственно), но позволяют вывести все значения представления с заданным алиасом
Плейсхолдеры {info:…} и {tinfo:…}	Аналогичны плейсхолдерам {f:…} и {t:…} (соответственно), но позволяют отобразить данные из переданной в контекст обработки плейсхолдеров дополнительной информации
Плейсхолдер-объявление {⁠`#alias` placeholder}	Плейсхолдер-объявление, который позволяет задать указанному в нем плейсхолдеру алиас, который может использоваться как часть других плейсхолдеров. Сам плейсхолдер-объявление всегда удаляется из текста документа
Плейсхолдеры {n}, {0n}, {00n} и др.	Используются для вывода номера строки в таблице или номера элемента списка
Дополнительные плейсхолдеры	Различные дополнительные плейсхолдеры, которые могут использоваться в шаблонах файлов

Скалярное значение (одну строку) возвращают плейсхолдеры {f:...} и {fv:...}, а также плейсхолдеры {t:...} и {tv:...}, если используются с параметром separate by (separator string) (т.е. все значения списка объединяются в одну строку с указанным разделителем).

Плейсхолдер `{f:...}`¶

Плейсхолдер {f:…} - универсальный плейсхолдер, который позволяет вывести значение из любого поля карточки, а также соединить любое поле карточки с данными любых других таблиц, чтобы вывести значение из этих таблиц.

Примеры использования:

{f:DocumentCommonInfo.AuthorName} – автор документа, это поле карточки AuthorName из секции DocumentCommonInfo.

Note

Если какой-то секции или поля нет (не удалось выполнить выборку), то вместо плейсхолдера подставляется пустая строка (см. ниже пример).
{f:DocumentCommonInfo.AuthorID-(UserID)->RoleUsers.ID->DepartmentRoles.ID->Roles.Name} – сложная выборка Департамент автора, которая соединяет поле карточки AuthorID из секции DocumentCommonInfo (т.е. идентификатор автора документа) с данными из таблиц RoleUsers, DepartmentRoles и Roles (в указанной последовательности), чтобы получить название департамента.

Посредством стрелок → определяется способ соединения таблиц:
- Section1.Field1->Section2.Field2:
  Система возьмет текущее значение поля карточки Section1.Field1 и использует его для выборки поля Field2 из таблицы Section2 по условию Section2.ID = Section1.Field1. Например, если в карточке есть ссылка на сотрудника в каком-то поле, то вы можете выбрать из справочника сотрудников его адрес электронной почты: DocumentCommonInfo.AuthorId->PersonalRoles.Email.
  
  Эквивалентная выборка
```
select Field2 from Section2 where Id = Section1.Field1
```
- Section1.Field1=>Section2.Field2:
  Аналогично предыдущему, но строка из связанной таблицы выбирается по RowId. Это нужно, если поле ссылается на строку в дочерней секции (справочника или другой карточки).
  
  Эквивалентная выборка
```
select Field2 from Section2 where RowId = Section1.Field1
```
- Section1.Field1-(KeyField)->Section2.Field2:
  Также выбирает значение из таблицы Section2, но выборка строки происходит по полю KeyField.
  
  Эквивалентная выборка
```
select Field2 from Section2 where KeyField = Section1.Field1
```
  Note
  
  Если сложная выборка вернёт более одной строки, то данные строки будут выведены через точку с запятой. Например, плейсхолдер {f:OutgoingRefDocs.DocID->DocumentCommonInfo.FullNumber} выведет полные номера документов, с которыми связан текущий: Дпр-00004; Исх-00001; П-000231.
В плейсхолдере также можно через ещё одно двоеточие дописать строку форматирования, например: {f:DocumentCommonInfo.CreationDate:dd/MM/yyyy HH\:mm} (разделитель между часами и минутами выводится с эскейп-символом \:, более подробное описание см. в разделе Плейсхолдер {t:…}, Возможные параметры форматирования, п. 11).

Будет подставлена дата создания карточки из поля CreationDate, отформатированная как dd/MM/yyyy HH:mm (день.месяц.год часы:минуты, т.е. 18.02.2016 12:01). Строка форматирования используется для преобразования значения поля в строку стандартными для .NET средствами (актуально для значений, отличных от строки, например, дата/время или число).

Вместо dd/MM/yyyy HH:mm укажите g, чтобы учитывать настройки форматирования у сотрудника.
Также значения данного плейсхолдера можно отсортировать, выбрать уникальный distinct или применить иное форматирование (кроме группировки - group by). Описание возможностей аналогично плейсхолдеру {t:…}, см. Возможные параметры форматирования в плейсхолдере.

Плейсхолдер `{t:...}`¶

Плейсхолдер {t:…} нужен для вывода нескольких значений в виде таблицы или списка, где каждая строка (или элемент списка) содержит одну или несколько колонок (для списка это просто несколько значений рядом).

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

Группировка (см. ниже) позволяет объединять и как угодно группировать любые данные из различных таблиц.

{t:Секция1.Поле1->Секция2.Поле2 distinct top 5 group by Секция2.Поле3, Секция1.Поле4 order by Секция1.Поле5 desc, Секция2.Поле6 format as (* [$LocalizedString]: [0]) separate by (;\n) utc trim task:custom format}

Группировку/сортировку рекомендуется указывать только для первого плейсхолдера в строке, чтобы результат был ожидаемым (в порядке объявления в документе).

Однако, в особо сложных случаях, группировка и сортировка для плейсхолдеров в пределах строки могут отличаться. При этом при незаданной группировке она наследуется от предыдущего плейсхолдера (по порядку объявления).

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

Возможные параметры форматирования в плейсхолдере:

Секция1.Поле1->Секция2.Поле2 - аналогично плейсхолдеру {f:…}, т.е. таблиц может быть несколько, их можно объединять по ID →, по RowID =>, по любой другой колонке - (ParentRowID) →.
distinct - определяет, что в результаты запроса попадут только строки, которые были определены как отличающиеся в результатах запроса. Аналогично запросу SQL вида select distinct. Это позволяет, например, вывести только фамилии исполнителей, которые отличаются между собой.
top N - указываем, что требуется выбрать не больше, чем заданное количество строк из результатов. Например, top 10 для вывода первых десяти или top 1 для вывода первой строки (независимо от их количества).
group by Секция2.Поле3, Секция1.Поле4 - позволяет указать, по каким ключевым колонкам строки будут объединяться между собой. По умолчанию (когда выражение group by не указано) объединение выполняется по Секция1.RowID, где Секция1 - это первая заданная секция. В выражении может быть опущено название секции, тогда будет использоваться первая заданная секция.

Например, group by ParentRowID будет группировать строки по колонке Секция1.ParentRowID. Если запрос к базе данных вернёт больше одной строки с одними и теми же значениями ключевой колонки ParentRowID (в этом примере), то эти значения будут объединяться в пределах группы (строки таблицы) через символ разделителя (по умолчанию точка с запятой) по аналогии с выводом плейсхолдера {f:…}. Например, будут отображены одна строка таблицы Иванов И.И.; Петров П.П. и другая строка Сидоров С.С. (т.к. первые две строки из результатов запроса имели одинаковый ParentRowID, а третья строка имела отличающийся ParentRowID).
order by Секция1.Поле5 desc, Секция2.Поле6 - указание сортировки, которая выполняется при запросе данных из SQL. Если указано несколько колонок, то выполняется сначала сортировка по первой колонке, затем по второй. Необязательное слово desc указывает, что сортировка выполняется по убыванию, а asc - по возрастанию (по умолчанию). В примере выполняется сначала сортировка строк результата по колонке Секция1.Поле5 по убыванию, а затем в пределах одинакового значения в Поле5 - по колонке Секция2.Поле6 по возрастанию. Если секцию не указать, то будет выполнена сортировка по колонке первой таблицы.

Например, order by Order указывает, что сортировка будет выполнена по колонке Секция1.Order. Указание сортировки особенно удобно для упорядоченных коллекционных секций карточки. Если выражение order by не задано, то сортировка будет произведена по результирующей колонке по возрастанию, в примере это Секция2.Поле2.
format as (format string) - указывает, что каждое значение при выводе должно быть дополнительно отформатировано с учётом строки формата format string. Строка формата соответствует такой строке в стандартном выражении String.Format в .NET, где вместо фигурных скобок участвуют квадратные. В такой строке могут быть встроенные строки локализации.

Например, format as (* [$LocalizedString]: [0]) аналогично вызову String.Format("* {$LocalizedString}: {0}", value), где подстрока {$LocalizedString} будет заменена на строку локализации, а {0} - это позиция для выводимого значения value. Символы \n соответствуют переводу строки.
separate by (separator string) - определяет формат строки-разделителя separator string между несколькими значениями в пределах одной группы (для плейсхолдера {f:…} это будут любые несколько значений). По умолчанию используется разделитель “; “, т.е. “точка с запятой и пробел”. Символы \n соответствуют переводу строки. Разделитель ;\n означает, что между значениями будут вставлены точка с запятой и перевод строки. Например:

Иванов И.И.;

Петров П.П.;

Сидоров С.С.
utc - если значение, возвращаемое плейсхолдером, является датой (соответствует типам SQL: Date, DateTime, DateTime2), то оно выводится без приведения к локальному времени пользователя, который генерирует документ по шаблону. При выводе дат по умолчанию выводятся дата и время, приведённые к локальному времени, для типов SQL DateTime и DateTime2. Указание utc позволяет не выполнять корректировку времени в соответствии с часовым поясом пользователя. Тип данных SQL Date по умолчанию выводится, как только дата (без времени), при этом не выполняется приведение к локальному времени, т.е. настройка utc работает по умолчанию и игнорируется при явном указании.
trim - после окончательного формирования строки, которая заменяет плейсхолдер, удаляются начальные и конечные символы пробелов, табуляций и переводов строк (в соответствии с определением таких символов в таблицах Unicode). Например, из строки Иванов И.И.; Петров П.П. будет удалён конечный пробел.
task - позволяет получить данные не из основной карточки, а из карточки задания.
custom format - дополнительное форматирование, выводимое в конце выражения плейсхолдера после двоеточия. Например, для вывода типа SQL DateTime как дата и время без секунд, можно использовать строку g, что аналогично dd.MM.yyyy HH\:mm. Разделитель между часами и минутами выводится с эскейп-символом \:. Если нужен символ \, то его следует задвоить \\. Указанное значение аналогично использованию форматирования типов данных .NET через IFormattable.ToString(), в этом примере: dateTimeValue.ToString("g", LocalizationManager.CurrentCulture).

Примеры стандартных строк форматирования, которые могут использоваться в выражении custom format:
- g: дата со временем без указания секунд (пример: 27.05.2022 18:09).
- G: дата со временем с секундами (пример: 27.05.2022 18:09:30).
- d: дата без времени (пример: 27.05.2022).
- t: время без указания секунд (пример: 18:09).
- T: время с секундами (пример: 18:09:30).
- N: число с разделителями разрядов, что удобно при выводе денежных сумм (пример: 1 200 340,60).
За подробностями по использованию строк форматирования дат, времени и чисел обратитесь к документации .NET.

Warning

Если в выражениях плейсхолдера двоеточие используется в месте, не предусмотренном стандартным форматированием, например: format as (value: [0]), то при отсутствии явно заданной строки форматирования custom format требуется завершить определение плейсхолдера двоеточием, т.е. так, будто бы строкой custom format является пустая строка.

Например: {t:OutgoingRefDocs.DocID->DocumentCommonInfo.AuthorName format as (Автор: [0]):}. Аналогично и для плейсхолдеров {f:...}, {fv:...}, {tv:...}.

Все выражения, кроме списка таблиц в пункте 1, не обязательны для указания.

Плейсхолдер `{task:...}`¶

Плейсхолдер {task:…} - аналогичен плейсхолдеру {f:…}, но в отличие от него позволяет вывести значение из задания, такие как текущий исполнитель, автор, дата создания, плановая дата завершения и т.д., а также соединить любое из этих полей с данными любых других таблиц, чтобы вывести значение из этих таблиц.

Примеры использования:

{task:AuthorName} – автор задания. Это поле AuthorName из объекта задания.
{task:AuthorID-(UserID)->RoleUsers.ID->DepartmentRoles.ID->Roles.Name} – сложная выборка Департамент автора задания, которая соединяет поле AuthorID из объекта задания (т.е. идентификатор автора задания) с данными из таблиц RoleUsers, DepartmentRoles и Roles (в указанной последовательности), чтобы получить название департамента.

Описание возможностей плейсхолдера идентично плейсхолдеру {f:…} (см. Возможные параметры форматирования в плейсхолдере), за исключением следующих отличий:

Вместо конструкции Секция1.Поле1->Секция2.Поле2 используется конструкция Поле1->Секция2.Поле2, где Поле1 может принимать одно из следующих значений:
- Created - дата создания задания;
- CreatedByID - идентификатор пользователя, создавшего задание;
- CreatedByName - имя пользователя, создавшего задание;
- Modified - дата последнего изменения задания;
- ModifiedByID - идентификатор пользователя, внесшего последние изменения в задание;
- ModifiedByName - имя пользователя, внесшего последние изменения в задание;
- Planned - плановая дата завершения задания;
- InProgress - дата взятия задания в работу;
- AuthorID - идентификатор автора задания;
- AuthorName - имя автора задания;
- RoleID - идентификатор роли исполнителя задания;
- RoleName - имя роли исполнителя задания;
- UserID - идентификатор пользователя, взявшего задание в работу;
- UserName - имя пользователя, взявшего задание в работу.
Не поддерживает использование параметра task.

Плейсхолдеры `{fv:...}` и `{tv:...}`¶

Аналогичны плейсхолдерам {f:…} и {t:…} (соответственно), но позволяют отобразить результаты выполнения представления с заданным алиасом, в данных по таблицам.

Пример:

{tv:АлиасПредставления.КолонкаПредставления->Секция1.Поле1 top 5 with param АлиасПараметра НастройкиПараметра group by Колонка2, Колонка3 order by Колонка4 desc, Колонка5 format as (* [$LocalizedString]: [0]) separate by (;\n) utc trim:custom format}

Возможные параметры форматирования в плейсхолдере:

АлиасПредставления - это алиас представления, которое будет выполнено. Представление выполняется независимо от прав доступа пользователя на это представление (выполнение происходит на сервере, а возможность выполнить представление определяется только правами на использование шаблона файла). Не рекомендуется выдавать права доступа на роли для представлений, используемых только в шаблонах, т.к. это даст пользователю возможность выполнить представление без фильтрации по карточке, получив доступ ко всем данным в БД.
КолонкаПредставления - название колонки, возвращаемое представлением, которая будет отображена в плейсхолдере, если не задана конструкция ->Секция1.Поле1.
->Секция1.Поле1 - аналогично плейсхолдеру {f:…}, можно делать сложную выборку данных из различных таблиц, которые можно объединять по ID →, по RowID =>, по любой другой колонке - (ParentRowID) →. Основное отличие, что в качестве первого значения для объединения используется значение из КолонкаПредставления.
top N - указывает, что требуется выбрать не больше, чем заданное количество строк из результатов. Если представление поддерживает пейджинг, то выбирается первая страница размером в N строк. Если представление не поддерживает пейджинг, то будут выбраны все строки, после чего заданное количество строк будет отображено, а остальные строки - игнорированы.
with param АлиасПараметра НастройкиПараметра - указывает алиас параметра представления, в который будет передано значение, в зависимости от настроек параметра. Настройки параметра могут быть следующими:
- Без настроек параметра (with param АлиасПараметра) - в качестве значения параметра подставляется идентификатор текущей карточки, для которой генерируется шаблон. Если шаблон генерируется из представления, то передается идентификатор текущего пользователя.
- value ЗначениеПараметра (with param АлиасПараметра value ЗначениеПараметра) - в качестве параметра передается константа, указанная в ЗначениеПараметра. Система конвертирует указанное значение в тип параметра (в случае невозможности конвертации, система выдаст ошибку). Если необходимо указать в качестве значения параметра строку с пробелами, то эту строку необходимо заключить в двойные кавычки "...", при этом для использования символа двойных кавычек внутри пишутся две двойные кавычки "".
  
  Note
  
  Если в качестве значения параметра используется идентификатор, то его следует писать без фигурных скобок.
  
  Important
  
  Если данный плейсхолдер задан в тексте документа, то в значении параметра нельзя использовать символы фигурных скобок {}.
- from АлиасПлейсхолдера (with param АлиасПараметра from АлиасПлейсхолдера) - в качестве параметра передается значение из плейсхолдера-объявления с указанным алиасом плейсхолдера (см. Плейсхолдер-объявление {⁠#alias placeholder}). Данную конструкцию можно использовать в следующих ситуациях:
  1. Для передачи значения плейсхолдера строкового типа ({f}, {fv} и т.д.) в качестве параметра представления. Можно использовать как в плейсхолдере {fv}, так и {tv}. Пример передачи в качестве параметра PartnerID идентификатора контрагента из секции DocumentCommonInfo, из поля PartnerID:
    - Плейсхолдер-объявление - {⁠#Parner f:DocumentCommonInfo.PartnerID}
    - Использование в параметре плейсхолдера - {... with param PartnerID from Partner ...}
  2. Для передачи значения табличного плейсхолдера ({t}, {tv} и т.д.) из родительской таблицы в дочернюю. Можно использовать только в плейсхолдере {tv} и только, если для родительской таблицы используется плейсхолдер-объявление. В такой ситуации в качестве АлиасПлейсхолдера пишется АлиасПлейсхолдера.ИмяПоля. Пример передачи из родительской таблицы Performers значения Email как параметра в дочернюю таблицу:
    - Плейсхолдер-объявление родительской таблицы - {⁠#Performers t:Performers.UserID->PersonalRoles.*}
    - Использование в параметре плейсхолдера дочерней таблицы - {... with param PartnerID from Performers.Email ...}
group by Колонка2, Колонка3 - группировка строк в плейсхолдере {tv:…} по названиям колонок, возвращаемых представлением. Если группировка не указана, то строки не группируются и возвращаются в том виде и в том же порядке, в котором их возвращает представление.
order by Колонка4 desc, Колонка5 - сортировка, выполняемая в представлении по заданным колонкам. Сортировка выполняется средствами самого представления, а задаваемые колонки - это алиасы колонок, способ сортировки по которым определяется в представлении. Необязательное слово “desc” указывает, что сортировка выполняется по убыванию, а “asc” - по возрастанию (по умолчанию). Если выражение не указано, то выполняется сортировка по умолчанию, заданная в метаинформации представления #view.
format as (* [$LocalizedString]: [0]) - форматирование каждого возвращаемого значения. Аналогично выражению format as для плейсхолдеров {f:…} и {t:…}.
separate by (;\n) - указание разделителя между несколькими значениями в пределах группы (строки таблицы для {tv:…}) или для всех возвращённых значений в плейсхолдере {fv:…}. Аналогично выражению separate by для плейсхолдеров {f:…} и {t:…}.
utc - вывод значения без корректировки по часовому поясу пользователя. Форматирование дат и корректировка часового пояса работает аналогично плейсхолдерам {f:…} и {t:…}.
trim - удаление начальных и конечных пробельных символов. По аналогии с выражением в {f:…} и {t:…}.
custom format - дополнительное форматирование. По аналогии с выражением в {f:…} и {t:…}.

Плейсхолдеры `{info:...}` и `{tinfo:...}`¶

Аналогичны плейсхолдерам {f:…} и {t:…} (соответственно), но позволяют отобразить данные из переданной в контекст обработки плейсхолдеров дополнительной информации.

Пример:

{tinfo:Ключ1.Ключ2.Ключ3 top 5 order by Ключ4 desc, Ключ5 format as (* [$LocalizedString]: [0]) separate by (;\n) utc trim:custom format}

Ключ1.Ключ2.Ключ3 - определяет путь в переданном Info к требуемой информации. При использовании плейсхолдера {tinfo:...} по одному из ключей должен быть передан список объектов. При использовании {info:...}, аналогично плейсхолдеру {f:…}, можно использовать несколько таблиц, например Ключ1.Ключ2.Ключ3->Секция1.Поле1.
top N - указываем, что требуется выбрать не больше, чем заданное количество строк из результатов. Например, top 10 для вывода первых десяти или top 1 для вывода первой строки (независимо от их количества).
order by Ключ4 desc, Ключ5 - указание сортировки, которая выполняется при запросе данных из Info. В качестве ключей следует указывать ключ относительно пути до элемента списка. Например, если список хранится по пути Ключ1.Ключ2, то значение для сортировки берется Ключ1.Ключ2.Ключ4. Если указано несколько ключей, то выполняется сначала сортировка по первому ключу, затем по второму. Необязательное слово desc указывает, что сортировка выполняется по убыванию, а asc - по возрастанию (по умолчанию).
format as (format string) - указывает, что каждое значение при выводе должно быть дополнительно отформатировано с учётом строки формата format string. Строка формата соответствует такой строке в стандартном выражении String.Format в .NET, где вместо фигурных скобок участвуют квадратные. В такой строке могут быть встроенные строки локализации.

Например, format as (* [$LocalizedString]: [0]) аналогично вызову String.Format("* {$LocalizedString}: {0}", value), где подстрока {$LocalizedString} будет заменена на строку локализации, а {0} - это позиция для выводимого значения value. Символы \n соответствуют переводу строки.
separate by (separator string) - определяет формат строки-разделителя separator string между несколькими значениями в пределах одной группы (для плейсхолдера {f:…} это будут любые несколько значений). По умолчанию используется разделитель “; “, т.е. “точка с запятой и пробел”. Символы \n соответствуют переводу строки. Разделитель ;\n означает, что между значениями будут вставлены точка с запятой и перевод строки. Например:

Иванов И.И.;

Петров П.П.;

Сидоров С.С.
utc - если значение, возвращаемое плейсхолдером, является датой (соответствует типам SQL: Date, DateTime, DateTime2), то оно выводится без приведения к локальному времени пользователя, который генерирует документ по шаблону. При выводе дат по умолчанию выводятся дата и время, приведённые к локальному времени, для типов SQL DateTime и DateTime2. Указание utc позволяет не выполнять корректировку времени в соответствии с часовым поясом пользователя. Тип данных SQL Date по умолчанию выводится, как только дата (без времени), при этом не выполняется приведение к локальному времени, т.е. настройка utc работает по умолчанию и игнорируется при явном указании.
trim - после окончательного формирования строки, которая заменяет плейсхолдер, удаляются начальные и конечные символы пробелов, табуляций и переводов строк (в соответствии с определением таких символов в таблицах Unicode). Например, из строки Иванов И.И.; Петров П.П. будет удалён конечный пробел.
custom format - дополнительное форматирование, выводимое в конце выражения плейсхолдера после двоеточия. Например, для вывода типа SQL DateTime как дата и время без секунд, можно использовать строку g, что аналогично dd.MM.yyyy HH\:mm. Разделитель между часами и минутами выводится с эскейп-символом \:. Если нужен символ \, то его следует задвоить \\. Указанное значение аналогично использованию форматирования типов данных .NET через IFormattable.ToString(), в этом примере: dateTimeValue.ToString("g", LocalizationManager.CurrentCulture).

Плейсхолдер-объявление `{⁠#alias` `placeholder}`¶

Особый тип плейсхолдеров, который состоит из двух частей:

alias - уникальное имя, по которому к данному объявлению можно будет обращаться из других плейсхолдеров.
placeholder - любой другой плейсхолдер, кроме плейсхолдера-объявления и плейсхолдера {n}. Само значение плейсхолдера рассчитывается только в момент обращения к нему.

Указанный placeholder может быть как табличным плейсхолдером (плейсхолдеры {t}, {tv} и т.д.), так и строковым плейсхолдером (плейсхолдеры {f}, {fv} и т.д.). Если данный плейсхолдер является табличным, то в качестве поля таблицы или имени колонки представления, откуда берутся данные, в этом табличном плейсхолдере ставится символ “*”. Строковые плейсхолдеры пишутся без изменений.

Примеры:

{⁠#Partner f:DocumentCommonInfo.PartnerID}
{⁠#Performers t:Performers.UserID->PersonalRoles.*}
{⁠#LinkedDocs tv:LinkedDocuments.* with param LinkedDocID}

Данное объявление используется для объявления основы для табличных плейсхолдеров. Например, можно объявить плейсхолдер:

{⁠#Reports t:ProtocolReports.* top 5 order by Order}

, а внутри самой таблицы для всех табличных плейсхолдеров уже использовать данную основу плейсхолдера по его алиасу:

{t:Reports.Subject}
{t:Reports.PersonName}
{t:Reports.PersonID->PersonalRoles.Email}

При этом каждому плейсхолдеру {t} внутри таблицы будут подставлены все настройки плейсхолдера из алиаса (в данном примере - top 5 order by Order).

Другой способ использования данного типа плейсхолдеров - это использование в качестве значения параметра для плейсхолдеров {fv} и {tv}. Более подробно про данный способ использования алиаса смотрите в разделе Плейсхолдеры {fv:…} и {tv:…}.

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

Плейсхолдеры `{n}`, `{0n}`, `{00n}` и др.¶

При использовании в строке таблицы (или в элементе списка) данный плейсхолдер выводит номер строки. Это удобно для вывода номера строки отдельной колонкой.

Example

{n} - {t:OutgoingRefDocs.DocDescription order by Order}

Выведет информацию по ссылкам на другие документы с указанием номера каждой ссылки:

- Дпр-0003
- И-0002

Указание {00n} дописывает нули до определённой длины, т.е. номер “5” выводит как “005”.

Дополнительные плейсхолдеры¶

Дополнительные плейсхолдеры в основном используются в шаблонах файлов, но также могут быть использованы и при формировании номера:

Плейсхолдеры для вывода текущей даты/времени:
- {date} - заменяется на текущую дату/время. В параметрах плейсхолдера можно указать формат отображения, например: {date:dd/MM/yyyy}.
- {yyyy} - заменяется на четырехзначное указание года, например 2018.
- {yy} - заменяется на двухзначное указание года, например 17.
- {M} - заменяется на числовое обозначение текущего месяца, например 6.
- {MM} - заменяется на числовое обозначение текущего месяца, например 06.
- {MMM} - заменяется на текстовое обозначение текущего месяца (3 символа), например Jun.
- {MMMM} - заменяется на текстовое обозначение текущего месяца, например June.
- {dd} - заменяется на обозначение текущего дня, например 03.
- {d} - заменяется на обозначение текущего дня, например 3.
  
  Например, плейсхолдеры {dd}.{MM}.{yyyy} заменятся на текущую дату в формате 28.03.2018.
{cardDigest} - заменяется на дайджест текущей карточки.
{$LocalizationString} - такой плейсхолдер заменяется на строку с алиасом LocalizationString, локализованную для языка текущего пользователя.

Например, строка {$ApprovalHistory_Header} заменяется на “Approval history” для англоязычных пользователей и на “Лист согласования” для русскоязычных пользователей.
{userID} - заменяется на идентификатор текущего пользователя (выполняющего генерацию файла по шаблону), например: ffe132a8-23fc-4a5b-ac75-70e0b7854c59.
{userName} - заменяется на имя текущего пользователя, например: Иванов И.И.
{serverCode} - заменяется на текущий код сервера (полезно при формировании ссылок tessa://), например: prod.
{instanceName} - заменяется на текущее имя экземпляра сервера (полезно при формировании ссылок tessa://), например: tessa. Зарезервировано для будущих нужд, не рекомендуется использовать.
{sessionID} - заменяется на идентификатор текущей сессии, например: dde132a8-23fc-4a5b-ac75-70e0b7854c59.
{cardID} - заменяется на идентификатор карточки (для которой генерируется файл по шаблону), например: 12d8cf28-9902-4dfd-8cbc-0f8a4d994691.
{cardLink} - заменяется на ссылку tessa:// на открытие текущей карточки, например: tessa://tessaclient.prod?Action=OpenCard&ID=12d8cf28-9902-4dfd-8cbc-0f8a4d994691&Name=Карточка.

Note

Ссылка будет сформирована, только если явно не отключено её формирование при помощи флага Отключить ссылки на desktop-клиент для уведомлений и виртуальных файлов в карточке Настройки сервера.
{webCardLink} - аналогично {cardLink}, только заменяется на ссылку для открытия карточки в легком клиенте.

Note

Ссылка будет сформирована, только если в карточке Настройки сервера заполнено поле Базовый адрес web-клиента.
{webAddress} - заменяется на ссылку на базовый адрес веб-клиента с завершающим слешем, т.е. на https://address.org/tessa/web/.

Данный плейсхолдер, например, можно комбинировать в документе HTML, чтобы дать ссылку на узел дерева в рабочем месте по идентификатору узла:

<a href="{webAddress}views/ef0523b2-7fad-45d4-a44d-cac7ea392ced">Ссылка на узел дерева "Мои задания"</a>

Идентификатор узла можно узнать в Tessa Admin: вкладка -> Рабочие места -> выбрать нужный узел в дереве и в свойствах в параметре Id скопировать идентификатор выбранного узла.

Note

Возвращается значение поля Базовый адрес web-клиента из карточки Настройки сервера.
{appLink} и {webAppLink} - заменяются на ссылку на приложение (толстый и лёгкий клиенты соответственно). Используются, например, для отправки уведомления на почту сотрудникам с информацией об окончании срока действия пароля.
{passwordExpires} - генерируется из карточки сотрудника, заменяется на срок окончания действия пароля у сотрудника. Срок вычисляется следующим образом: Дата и время последнего изменения пароля в карточке сотрудника + Срок действия пароля, дни в карточке Настройки сервера. Используется для отправки уведомления на почту сотрудникам с информацией об окончании срока действия пароля.
{link:Action} - заменяется на ссылку tessa:// с указанием действия (по умолчанию OpenCard для открытия карточки или файла), например: tessa://tessaclient.prod?Action=Parameter
{text:any text} - заменяется на текст, заданный в параметрах. Если текст содержит двоеточие, то плейсхолдер следует завершить на двоеточии, например: {text:some text: other text:}

Экранирование плейсхолдеров¶

Для того, чтобы плейсхолдер не был обработан и заменён, т.е. остался в первоначальном виде, существует возможность его экранировать в тексте с помощью символа обратной косой черты \, поставив данный символ непосредственно перед открывающей фигурной скобкой плейсхолдера.

В таком случае текст вида \{f:table.field} преобразуется в {f:table.field}.

Example

Исходный текст.

Чтобы отобразить текущий год ("{yyyy}"), можно использовать плейсхолдер вида \{yyyy}.

Результат после обработки плейсхолдеров.

Чтобы отобразить текущий год ("2023"), можно использовать плейсхолдер вида {yyyy}.

Также можно экранировать символы { и } внутри плейсхолдеров.

Example

{f:Section.Field:#format(\{some_format_in_cursive_braces\})}

В этом примере подстрока \{some_format_in_cursive_braces\} не будет обработана как плейсхолдер, в данном случае плейсхолдером будет являться вся строка целиком, обёрнутая во внешние фигурные скобки.

Important

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

Example

Пример некорректного экранирования вложенного участка текста, обёрнутого в фигурные скобки.

{f:Section.Field:#format(\{some_format_in_cursive_braces})}

В примере выше плейсхолдером будет являться подстрока {f:Section.Field:#format(\{some_format_in_cursive_braces}, а оставшиеся символы )} будут считаться не относящимися к плейсхолдеру.

Шаблонизация текста¶

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

В данный момент система поддерживает использование скриптов совместно с плейсхолдерами в следующих местах:

Шаблоны файлов - для текстовых и html документов;
Уведомления - тема и текст уведомления в карточке Уведомления;
Конструктор процессов - настройки действий Уведомление, Добавить файл по шаблону, Задание, Группа заданий.

Все скрипты в тексте имеют доступ к следующему набору параметров:

context - контекст выполнения скриптов, реализующий интерфейс IPlaceholderScriptContext. Общий для всех выполняемых в рамках обработки текста скриптов.
textBuilder - объект типа StringBuilder, в который записывается итоговый текст. Уникальный для каждой группы или строки.

Система поддерживает следующие конструкции для вставки скриптов в текст:

<# ... #> - вставка скрипта в текст.

Пример, когда вставка части текста выполняется только при определенном условии.

Приветствую, <# if (context.Session.User.IsAdministrator()) { #>многоуважаемый, <# } #> {userName}.

Другой пример с использованием циклов.

Приветствую: <# foreach (Dictionary<string, object> item in context.Info.Get<List<object>>("Items")) 
{ #>
многоуважаемый, <# textBuilder.Append(item["Name"]); #> 
<# } #>.

<#= ... #> - вставка результата выражения в итоговый текст.

Аналогичный пример со вставкой через условие, но только через выражение.

Приветствую, <#= context.Session.User.IsAdministrator() ? "многоуважаемый, " : string.Empty #> {userName}.

+<## ... ##>+ и +<##= ... ##>+ - конструкции, аналогичные описанным выше, но их скрипты выполняются только при инициализации таблицы (см. Обработка таблиц), во всех остальных ситуациях данный скрипт игнорируется.

Важной особенностью данного функционала является то, что для строк и групп с плейсхолдерами (обрамлены в <_row>… и <_group>…</_group> соответственно) скрипты генерируются отдельно и вызываются при генерации каждой отдельной строки или группы. Это позволяет, в свою очередь, видоизменять каждую строку и группу таблицы по отдельности.

Обработка таблиц¶

В данном пункте речь идет о таблицах с табличными плейсхолдерами, которые обрамлены в <_row>…</_row> и <_group>…</_group> конструкции.

При наличии внутри таблицы скриптов, система генерирует для нее 2 скрипта:

Скрипт инициализации таблицы
Скрипт генерации строки/группы

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

При формировании данного скрипта все конструкции вида +<# ... #>+ и +<#= ... #>+ игнорируются, как будто их вообще и нет в текста. Вместо них используются конструкции +<## ... ##>+ и +<##= ... ##>+ для написания скриптов.

Однако, в большинстве случаев в этом нет необходимости, т.к. система получит плейсхолдеры из самого текста таблицы. Данные скрипты могут быть полезны в ситуациях, когда плейсхолдеры для строк генерируются скриптами (внутри +<# ... #>+ или +<#= ... #>+) или если есть желание или необходимость выделить первый плейсхолдер для расчёта сортировок, группировок и т.д. в отдельный плейсхолдер, результат которого выводиться не должен.

Пример:

Таблица:
<_row><##= "{t:Секция1.Поле1 top 5 Секция1.Поле3 order by Секция1.Поле4 desc, Секция2.Поле6}" 
##>
    {t:Секция1.Поле6} 
    <# if {условие) { #>{t:Секция1.Поле8}<# } else { #>{t:Секция1.Поле7\->Секция2.Поле8}<# } #>
</_row>

Скрипт генерации строки/группы вызывается каждый раз при генерации строки или группы соответственно. Данный скрипт возвращает текст, сгенерированный с учетом скриптов внутри данной строки или группы. В данном тексте могут быть новые табличные плейсхолдеры, расчёт которых произведется после генерации текста строки (но до замены плейсхолдеров в таблице).

С помощью данного скрипта можно видоизменить строку, подменить одну строку на другую внутри группы или полностью исключить определенную строку из результата.

Пример, в зависимости от условия внутри группы будет использоваться одна или другая строка:

Таблица:
<_group>
    {t:Секция1.Поле1}
    <# if (условие_на_проверку_типа_строки) { #>
    <_row>
        {t:Секция1.Поле1} | {t:Секция1.Поле2}
    </_row>
    <# } else { #>
    <_row>
        Дополнительный текст в данной строке: {t:Секция1.Поле3} | {t:Секция1.Поле4}
    </_row>
<# } #>
</_group>

Пример, убираем всю строку, если условие не выполнено:

Таблица:
<_row><# if (необходимое_условие_для_строки) { #>
    {t:Секция1.Поле6}
    <# if {условие) { #>{t:Секция1.Поле8}<# } else { #>{t:Секция1.Поле7\->Секция2.Поле8}<# } #>
<# } #></_row>

Особенности шаблонных файлов для представлений¶

В шаблоне файла для представления в плейсхолдерах {fv:...} и {tv:...} можно не указывать алиас представления, т.к. это будет выбранное представление (т.е. представление, из которого формируется файл по шаблону). При этом, при формировании файла по шаблону, будет учитываться предварительно настроенная фильтрация в представлении.

В случае, если мы указываем представление в плейсхолдере {fv:...} или {tv:...} (т.е. плейсхолдеры заданы для одного представления, а формироваться файл по шаблону будет из другого представления), то данное представление будет выгружено без учета параметров (т.е. без учета фильтрации в представлении). Данный функционал (выгрузка представления с учетом фильтрации), при необходимости, можно реализовать с помощью дополнительных расширений.

Любые скаляры (т.е. плейсхолдеры, которые возвращают одно значение, см. Плейсхолдеры) также можно использовать в шаблонных файлах для представлений. Плейсхолдеры {f:...}, {t:...} будут выполнены в контексте карточки текущего сотрудника, то есть {f:PersonalRoles.Name} - вернет имя текущего сотрудника. Для плейсхолдеров {fv:...} и {tv:...} в параметр, указанный в with param, передается идентификатор текущего пользователя.

Примеры создания шаблонов файлов в формате docx¶

Пример docx шаблонного файла, в котором указаны плейсхолдеры, представлен на рисунке ниже (слева). Сформированный из карточки входящего документа по данному шаблону файл представлен на рисунке справа:

В docx шаблонных файлах может использоваться плейсхолдер {t:...} для вывода значений в таблицу, в виде списка или нумерованного списка.

Рассмотрим конкретные примеры:

Пример вывода данных в виде нумерованного списка:

Выведем список карточек, на которые ссылается текущая карточка, с указанием после запятой автора карточки.

В файле docx добавим строку: {t:OutgoingRefDocs.DocID->DocumentCommonInfo.FullNumber}, автор {t:OutgoingRefDocs.DocID->DocumentCommonInfo.AuthorName}

Далее преобразуем данную строку в нумерованный список:

При формировании файла по данному шаблону из карточки исходящего документа для каждой строки результата будет добавлена строка с очередным номером и заданным содержимым:
Аналогично можно вывести данные в виде списка:
Следующий пример - выведем те же данные, но в виде таблицы:

Добавим в docx документ новую таблицу с тремя колонками.

В первой строке таблицы указываем название колонок: №, Карточка, Автор. Во второй строке таблицы указываем плейсхолдеры:
Example
- {n} - порядковый номер записи;
- {t:OutgoingRefDocs.DocID->DocumentCommonInfo.FullNumber} - номер карточки;
- {t:OutgoingRefDocs.DocID->DocumentCommonInfo.AuthorName} - автор карточки.
При формировании файла по данному шаблону из карточки исходящего документа для каждой строки результата в таблицу будет добавлена новая строка с очередным заданным содержимым:
Еще один способ - использовать механизм закладок или примечаний в Word для выделения нужной области в качестве строки, группы или таблицы. С помощью имени закладки или текста примечания система поймет, к какому типу группы необходимо определить данную область.

Note

Для определения именованной группы с помощью примечания текст примечания должен начинаться с символа #. Например, #r_AreaName.

Область группы, которую система определяет по выделенной области закладки или примечания, определяется по следующему правилу:
- Если выделенная область находится целиком внутри одного параграфа, то областью группы (и набором элементов, которые будут копироваться при добавлении каждой новой строки) будут являться только те элементы, которые находятся внутри неё, и они будут скопированы внутрь данного параграфа при добавлении новых строк.
- Если выделенная область находится целиком внутри параграфа, но ее окончание включает переход между параграфами, то в качестве области группы будет определен весь текущий параграф. Для каждой новой строки будет добавлен новый параграф. Отличить, включает ли в себя закладка или примечание переход между параграфами можно визуально.
- Если выделенная область находится внутри нескольких параграфов или других элементов (ячейках, строках, таблицах), то система определяет в качестве области все элементы целиком, вне зависимости от того, где конкретно начинается или заканчивается выделенная область.
  
  Note
  
  Если выделенная область включает в себя целиком одну или несколько ячеек строки, то при генерации новых строк копируется вся строка. Для областей, определяющих группу или строку таблицы, помимо выделенной строки также копируются все строки ниже.

Выделяют следующие типы групп, в зависимости от имени закладки или текста примечания:

r_AreaName

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

Пример простого использования:

Сделаем перечисление внутри параграфа, где заданы алиасы плейсхолдеров (см. Алиасы плейсхолдеров), указав закладку на внутренние элементы параграфа r_Decided:

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

Пример использования вложенных t_AreaName:

Сделаем простой шаблон файла, который из представления Мои документы сразу бы выводил по каждому документу его связанные документы.

Для строк, выделенных синим, создаем закладку r_Main, для строк, выделенных зеленым, создаем закладку t_Sub, для строки, выделенной красным, создаем закладку r_Sub.

В примере также используются плейсхолдеры-объявления, с помощью которых мы указываем, что по алиасу Main у нас будут браться данные для внешней таблицы из представления Мои документы (имя представления не указывается, т.к. шаблон файла строится именно по этому представлению), а по алиасу Sub у нас будут браться данные для вложенной таблицы из представления Связанные документы, и при этом для получения данных из этого представления в качестве параметра LinkedDocID будет передаваться значение из колонки DocID из строки основной таблицы.

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

Таким образом, из этих данных:

Можно получить следующий результат:

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

Группировка строк по параметру. Внутри диапазона ячеек с группировкой может содержаться диапазон с именем r_AreaName, g_AreaName (для создания многоуровневой группировки) или t_AreaName (для создания вложенной таблицы).

Пример использования g_AreaName с вложенным r_AreaName:

Перенесем шаблон Мои задания на docx. В качестве строки выделим строку, отмеченную синим, и создадим закладку r_Task, а в качестве группы выделим две строки таблицы, выделенные красным, и создадим закладку g_TaskGroup.

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

Пример использования g_AreaName с вложенным g_AreaName2:

Модифицируем первый пример, перенесём состояние задания в отдельную строку. Выделим все три строки таблицы, обведенные синим цветом, и сделаем для них закладку g_TasksByType, далее выделим две нижние строки, обведенные зеленым цветом, и сделаем для них закладку g_TasksByState, а затем выделим строку, обведенную красным цветом, и сделаем закладку r_Tasks.

Система определит области группировки и их положение относительно друг друга (что одна содержит вторую, а вторая содержит внутри область строк), и для каждой из них определяет плейсхолдеры, по которым должна производиться группировка. В результате получим:

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

Использование области t_AreaName в области g_AreaName идентично использованию области t_AreaName в области r_AreaName, и также допускает использование одновременно несколько областей таблиц внутри себя.
t_AreaName

Определяет таблицу. Внутри области данной группы должна содержаться другая закладка/примечание с именем r_AreaName или g_AreaName. Если внутри сгенерированной таблицы не будет ни одной строки, то все объекты внутри данной области будут удалены из документа.

Пример: обрамляем диапазон r_Decided в новый диапазон t_DecidedTable.

В ситуации, когда внутри r_Decided не было найдено ни одной строки по заданным плейсхолдерам, удаляются все элементы из области группы t_DecidedTable.

AreaName - любое уникальное имя в рассмотренных выше типах групп.

Для указания в файле по шаблону ссылок, например, на связанные карточки, необходимо в Word файле шаблона указать гиперссылку:

В поле Адрес указывается ссылка в следующем виде: https://tessalink/?link=ссылка_с_плейсхолдерами, т.е. в нашем примере в качестве гиперссылки указываем https://tessalink/?link=tessa://tessaclient.{serverCode}?Action=OpenCard&ID={t:OutgoingRefDocs.DocID}&Name={t:OutgoingRefDocs.DocDescription}:

Далее данную ссылку необходимо сделать в виде нумерованного списка.

Note

После указания гиперссылки, если снова открыть окно редактирования гиперссылки, то в поле Адрес можно заметить, что некоторые символы автоматически заменены, например: tessa://tessaclient.%7bserverCode%7d/?... Это связано с особенностями работы Word, вносить правки в ссылку не требуется, файл по шаблону будет формироваться корректно.

На рисунках ниже представлен docx шаблонный файл (на рисунке слева) и файл, сформированный из карточки входящего документа по данному шаблону (на рисунке справа):

Аналогично можно давать ссылки на файлы и версии файлов, например, на лист согласования текущего документа: tessa://tessaclient.{serverCode}?Action=OpenCard&ID={f:DocumentCommonInfo.ID}&Name={f:DocumentCommonInfo.FullNumber}&FID=fd70bd20-ba8c-420f-9fc7-55c6c8898235&VID=bb68360d-7690-4163-b985-a0a88abe5f21.

Описание плейсхолдеров можно посмотреть в разделе Плейсхолдеры.

Примеры настроенных docx шаблонов можно посмотреть в представлении Шаблоны файлов (в представлении Администратор -> Шаблоны и уведомления):

Протокол совещания - шаблонный файл используется для формирования протокола совещания из карточки Протокол.

Блоки с условиями в шаблонах файлов в формате docx¶

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

Чтобы создать такой блок, нужно выделить часть документа, на которую планируется повесить условие отображения, и добавить примечание с текстом вида:

#if <выражение>

где <выражение> – это простое условие на языке C#, возвращающее true или false, в котором можно сравнивать поля карточки, для которой генерируется шаблон файла.

Система определяет такие примечания как блоки с условием и при обработке шаблонов файлов, и при генерации шаблона файлов проверяет условия, и если они не выполнены - такие блоки удаляются из документа.

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

Note

Сами примечания с условиями удаляются из документа вне зависимости от того, выполнено ли в них условие или нет.

Note

Блоки с условиями можно вкладывать друг в друга. Тогда внутренний блок будет отображён не только при успешном выполнении своего условия, но и при успешном выполнении условия наружного блока.

Important

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

Система выражений строго ограничивает возможности по написанию скриптов. В ней доступны все стандартные типы данных языка C# (DateTime, int, decimal, string, bool и т.д.), однако недоступны никакие статические методы и свойства, никакие объекты системы и платформы. Для применения доступны только данные текущей карточки и параметры, добавляемые разработчиками в расширениях системы выражений. С расширениями системы выражений можно ознакомиться в руководстве разработчика.

По умолчанию в платформе в качестве параметров выражения можно использовать:

имя поля любой строковой секции карточки;

Example

Например, чтобы получить сумму договора, которая хранится в секции DocumentCommonInfo в поле Amount, можно использовать переменную Amount.

Important

Если у двух строковых секций карточки есть поля с одинаковым именем, то система в качестве значения будет использовать одно из них, при этом порядок явным образом не определён.
константу d для доступа к строковой секции карточки и к её полям;

Example

Например, чтобы получить сумму договора, которая хранится в секции DocumentCommonInfo в поле Amount, можно написать d.DocumentCommonInfo.Amount.
константу t для доступа к табличной секции карточки и к её строкам;

Example

Например, чтобы получить имя первого исполнителя договора, которое хранится в секции Performers в поле UserName, можно написать t.Performers[0].UserName.
метод GetPlaceholderValue, с помощью вызова которого можно получить значение плейсхолдера. Если плейсхолдер возвращает несколько значений, то метод вернёт первое из них;

Example

Например, чтобы получить значение плейсхолдера f:DocumentCommonInfo.Amount, определяющего сумму документа, нужно написать GetPlaceholderValue("f:DocumentCommonInfo.Amount")

Important

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

Example

Например, чтобы получить все значения плейсхолдера f:Performers.UserID, определяющего список идентификаторов сотрудникоов из поля “Исполнители” документа, нужно написать GetPlaceholderValues("f:Performers.UserID")

Important

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

Примеры создания шаблонов файлов в формате html¶

Пример html шаблонного файла, в котором указаны плейсхолдеры представлен на рисунке ниже (слева). Сформированный из карточки входящего документа по данному шаблону файл представлен на рисунке справа:

Для вывода данных построчно (например, список заданий в Листе согласования) используется специальный тэг <_row>…{t:…}…{t:…}…</_row>. Всё содержимое внутри тэга дублируется для каждой строки, которая получена от плейсхолдеров внутри строки в результате выполнения запроса SQL. На рисунке ниже представлен пример части html кода (слева) и сформированный по шаблону файл (справа):

Html шаблоны также могут использоваться для выгрузки представлений. Для вывода данных построчно используется тот же тег <_row>, внутри которого содержатся нужные плейсхолдеры.

Также можно поместить всю таблицу целиком в тег <_table>…</_table>. Тогда в ситуации, когда табличные плейсхолдеры во внутреннем теге <_row> или <_group> не возвращают ни одной строки, то весь текст, заключенный в тег <_table>, будет удален.

Примеры настроенных html шаблонов можно посмотреть в представлении Шаблоны файлов (в представлении Администратор -> Шаблоны и уведомления):

Лист согласования - шаблонный файл может использоваться для карточек документов, у которых используется типовой процесс маршрутов.
Мои задания - шаблонный файл используется для выгрузки данных из представления Мои задания.

Группировка в шаблонных файлах формата html¶

Также в html доступен тег для группировки данных в таблице - <_group>, внутри которого может быть один тэг <_row> или <_group> (для множественных группировок), и любое количество тэгов <_table> (для вложенных таблиц). Любые плейсхолдеры, входящие в <_group> и не входящие во внутренние тэги, считаются группирующими. Т.е. группировка происходит по всем плейсхолдерам ({t:...} или {tv:...}), которые используются в области группы. Они объединяются в строку и по ней производится группировка. В области группы также могут быть еще любые плейсхолдеры, которые возвращают скаляры (т.е. одну строку).

Параметр для плейсхолдера is group может использоваться только в области строки (<_row>), но вне области группировки. Этот параметр переносит значение на верхний уровень группировки.

На рисунке ниже представлена часть кода html страницы, которая должна выводить список заданий (из представления Мои задания). Группировка производится по колонке Тип задания (плейсхолдер {tv:TypeCaption}). В колонках таблицы должна отображаться информация: состояние задания, роль, информация по заданию, выполнить к (плановая дата/время завершения задания), до завершения (срок до завершения задания), карточка (ссылка на карточку документа, отображается номер карточки):

При формировании из представления Мои задания файла по шаблону Мои задания результирующий документ будет выглядеть следующим образом:

Многоуровневая группировка в шаблонных файлах формата html¶

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

При формировании из представления Мои задания файла по шаблону Мои задания результирующий документ будет выглядеть следующим образом:

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

Вложенные таблицы в шаблонных файлах формата html¶

Внутрь тэгов <_row> и <_group> можно поместить один или несколько тегов <_table> для генерации вложенных таблиц внутри каждой строки или группы таблицы. У каждой строки вложенной таблицы также могут быть вложенные таблицы.

Рассмотрим пример создания html шаблона с вложенной таблицей. Сделаем простой шаблон файла, который из представления Мои документы сразу бы выводил по каждому документу его связанные документы.

С помощью использования вложенного тэга <_table> мы для каждой строки основной таблицы выводим свою подтаблицу со связанными документами. При этом, если вложенная таблица будет без строк, то для данной строки будет удален весь тэг <_table> целиком.

В примере также используются плейсхолдеры-объявления, с помощью которых мы указываем, что по алиасу Main у нас будут браться данные для внешней таблицы из представления Мои документы (имя представления не указывается, т.к. шаблон файла строится именно по этому представлению), а по алиасу Sub у нас будут браться данные для вложенной таблицы из представления Связанные документы, и при этом для получения данных из этого представления в качестве параметра LinkedDocID будет передаваться значение из колонки DocID из строки основной таблицы.

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

Таким образом, из этих данных:

Можно получить следующий результат:

Описание плейсхолдеров можно посмотреть в разделе Плейсхолдеры.

Примеры создания шаблонов файлов в формате txt¶

Пример txt шаблонного файла, в котором указаны плейсхолдеры представлен на рисунке ниже (слева). Сформированный из карточки договора по данному шаблону файл представлен на рисунке справа:

В txt шаблонных файлах для построчного вывода и группировки данных используются те же теги, что и для html: <_row>, <_group> и <_table>. На рисунке выше пример, где построчно выведена информация из секции Ссылки. Используемый в примере форматтер #wrap описан далее.

Txt шаблоны также могут использоваться для выгрузки представлений.

Примеры создания шаблонов файлов в формате xlsx¶

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

r_AreaName

При добавлении новых строк они добавляются путем копирования и вставки новых строк.

Пример: в таблице строка 31, где заданы алиасы плейсхолдеров (см. Алиасы плейсхолдеров), указан диапазон ячеек с именем r_Decided:

В результирующем файле в таблицу путем копирования и вставки новых строк добавлены все записи из карточки протокола:

В данном диапазоне может находиться неограниченное количество диапазонов t_AreaName. Каждый из них будет определять отдельную вложенную таблицу, которая формируется отдельно для каждой строки диапазона r_AreaName.
j_AreaName

При добавлении новых строк они добавляются путем заполнения существующих строк.

Пример: для двух таблиц в строках 12-13, где заданы алиасы плейсхолдеров (см. Алиасы плейсхолдеров), указаны диапазоны ячеек с именами соответственно j_Participants и j_Reports:

В результирующем файле в каждую таблицу путем заполнения существующих строк добавлены все записи из карточки протокола:
g_AreaName

Группировка строк по параметру. Внутри диапазона ячеек с группировкой может содержаться один диапазон вида r_AreaName, g_AreaName (для многоуровневых группировок) или j_AreaName. Также внутри данного диапазона может находиться неограниченное количество диапазонов t_AreaName. Каждый из них будет определять отдельную вложенную таблицу, которая формируется отдельно для каждой строки диапазона g_AreaName.

Примеры можно посмотреть далее, в разделах Группировка в шаблонных файлах формата xslx, Многоуровневая группировка в шаблонных файлах формата xslx и Вложенные таблицы в шаблонных файлах формата xslx.
t_AreaName

Определяет таблицу. Внутри диапазона ячеек должен содержаться диапазон с именем r_AreaName, j_AreaName или g_AreaName. Если внутри сгенерированной таблицы не будет ни одной строки, то все строки, в которых располагается диапазон t_AreaName будут удалены из документа.

Пример: обрамляем диапазон r_Decided в новый диапазон t_DecidedTable.

В ситуации, когда внутри r_Decided не было найдено ни одной строки по заданным плейсхолдерам, удаляются все строки диапазона t_DecidedTable, в том числе и заголовок.

AreaName - любое уникальное имя диапазона ячеек.

Для указания имени диапазона ячеек необходимо сначала выделить нужные ячейки и после указать имя:

Диспетчер имен (окно для просмотра, редактирования, удаления имен диапазонов) можно открыть, нажав в Excel сочетание клавиш Ctrl + F3:

Более подробно о настройке xslx шаблонного файла описано далее.

Примеры настроенных xslx шаблонов можно посмотреть в представлении Шаблоны файлов (в представлении Администратор -> Шаблоны и уведомления):

Мои задания (Excel) - шаблонный файл используется для выгрузки данных из представления Мои задания;
Протокол совещания (Excel) - шаблонный файл используется для формирования протокола совещания из карточки Протокол.

Группировка в шаблонных файлах формата xslx¶

Группировка происходит по всем плейсхолдерам ({t:...} или {tv:...}), которые используются в области группы. Они объединяются в строку и по ней производится группировка. В области группы также могут быть еще любые плейсхолдеры, которые возвращают скаляры (т.е. одну строку).

Параметр для плейсхолдера is group может использоваться только в области строки (r_AreaName или j_AreaName), но вне области группировки. Данный параметр определяет, что плейсхолдер будет использоваться на самом верхнем уровне группировки (если их несколько).

В данном разделе рассмотрим пример создания шаблонного файла в формате xlsx для представления Мои задания: вывод списка моих заданий с группировкой по одному плейсхолдеру - Тип задания.

А также в данном примере будем использовать Алиасы плейсхолдеров:

t_type          tv:TypeCaption
t_state         tv:StateName
t_role          tv:RoleName
t_result        tv:TaskInfo
t_date          tv:PlannedDate
t_completed     tv:TimeToCompletion

Формируем Excel файл, где прописываем заданные алиасы плейсхолдеров. Для колонки Карточка (ссылка на карточку) указываем ссылку в следующем формате (более подробно о плейсхолдерах в разделе Плейсхолдеры):

tessa://tessaclient.{serverCode}?Action=OpenCard&ID={tv:CardID}&Name={tv:CardName}

В данном примере будет настроена группировка по {*t_type}, т.е. типу задания.

Далее задаем имя для диапазона ячеек. Это необходимо для того, чтобы вся информация из представления записалась в таблицу построчно.

Выделяем ячейки в строке с плейсхолдерами (кроме ячейки с группировкой - {t_type}) и задаем для них имя (имя указываем с обязательным служебным префиксом r_):

Теперь зададим группировку. Необходимо выделить диапазон ячеек, включающий группировку, плюс диапазон r_Test. Для выделенного диапазона задаем имя (имя указываем с обязательным служебным префиксом g_):

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

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

В поле Адрес указывается ссылка в следующем виде: https://tessalink/?link=ссылка_с_плейсхолдерами, т.е. в нашем примере в качестве гиперссылки указываем https://tessalink/?link=tessa://tessaclient.{serverCode}?Action=OpenCard&ID={tv:CardID}&Name={tv:CardName}.

Note

После указания гиперссылки, если снова открыть окно редактирования гиперссылки, то в поле Адрес можно заметить, что некоторые символы автоматически заменены, например: tessa://tessaclient.%7bserverCode%7d/?.... Это связано с особенностями работы Excel, вносить правки в ссылку не требуется, файл по шаблону будет формироваться корректно.

Также для файлов шаблонов можно писать скрипты C#, пример доступен в руководстве разработчика.

Многоуровневая группировка в шаблонных файлах формата xslx¶

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

В выбранном шаблоне делаем область g_TasksByType на ячейках, выделенных синим цветом, область g_TasksbyState на ячейках, выделенных зеленым цветом и область r_Tasks на ячейках, выделенных красным цветом.

Для группировки значений для вернхнеуровневой группировки будут использоваться все плейсхолдеры, которые входят в область g_TasksByType, но не входят во вложенную область. Для внутренней группировки работает точно такая же логика, но уже на области g_TasksByState.

При формировании из представления Мои задания файла по шаблону Мои задания (Excel) результирующий документ будет выглядеть следующим образом:

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

Вложенные таблицы в шаблонных файлах формата xslx¶

Как было написано выше, внутрь групп r_AreaName и g_AreaName можно поместить одну или несколько групп t_AreaName для генерации вложенных таблиц внутри каждой строки или группы таблицы. У каждой строки вложенной таблицы также могут быть вложенные таблицы.

Рассмотрим пример создания xslx шаблона с вложенной таблицей. Сделаем простой шаблон файла, который из представления Мои документы сразу бы выводил по каждому документу его связанные документы.

В выбранном шаблоне делаем область r_Main на ячейках, выделенных синим цветом, область t_Sub на ячейках, выделенных зеленым цветом и область r_Sub на ячейках, выделенных красным цветом.

С помощью использования вложенной группы t_Sub мы для каждой строки основной таблицы выводим свою подтаблицу со связанными документами. При этом, если вложенная таблица будет без строк, то все строки Excel вложенной таблицы для данной строки внешней таблицы будут удалены целиком.

В примере также используются плейсхолдеры-объявления, с помощью которых мы указываем, что по алиасу Main у нас будут браться данные для внешней таблицы из представления Мои документы (имя представления не указывается, т.к. шаблон файла строится именно по этому представлению), а по алиасу Sub у нас будут браться данные для вложенной таблицы из представления Связанные документы, и при этом для получения данных из этого представления в качестве параметра LinkedDocID будет передаваться значение из колонки DocID из строки основной таблицы.

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

Таким образом из этих данных:

Можно получить следующий результат:

Описание плейсхолдеров можно посмотреть в разделе Плейсхолдеры.

Использование формул в шаблонных файлах формата xlsx¶

Система генерации файлов по шаблону поддерживает работу формул в файлах Excel при генерации файла. В эту обработку входит:

Сохранение позиции формулы в ячейке при перемещении строки с формулой в документе (при добавлении новых строк). Например, если формула была в ячейке A2, и перед этой строкой добавилось 5 новых строк (при генерации таблицы), то формула будет на строке A7.

Шаблон:

Результат:
Сохранение корректных ссылок в формуле на другие ячейки. Например, если формула находится в ячейке A3, а ссылается на ячейки B1 и C6, а в документ были добавлены 5 новых строк, начиная со строки 4, то в итоговом документе формула останется на позиции A3 (т.к. перед ней не было добавлено строк), а сама формула будет ссылаться на ячейки B1 (не изменилась, т.к. перед ней не было добавлено строк) и C11 (ячейка, на которую ссылалась формула, сместилась на 5 строк).

Шаблон:

Результат:
Клонирование формул внутри именованных групп, определяющих строки таблицы. Например, если формула находилась в группе r_AreaName, то при добавлении новых строк по этой группе, формула будет скопирована в каждую строку. При этом в формуле будут также актуализированы все ссылки, которые ссылаются на ячейки в r_AreaName. Например, если формула находится в ячейке A1, и ссылается на ячейки B1 и C1, и при этом указанная группа с табличными плейсхолдерами r_AreaName на диапазон A1:C1, то при копировании этой строки, в новой строке 2 в ячейке A2 будет формула из A1, но ссылаться она будет уже на ячейки B2 и C2.

Шаблон:

Результат:
Расширение диапазонов ссылок из формул, которые ссылаются на именованные группы r_AreaName или g_AreaName. Если формула ссылается на ячейки именованной группы, то эта ссылка будет расширяться с увеличением числа строк, генерируемых по данной именованной группе. Для того, чтобы это расширение происходило, должно быть выполнено 2 условия:
1. Ссылка из формулы должна покрывать всю высоту группы. Т.е., если группа r_AreaName занимает диапазон A1:B2, и на нее ссылаются 2 формулы, одна на диапазон A1:A2, другая на диапазон A1:B1. То при добавлении, например, 5 новых строк по этой именованной группе, первая формула будет ссылаться на диапазон A1:A12 (т.к. добавлено 10 строк), а вторая формула на диапазон A1:B1 (не был расширен).
  
  Шаблон, зеленым выделена правильная настройка, красным неправильная:
  
  Результат:
2. Формула должна находиться или вне именованных групп, или в именованной группе, отличной от той, на которую ведет ссылка из формулы.
Удаление некорректных формул, которые ссылаются на удаленные данные. Например, если формула ссылается на некую ячейку, которая находится в группе t_AreaName и при генерации файла, эта группа была удалена, то формула, которая ссылается на эту ячейку, также будет удалена.

Шаблон:

Результат:

Рассмотрим пример использования формул. Для этого модифицируем шаблон файла Мои задания (Excel).

Добавим в ячейку A5, где у нас выводится тип задания, следующую формулу:

="{*t_type} ("&СЧЁТЗ(A6)&")"

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

Ссылка A6 покрывает всю высоту группы r_Tasks (выделена зеленым).
Формула находится в группе g_TasksByType (выделена красным), которая является родительской по отношению к группе r_Tasks (выделена зеленым), на ячейки которой она ссылается.

Построив файл по данному шаблону, можно убедиться в результате:

Форматтеры и вставка изображений в плейсхолдеры¶

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

Форматтеры выводятся вместо стандартного форматирования после двоеточия (см. примеры ниже).

Также форматтеры можно объединять в цепочки, разделяя их через точку с запятой. Подробное описание цепочек форматтеров и примеры см. в разделе Цепочки форматтеров.

Список доступных форматтеров с их кратким описанием представлен в таблице (а также ссылки на соответствующие разделы с подробным описанием форматтера):

Форматтер	Описание
`#image`	Форматтер изображения - на входе получает массив байт, например, из поля в базе данных, и на выходе формирует его как изображение
`#barcode`	Получает строку текста и вставляет её как штрих-код указанного формата
`#qrcode`	Получает строку текста и вставляет её как QR-код указанного формата
`#format`	Применяется для форматирования полученного текста, например, даты (аналогично форматированию в плейсхолдерах)
`#align`	Применяется для выравнивания полученного текста
`#wrap`	Применяется для выравнивания полученного текста c переносом на следующую строку, если размер превышает допустимый предел
`#file`	Форматтер загружает заданный файл или версию файла по идентификатору и представляет, как массив байт, который можно направить в другие форматтеры, например, в `#image` или `#text`
`#text`	Форматтер представляет заданный массив байт как текст
`#cardLink` и `#webCardLink`	Форматтеры, преобразующие входящий `Guid` в ссылку на карточку (в толстом и легком клиенте соответственно). Пример использования см. в разделе Цепочки форматтеров. Имеют те же ограничения, что и соответстсвующие плейсхолдеры
`#noencode`	Форматтер, который предотвращает вызов Encode-методов для плейсхолдера при замене его в документе. Актуально, в частности, для `HTML` документов, для которых в форматтере можно вставлять `HTML`-разметку, которая будет вставлена именно как тэги `HTML`, а не как обычный текст
`#split_par`	Форматтер, который при замене плейсхолдера переносы строк не добавляет как переносы на новую строку в параграфе, а параграф разделяет на несколько по этим переносам строк. Форматтер применим только для документов Word

При использовании форматтеров, которые вставляют изображение (т.е. #image, #barcode, #qrcode) для шаблонов html на месте плейсхолдера при формировании документа по шаблону автоматически будет сгенерирован тэг объект <image />, содержащий бинарные данные изображения и разные параметры. Пример html шаблона см. в разделе Форматтер #barcode.

Для корректной вставки изображений в шаблоны форматов docx и xlsx необходимо в шаблоне добавить объект типа Надпись и в тексте надписи указать плейсхолдер (или алиас).

Если данные, по которым строится изображение (#image), штрих-код (#barcode) или QR-код (#qrcode) вернули “null” (в т.ч. только пробелы) или массив байт нулевого размера (из представления, базы данных, другого форматтера и т.д.), то в документе HTML тег <image/> не генерируется на месте плейсхолдера, а в документах docx и xlsx объект Надпись будет удалён.

Форматтер `#image`¶

Форматтер изображения на входе получает массив байт, например, из поля в базе данных, и на выходе формирует его как изображение.

#image(w=300;h=200;img=jpeg;alt=Image text;reformat)

Описание параметров форматтера изображения:

w - ширина изображения, если размер не указан в параметрах, то используется либо исходный, либо тот, который есть у надписи в Word/Excel.
h - высота изображения, если размер не указан в параметрах, то используется либо исходный, либо тот, который есть у надписи в Word/Excel.
img - указывается тип изображения при вставке в документ. При этом не выполняет конвертацию, а просто указывает на исходный тип картинки. По умолчанию это PNG.

Note

В HTML для всех современных браузеров и в Word/Excel изображение успешно отобразится с параметром по умолчанию, даже если его тип отличен от PNG, но если вдруг возникнут проблемы и изображение не будет отображено, то можно задать тип явно. Доступны типы (соответствующие одноимённым форматам): bmp, emf, exif, gif, icon, jpeg, png, tiff, wmf. Укажите unknown, если тип неизвестен и об этом надо явно оповестить браузер или Word/Excel.
alt - используется, чтобы задать альтернативный текст в тех случаях, когда картинка недоступна или когда её должен прочитать голосовой помощник Windows.

Может использоваться во всех типах шаблонов - html, Word, Excel. Для Word-а замещающий текст можно просмотреть, вызвав контекстное меню правой кнопкой мыши по изображению и выбрав пункт “Замещающий текст” (или выбрав “Формат рисунка” - для более старых версий Word). При включении голосового помощника вместо изображения будет зачитан указанный текст.

Замещающий текст также может содержать локализацию, например:

#qrcode(t=url;alt=$KrTypes_DocTypes_Incoming)

Если в данном параметре требуется помимо строки локализации указать какой-то текст, то необходимо записывать в следующем формате:

#qrcode(t=url;alt={$KrTypes_DocTypes_Incoming} - Ссылка на карточку)

Warning

При необходимости указания плейсхолдера с таким форматтером (который содержит в себе фигурные скобки) необходимо использовать Алиасы плейсхолдеров, иначе документ не будет формироваться корректно.
reformat - используется только в Word/Excel. Если данное свойство не указано, то при вставке изображения в объект Надпись все параметры надписи (включая рамку, обтекание текстом и соотношение сторон) будут сохранены. Если reformat указан, то параметры надписи будут сброшены, и они будут определяться исключительно указанной шириной/высотой (или же шириной/высотой исходного изображения). Для документа HTML свойство reformat игнорируется.

Перечисленные свойства применимы для всех форматтеров изображений. При вставке в HTML на месте плейсхолдера будет сгенерирован тэг объект <image />, содержащий бинарные данные изображения и разные параметры.

Для Word и Excel надо вставить объект типа Надпись и в тексте надписи указать плейсхолдер (или алиас плейсхолдера). Надпись будет заменена на объект “Рисунок” с изображением.

Example

Для примера возьмем иконку из стандартного представления Приложения (Администратор -> Служебные -> Приложения), и отобразим её в файле шаблона в виде изображения размером 300х300 пикселей.

В шаблонном документе Word создадим таблицу, в левой колонке отобразим имя приложения с помощью плейсхолдера {tv:Applications.AppName}, во второй колонке добавим две области Надпись, в каждой из которых плейсхолдер получает иконку и с помощью форматтера отображает изображение размером 300х300: {tv:Applications.Icon:#image(w=300;h=300)}.

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

Форматтер #image также может сконвертировать входящее изображение в формат png:

#image(png;...прочие параметры).

Если на входе было изображение в bmp (или любое другое), то оно будет сконвертировано в png. Если на входе уже был png, то конвертация не выполняется и изображение показывается в исходном виде. В отличие от остальных перечисленных параметров, этот работает только для форматтера #image и нужен он в случае, если изображение в исходном виде не отображается в документе, или оно занимает слишком много места (как в случае с bmp).

Форматтер `#barcode`¶

Форматтер штрих-кода получает строку текста и вставляет её как штрих-код. Штрих-код всегда выводится как изображение png.

Note

Строка, полученная от плейсхолдера, должна содержать только корректные для формата символы. Например, использование русских букв для штрих-кода будет некорректно, и оно приведёт к ошибке в момент формирования документа.

Форматтер может содержать как все вышеперечисленные параметры (описанные в разделе Форматтер #image), так и параметр t, где указывается тип штрих-кода.

Возможные типы штрих-кодов (описание типа можно найти по названию в интернете): UPCA, UPCE, UPC_SUPPLEMENTAL_2DIGIT, UPC_SUPPLEMENTAL_5DIGIT, EAN13, EAN8, Interleaved2of5, Standard2of5, Industrial2of5, CODE39, CODE39Extended, CODE39_Mod43, Codabar, PostNet, BOOKLAND, ISBN, JAN13, MSI_Mod10, MSI_2Mod10, MSI_Mod11, MSI_Mod11_Mod10, Modified_Plessey, CODE11, USD8, UCC12, UCC13, LOGMARS, CODE128, CODE128A, CODE128B, CODE128C, ITF14, CODE93, TELEPEN, FIM, PHARMACODE.

Если формат не указан, то используется формат по умолчанию - CODE128.

Example

Создадим шаблон файла для входящего документа, где будет выводиться номер документа в виде штрих-кода. В шаблоне добавляем область Надпись, где указываем плейсхолдер для получения номера карточки и форматтер для вывода штрих-кода:

{f:DocumentCommonInfo.FullNumber:#barcode(t=ean13;w=150;h=30)}

В результирующем файле мы видим сформированный штрих-код (правый рисунок):

Чтобы в Word/Excel изображение выводилось без “рамки”, можно либо использовать параметр reformat, описанный выше, либо в формате фигуры средствами Word/Excel убрать границу у надписи.

Аналогичный пример в формате html:

Может быть указан опциональный параметр l, позволяющий вывести метку с текстом штрих-кода рядом с изображением. По умолчанию метка не выводится. Текст выводится как часть изображения и вставляется соответствующим образом в документ. Если вам нужно вставить текстовое представление штрих-кода как текст, то вместо этого параметра добавьте в шаблон файла второй текстовый плейсхолдер, связанный с тем же полем.

Возможные значения параметра l (без учёта регистра): None (метка не выводится), TopLeft (метка с текстом выводится сверху слева от изображения), TopCenter (метка с текстом выводится сверху по центру от изображения), TopRight (метка с текстом выводится сверху справа от изображения), BottomLeft (метка с текстом выводится снизу слева от изображения), BottomCenter (метка с текстом выводится снизу по центру от изображения), BottomRight (метка с текстом выводится снизу справа от изображения).

Note

Для релиза TESSA 4.0 и старше, положение метки определяется автоматически, в зависимости от типа штрих-кода, обычно снизу. Укажите параметр l=none, чтобы не выводить метку, или любое другое значение, чтобы вывести её в позиции по умолчанию.

Example

Используем параметр l для вывода метки снизу по центру от графического представления:

{f:DocumentCommonInfo.FullNumber:#barcode(t=ean13;l=bottomcenter;w=150;h=30)}

Форматтер `#qrcode`¶

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

Например, может быть QR-код со ссылкой на веб-страницу (URL), телефонным номером для возможности позвонить по этому номеру или добавить его в контакт, адресом email, на который надо написать письмо, и др.

Помимо параметров, описанных в разделе Форматтер #image у данного форматтера есть еще дополнительные параметры:

t - задается тип QR-кода. Доступны следующие типы:
- Text - QR-код, вставляемый в виде текста.
- Url - QR-код, вставляемый как URL-ссылка. Если протокол не указан, то используется http://.
- Email - QR-код, вставляемый как mailto-ссылка для заданного email получателя.
- SMS - SMS-сообщение, отправляемое на заданный телефонный номер.
- MMS - MMS-сообщение, отправляемое на заданный телефонный номер.
- Phone - QR-код, вставляемый как телефонный номер.
- Skype - QR-код, вставляемый как звонок заданному пользователю Skype.
- WhatsApp - QR-код, вставляемый как WhatsApp-сообщение заданному пользователю.
  
  Если тип не указан, то используется тип по умолчанию t=Text.
ecc - определяет уровень коррекции ошибок для генерируемого QR-кода, т.е. определяет объём нечитаемой информации, при наличии которой QR-код всё равно корректно распознаётся смартфоном. Более высокий уровень означает больший размер генерируемого изображения. Доступны следующие варианты:
- L - 7% информации может быть потеряно.
- M - 15% информации может быть потеряно.
- Q - 25% информации может быть потеряно.
- H - 30% информации может быть потеряно.
  
  Если параметр не указан, по умолчанию используется ecc=Q.
utf8 - определяет факт того, что текст кодируется в UTF8 внутри QR-кода. Если флаг не указан, то используется другая кодировка, определяемая стандартном QR-кода, обычно это ISO-8859-1.

Этот параметр может влиять на считывание QR-кода некоторыми устройствами. По умолчанию не рекомендуется указывать.
bom - определяет необходимость вставки специальных символов BOM (byte order mark) в начале строки для кодирования UTF-8; используется совместно с флагом utf8.

Этот параметр может влиять на считывание QR-кода некоторыми устройствами. По умолчанию не рекомендуется указывать.
px - количество пикселей в т.н. блоке QR-кода, который влияет на размер генерируемого изображения (или на чёткость изображения при вставке в документ с явно указанными размерами).

По умолчанию значение px=2, допустимо значение “1” или больше.

Example

В шаблон файла для входящего документа добавим QR-код для звонка контактному лицу контрагента, указанного в карточке.

Для отображения QR-кода создадим область Надпись, где укажем плейсхолдер для получения номер телефона контактного лица контрагента и форматтер для вывода QR-кода типа Phone:

{f:DocumentCommonInfo.PartnerID->Partners.Phone:#qrcode(t=phone)}

В результирующем файле мы видим сформированный QR-код (правый рисунок):

Форматтер `#format`¶

Форматтер аналогичен форматированию в плейсхолдерах, т.е. {f:DocumentCommonInfo.DocDate:d} и {f:DocumentCommonInfo.DocDate:#format(f=d)} равнозначны и вернут одинаковый результат.

Строки форматирования указываются такие же, как и в строке “custom format” в других плейсхолдерах.

Данный форматтер нужен, чтобы иметь возможность передать его дальше по цепочке форматтеров. Например, генерируем QR-код по строке с датой: {f:DocumentCommonInfo.DocDate:#format(f=d);qrcode}

Также он может использоваться для локализации полученных данных. Например, если в поле Тема карточки документа помимо обычного текста вставлена строка локализации, то для корректного вывода в шаблоне необходимо указать:

{f:DocumentCommonInfo.Subject:#format(localize)}

при этом строка локализации на входе должна быть в формате $String или text {$String} text.

Форматтер `#align`¶

Форматтер #align используется для выравнивания текста в заданном направлении:

#align(right=30;trim;char=.)

Описание параметров форматтера выравнивания:

right=N/center=N/left=N - направление выравнивания текста, где N - количество символов, до которых необходимо выравнивать текст.
trim - если параметр указан, то при превышении допустимого размера произойдет обрезание строки.
char - символ, используемый для выравнивания. Можно указывать символ или код Unicode. Например: char=. или char=0x002E. Если параметр не указан, то используется пробел.

Example

Шаблон в формате txt, который выводит тему документа, дополнив строку точками, длина строки - 25 символов. В случае превышения (тема документа более 25 символов), строка будет обрезана:

{f:DocumentCommonInfo.Subject:#align(center=25;trim;char=.)}

Документ, сформированный по данному шаблону с темой, имеющей длину менее 25 символов:

Документ, сформированный по данному шаблону с темой, имеющей длину более 25 символов:

Форматтер `#wrap`¶

Форматтер #wrap аналогичен форматтеру #align (параметр trim не поддерживается). При превышении допустимого значения происходит перенос остатка на следующую строку.

Important

Данный форматтер корректно функционирует только для текстовых файлов формата txt.

Example

Возьмем тот же пример, что и для форматтера #align, где строка была обрезана. Только в данном случае выполним перенос строки с помощью форматтера #wrap:

{f:DocumentCommonInfo.Subject:#wrap(center=25;char=.)}

Документ, сформированный по данному шаблону:

Important

Обратите внимание, что в шаблонном файле для корректной работы переноса строк неоходимо после плейсхолдера с форматтером #wrap добавить перенос строк.

На рисунке ниже пример, где видны переносы строк.

По такому шаблону файл будет сформирован корректно, как на рисунке выше. Если же в конце не добавить перенос строк, например:

То по данному шаблону файл сформируется вот в таком виде:

Цепочки форматтеров¶

Форматтеры можно объединять в цепочки, разделяя их через точку с запятой.

Example

Выведем список ссылок на карточки (из поля Ссылки в документе) и QR-коды для открытия карточек по ссылкам в веб-клиенте на смартфоне.

В первой колонке таблицы запишем: {t:OutgoingRefDocs.DocDescription order by Order} - упорядоченный список ссылок, во второй колонке создадим область Надпись, где укажем плейсхолдер {t:OutgoingRefDocs.DocID order by Order:#webCardLink;qrcode(t=url)} - в каждой строке таблицы для идентификатора документа, на который ведёт ссылка, генерируем адрес веб-клиента (для открытия ссылки в браузере), а затем по адресу (как по строке текста) генерируем QR-код типа URL (ссылка).

В цепочке от первого форматтера ко второму передаётся результат работы первого в виде строки. Поэтому после вызова #qrcode (он возвращает массив байт с картинкой, а не текст) нет смысла отдавать результат никакому другому форматтеру из стандартных (написанный разработчиком форматтер сможет извлечь изображение и выполнить его постобработку, но по умолчанию в системе нет таких средств).

Форматтер `#file`¶

Форматтер #file загружает заданный файл или версию файла по идентификатору и представляет как массив байт, который можно направить в другие форматтеры, например, в #image или #text, т.е. по сути позволяет приложенные к карточке файлы изображений отобразить в шаблоне файла.

Example

В документе добавим таблицу из одной колонки, внутри колонки создадим объект Надпись, в которой укажем следующую конструкцию:

{t:Files.RowID:#file;image}

Результат создания файла по шаблону из карточки, к которой приложено три файла изображений:

В данном примере мы ищем файл по идентификатору #file, далее массив байт передаем в форматтер #image, который формирует изображение.

Для поиска файла по идентификатору версии файла форматтер используется с параметром version, например: {t:Files.VersionRowID:#file(version);image(w=120;h=60)}.

Идентификатор может быть получен не только из колонки-идентификатора, но и из строки, которая содержит идентификатор в поддерживаемом формате (обычный Guid в фигурных скобках, более подробно в MSDN).

Также идентификатор можно указать прямо в плейсхолдере, например: {text:4e4eb070-2333-40bd-8516-7e7c4592fbf4:#file;image}.

Форматтер `#text`¶

Форматтер #text представляет заданный массив байт как текст. Массив байт можно получить непосредственно из поля карточки, представления, или как в примере выше, из форматтера #file (т.е. из файла или версии файла с заданным идентификатором).

Для данного форматтера есть параметр t, в котором можно указать кодировку, например: {t:Files.RowID:#file;text(t=utf16)}.

Если для форматтера кодировка не задана, то текст берется в соответствующей кодировке Unicode на основании BOM (byte order mark - специальные нечитаемые символы в начале текстового файла), если он есть. Если BOM нет, то используется ANSI (это кодовая страница, заданная в региональных параметрах учётной записи Windows, например, страница 1251 для русскоязычного Windows).

Указать кодировку можно или из следующих значений (без учёта регистра):

utf7 - UTF-7
utf8 - UTF-8
utf16 или utf16le - UTF-16 Little Endian
utf16be - UTF-16 Big Endian
utf32 - UTF-32
ascii - ASCII

Или указав кодовую страницу, которая известна в .NET, подробнее в MSDN.

Шаблоны файлов и плейсхолдеры¶

Карточка шаблона файла¶

Алиасы плейсхолдеров¶

Расширения¶

Плейсхолдеры¶

Плейсхолдер {f:...}¶

Плейсхолдер {t:...}¶

Плейсхолдер {task:...}¶

Плейсхолдеры {fv:...} и {tv:...}¶

Плейсхолдеры {info:...} и {tinfo:...}¶

Плейсхолдер-объявление {⁠#alias placeholder}¶

Плейсхолдеры {n}, {0n}, {00n} и др.¶

Дополнительные плейсхолдеры¶

Экранирование плейсхолдеров¶

Шаблонизация текста¶

Обработка таблиц¶

Особенности шаблонных файлов для представлений¶

Примеры создания шаблонов файлов в формате docx¶

Блоки с условиями в шаблонах файлов в формате docx¶

Примеры создания шаблонов файлов в формате html¶

Группировка в шаблонных файлах формата html¶

Многоуровневая группировка в шаблонных файлах формата html¶

Вложенные таблицы в шаблонных файлах формата html¶

Примеры создания шаблонов файлов в формате txt¶

Примеры создания шаблонов файлов в формате xlsx¶

Группировка в шаблонных файлах формата xslx¶

Многоуровневая группировка в шаблонных файлах формата xslx¶

Вложенные таблицы в шаблонных файлах формата xslx¶

Использование формул в шаблонных файлах формата xlsx¶

Форматтеры и вставка изображений в плейсхолдеры¶

Форматтер #image¶

Форматтер #barcode¶

Форматтер #qrcode¶

Форматтер #format¶

Форматтер #align¶

Форматтер #wrap¶

Цепочки форматтеров¶

Форматтер #file¶

Форматтер #text¶

Плейсхолдер `{f:...}`¶

Плейсхолдер `{t:...}`¶

Плейсхолдер `{task:...}`¶

Плейсхолдеры `{fv:...}` и `{tv:...}`¶

Плейсхолдеры `{info:...}` и `{tinfo:...}`¶

Плейсхолдер-объявление `{⁠#alias` `placeholder}`¶

Плейсхолдеры `{n}`, `{0n}`, `{00n}` и др.¶

Форматтер `#image`¶

Форматтер `#barcode`¶

Форматтер `#qrcode`¶

Форматтер `#format`¶

Форматтер `#align`¶

Форматтер `#wrap`¶

Форматтер `#file`¶

Форматтер `#text`¶