# Шаблоны отчетов

## Принцип разметки
Шаблонов документов имеют одинаковую разметку, что позволяет, научившись размечать шаблоны одного типа, создавать отчёты других типов.
```{note}
Раздел не относится к специализированным отчетам, таким как Jasper Reports.
```
Рассмотрим основные положения.

Основным элементом разметки шаблона является 
- `Тэг` \
  Текст окружённый спецсимволами, управляющий формированием отчёта. 
  
Все тэги имеют следующий вид: `[#{значение}#]`

Простейшим случаем является Тэг, возвращающий значение атрибута строки: `[#{имя атрибута}#]`. 

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

Для печати в отчете набора данных предназначены переменные части, позволяющие выполнять запросы и выводить в отчёт данные с изменяющимся количеством строк. 

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

Форматы тегов для печати данных из запроса:
- открывающий тэг
  ```
  [#&{произвольное системное имя}={SQL запрос}#]
  ```
- закрывающий тэг
  ```
  [#/{произвольное системное имя}#]
  ```

Переменная часть обязательно должна заканчиваться закрывающим тэгом, системное имя которого совпадает с системным именем открывающего тэга. Все системные имена открывающих тэгов начинаются с символа `&`, а все закрывающие тэги начинаются с символа `/`.

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

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

Если из вложенного уровня	(уровень «деталь») необходимо получить значение атрибута из запроса верхнего уровня (уровень «мастер»), то следует использовать маркер следующего вида: [#super$sField#]
где «sField» - имя атрибута из Sql-запроса верхнего уровня.
При этом стоит отметить, что маркер [#sField#] тоже сработает, если атрибут «sField» присутствует только в запросе верхнего уровня. Если же он встречается в запросе нижнего уровня, то в печатной форме будет выведено значение из него.

```{tip}
1.	Располагайте открывающие и закрывающие тэги на отдельных строчках.
2.	Выносите запросы переменных частей в выборки, если их длина больше 1000 символов.
```

## Шаблон xlxs
Шаблоном xlxs является документ в формате `xlxs`, размеченный согласно общим правилам разметки шаблонов, описанным в предыдущем разделе. 
![](report_template/ReportExample.png)
```{only} html
{download}`скачать пример <report_template/ReportExample.xlsx>`
```
```{only} latex
Обратитесь к дистрибьютору документации за файлом `report_template/ReportExample.xlsx`
```

## Шаблон docx
Шаблоном docx является документ в формате `docx`, размеченный согласно общим правилам разметки шаблонов. 
Если создать отчёт с шаблоном docx,  скопировать в него разметку из отчёта xlsx, отчёт результат построения будет таким же, как для XLS. Отличия будут только  в форматировании, данные будут теми же.

## Шаблон TXT 
Шаблон на основе текстового файла был реализован для быстрой печати на матричных принтерах, поскольку печать текста происходит на много быстрее, чем печать графики или векторных шрифтов.
Пример:
```
[#&Person=Select * from LBR_Person#]
Карточка читателя библиотеки №[#sMnemoCode#]
Фамилия: [#sSecondName#] Имя: [#sFirstName#]
Отчество: [#sMiddleName#] Дата рождения: [#dBirthDate#]
Телефон: [#sPhone#]
Список заказов
Рег. №	Дата	Состояние
[#&Orders=select o.*, 
lbr_UserOrderAPI.GetIdState_HL(o.idState) as IdState_HL 
from lbr_UserOrder o
where o.idUser = :super$id#]
[#nRegNumber#][#dDate#][#idState_HL#]
[#/Orders#]
[#/Person#]
```

```{attention}
  Открывающий тег с запросом должен располагаться в одной строке!
```