...
Шаблоны документов плагина Documents
Для автоматизации заполнения типовых форм документов предназначена функция генерации документов по шаблону. Шаблон документа заводится в редакторе шаблонов, доступном через меню Плагины=>Документы=>Шаблоны документов.
Для создания нового шаблона документа щелкните на кнопку Новый элемент на стандартной панели инструментов. В появившемся редакторе заполните необходимые поля, выберите файл шаблона - документ в формате docx (предпочтительный формат), odt (на сервере должен быть установлен пакет LibreOffice), xlsx.
На представленном выше рисунке отображены следующие поля:
Имя шаблона - имя шаблона документа;
Имя выходного документа - название документа, который будет сгенерирован и привязан к договору;
Файл шаблона - загружаемый шаблон документа в формате docx, odt, xlsx;
Комментарий к файлу - комментарий к загружаемому файлу шаблона;
Имя выходного файла - имя сгенерированного файла;
Комментарий к шаблону - комментарий шаблона;
Динамический класс - Java-класс, в котором возможно определить логику получения данных для шаблона;
Видимость шаблона в плагине - флаг того, что шаблон будет отображен на вкладке Документы в договоре;
Переменные - список переменных, содержащихся в файле шаблона документа;
Таблицы - список таблиц, которые требуется сгенерировать в файле шаблона документа.
Файл шаблона представляет собой текстовый документ, содержащий в своем тексте специальные последовательности, на место которых будут подставлены данные. Формат таких последовательностей имеет вид:
| Блок кода | ||||
|---|---|---|---|---|
| ||||
{имя_переменной} или {имя_переменной(значение_по_умолчанию)} |
где имя_переменной - название этой последовательности; в тексте шаблона данное название должно совпадать с именем переменной в таблице Переменные;
значение_по_умолчанию - то значение, которое будет подставлено вместо последовательности в случае, если по имени перменной возвратится пустое значение (н-р, если в договоре отсутствует какой-либо заполненный параметр, то на его место можно поставить прочерк или какую-нибудь фразу ).
Новая переменная заводится с помощью редактора переменных, который вызывается нажатием на кнопку
...
...
...
В диалоговом окне редактора переменной задается имя переменной, ее тип и значение. Тип переменной выбирается в соответствующем выпадающем списке. Доступны следующие варианты:
Константа - значение переменной данного типа подставится в тело шаблона документа как есть. Данный тип переменной поддерживает макроподстановки, о которых речь пойдет ниже.
Параметр договора - как следует из названия, значение переменной данного типа берется из параметра договора. Для этого необходимо выбрать тип параметра договора и непосредственно сам параметр.
Дата - значение переменной данного типа можно выбрать из календаря (статическая дата, например, дата принятия устава), либо выбрать одно из предустановленных значений получения даты (динамическая дата. Возможные варианты: текущая дата, дата создания договора). Для переменной типа дата возможно ввести формат даты, который отформатирует дату требуемым образом. Подробнее о форматах дат см. SimpleDateFormat.
URL - предполагается, что значение переменной данного типа расположено на каком-то удаленном узле;
SQL - получение значения переменной данного типа осуществляется путем выборки из БД с помощью SQL-запроса.
В переменных типа Константа возможны следующие макроподстановки:
${contract_title} - название договора, для которого генерируется документ;
${contract_comment} - комментарий договора;
${current_user} - имя пользователя, который генерирует документ;
${user_<userId>} - имя пользователя с кодом <userId>. Код пользователя можно посмотреть в редакторе пользователей биллинга (Сервис=>Администрирование=>Пользователи и права), выбрав интересующего пользователя в таблице и нажав комбинацию клавиш Ctrl+i.
В переменных типа SQL возможны следующие макроподстановки:
${cid} - код договора, для которого генерируется документ.
Если в шаблоне документа задан динамический Java-класс, то значения, возвращаемые данным классом, имеют бОльший приоритет и перетирают значения одноименных переменных в списке переменных.
Динамический Java-класс реализует интерфейс ru.bitel.bgbilling.plugins.documents.server.bean.pattern.PatternDataExtractor, содержащий метод extractData( Connection con, int contractId, DocumentPattern pattern, DocumentType type, DocumentJournal journal, Map<String, String> apiMap ), который должен возвращать объект типа Map<String, String> - список переменных в формате "ключ=>значение переменной". Здесь в качестве ключа выступает название переменной, соответствующей переменной в файле шаблона документа.
Простой пример реализации метода extractData(Connection con):
| Блок кода | ||||
|---|---|---|---|---|
| ||||
public Map extractData( Connection con, int contractId, DocumentPattern pattern, DocumentType type, DocumentJournal journal, Map<String, String> apiMap ) throws BGException
{
Map<String, String> result = new HashMap<String, String>();
result.put("param1","value1");
result.put("param2","value2");
return result;
} |
Если в файле шаблона документа есть таблицы, которые необходимо сгенерировать, то в редакторе шаблонов необходимо добавить соответствие между таблицей в файле шаблона и таблицей в шаблоне, создаваемом в клиенте биллинга. Это осуществляется на вкладке Таблицы редактора шаблонов путем нажатия кнопок Добавить
...
...
...
В представленном редакторе задается символьное имя таблицы, ее порядковая позиция в файле документа, метод получения данных и, соответствующее методу получения данных, значение для таблицы. На данный момент поддерживается 2 метода получения данных:
SQL - полученная SQL-запросом таблица как есть попадет в тело сгенерированного документа. В SQL-запросе возможно использование макроподстановки ${cid} - код договора, для которого производится генерация документа;
Динамический класс Java - класс на Java, который возвращает данные для генерируемой таблицы.
Для генерации содержимого таблицы необходимо в файле шаблона создать заголовок таблицы и первую строку-шаблон, содержащую образец форматирования текста и ячеек. В этой строке-шаблоне также необходимо прописать названия столбцов, которые будут выступать в качестве ключей при получении данных (только для метода получения данных - Динамический класс). Если названия столбцов не заданы, то используются названия по умолчанию (col1...colN). В методе получения данных SQL по умолчанию используется нотация col1...colN, следовательно, задавать названия столбцов не обязательно.
Динамический класс должен реализовывать интерфейс ru.bitel.bgbilling.plugins.documents.server.bean.pattern.TableDataExtractor и метод extractData( Connection con, int contractId, List<Map<String, String>> apiRowList ), который возвращает List<Map<String, String>>, т.е. список строк и содержимое столбцов в виде "ключ->значение". В качестве ключа выступает название столбца в строке-шаблоне.
Замечения:
Рекомендуется использовать в качества шаблона документа файл Microsoft Office с расширением docx.
При использовании в качества шаблона документа файл с расширением odt необходимо, чтобы на сервере был установлен пакет LibreOffice. Также необходимо учитывать, что при использовании данного формата файла возможно искажение форматирования документа.
При использовании в качестве шаблона документа файл с расширением xlsx будет производиться подстановка ТОЛЬКО переменных в таблице на всех листах книги.
Для генерации документа необходимо открыть договор, для которого требуется сгенерировать документ по шаблону, выбрать вкладку Документы, выбрать Шаблон документа из выпадающего списка, Тип генерируемого документа и Журнал и нажать кнопку Сгенерировать. Сгенерированный документ появится в списке документов договора.