ExportToExcelCommand

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

Поддерживаемые переменные

В значениях параметров могут быть использованы тэги для изменения форматирования параметра.

Тэги форматирования

[b][/b]	Задает полужирное начертание отрывка текста.
[i][/i]	Выделяет отрывок текста курсивом.
[u][/u]	Выделяет отрывок текста подчёркиванием.
[br]	Перенос текста на новую строку.
[size={value}][/size]	Задает отрывку текста размер шрифта. В качестве {value} ожидается целочисленное значение.

Тэги форматирования заданные в тексте ячейки так же заменяются на соответвующие форматирование.

<#variable#>

Служит для отображения скалярного значения.

<%variable%>

Служит для отображения массива (для использования в таблице).

<*function*>

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

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

Поддерживаемые агрегирующие функции

sum	Сумма значений столбца
avg	Среднее значение столбца
min	Минимальное значение столбца
max	Максимальное значение столбца
count	Количество значений столбца (число строк в таблице)

<@PATH@>

Служит для вставки изображения.

Например, для вставки изображения с параметризованным путем следует указать выражения вида <@<#variable#>@> - для скалярных значений и <@<%variable%>@> - для массивов.

Выражение PATH имеет следующий формат: PATH[?width=INT][?height=INT][?mode=MODE][?rotation=INT], где:

• PATH - полный путь до файла изображения;

• width - необязательный параметр ширины изображения; в качестве значения INT ожидается положительное целочисленное значение;

• height - необязательный параметр высоты изображения; в качестве значения INT ожидается положительное целочисленное значение;

• mode - необязательный параметр типа размера; в качестве значения MODE ожидается тип размера изображения (по умолчанию "Zoom");

• rotation - необязательный параметр поворота изображения; в качестве значения INT ожидается целочисленное значение в диапазоне от -360 до 360 градусов.

Если явно не указаны width и height, то изображение будет вписываться в размеры ячейки (высота строки и ширина колонки).

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

Параметры width и height поддерживают режимы не больше и не меньше, которые задаются символами "-" и "+" соответственно. Символы указываются после значения параметра.

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

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

Для одного параметра можно использовать только один режим.

Если используется режим, то на параметр размера не влияет параметр mode.

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

Типы размера изображения

Zoom	Растягивание изображения до указанной ширины и высоты (в большую или меньшую сторону), сохраняя пропорции изображения
ZoomLess	Растягивание изображения до указанной ширины и высоты (только в меньшую сторону), сохраняя пропорции изображения
Stretch	Растягивание изображения до указанной ширины и высоты без сохранения пропорций изображения

Динамические колонки

Для заголовков в динамических колонках используется <[#variable#]>.

Для значений в динамических колонках используется <[%variable%]>.

Для динамических колонок в качестве параметра ожидается матрица из 3-х столбцов:

1. Идентификатор строки - является вспомогательным полем, необходимым для корректного определения кол-ва динамических колонок;

2. Название столбца;

3. Значение столбца.

К примеру, в команде определён следующий параметр:

<DynamicColumns>
  <DynamicColumnSqlQuery Name="City">
    <Text>
      SELECT
        row_number() over(PARTITION BY city_id) AS "RowNumber",
        title AS "ColumnTitle",
        value AS "CellValue"
      FROM
        template.city;
    </Text>
  </DynamicColumnSqlQuery>
</DynamicColumns>

Имена полей SQL-запроса не имеют значения. Важен порядок.

ParameterSqlQuery возвращает следующие данные:

RowNumber	ColumnTitle	CellValue
1	'City1'	11
1	'City2'	12
1	'City3'	13
1	'City4'	14
2	'City1'	21
2	'City2'	22
2	'City3'	23
2	'City4'	24
3	'City1'	31
3	'City2'	32
3	'City3'	33
3	'City4'	34

В итоге будет сформирована следующая таблица:

'City1'	'City2'	'City3'	'City4'
11	12	13	14
21	22	23	24
31	32	33	34

При задании имен параметров команды необходимо соблюдать их уникальность, т.к. при формировании динамических колонок тэги <[#variable#]> и <[%variable%]> будут заменены на временные тэги по количеству колонок:

<[#variable#]> - <#variableTitle0#>, <#variableTitle1#>, <#variableTitle2#>...<#variableTitleN#>;

<[%variable%]> - <%variableValue0%>, <%variableValue1%>, <%variableValue2%>...<%variableValueN%>.

Шаблон ExportToExcelCommand

<Command Name="" Type="ExportToExcelCommand">
  <!--Тэги, общие для всех команд-->
  <Condition Name="" />
  <!--Тэги, специфичные для ExportToDocxCommand-->
  <TemplateFileNamesSqlQuery>
    <Text></Text>
  </TemplateFileNamesSqlQuery>
  <ExportFileNamesSqlQuery>
    <Text></Text>
  </ExportFileNamesSqlQuery>
  <Parameters>
    <ParameterSqlQuery>
      <Text></Text>
    </ParameterSqlQuery>
  </Parameters>
  <DynamicColumns>
    <DynamicColumnSqlQuery Name="">
      <Text></Text>
    </DynamicColumnSqlQuery>
  </DynamicColumns>
</Command>

Описание ExportToExcelCommand

<Command Name="ExportToExcelCommandName" Type="ExportToExcelCommand">
  <!--Тэги, общие для всех команд-->
  <!--Тэги, специфичные для ExportToExcelCommand-->
</Command>

Результат выполнения ExportToExcelCommand

Value

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

Тэги, специфичные для ExportToExcelCommand

TemplateFileNameSqlQuery

Sql-запрос, возвращающий список путей XLSX-файлов шаблонов, хранящихся на сервере.

Обязательный тэг. Любое значение будет переведено в текстовое.

<TemplateFileNameSqlQuery>
  <Text>SQL-query</Text>
</TemplateFileNameSqlQuery>

ExportFileNameSqlQuery

Sql-запрос, возвращающий список полных путей до XLSX-файлов, в которые будут выгружены данные.

Обязательный тэг. Любое значение будет переведено в текстовое.

<ExportFileNameSqlQuery>
  <Text>SQL-query</Text>
</ExportFileNameSqlQuery>

Parameters

Набор Sql-запросов данных для вставки скалярных и табличных параметров.

Необязательный тэг. Ожидает список тэгов <ParameterSqlQuery>.

<Parameters>
  <ParameterSqlQuery>
    <Text>SQL-query</Text>
  </ParameterSqlQuery>
</Parameters>

ParameterSqlQuery

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

Необязательный тэг. Содержит обязательный тэг <Text>, ожидающий текст SQL-запроса.

Разделение данных на несколько тэгов <ParameterSqlQuery> позволяет избежать построение громоздких SQL-забросов, а так же отделить скалярные данные от табличных.

Пример

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

<Parameters>
  <ParameterSqlQuery>
    <Text>
    	SELECT
		    O.order_number AS "OrderNumber",
	  	  O.order_date AS "OrderDate"
	  	FROM
		    _order O
		  WHERE
    		O.order_id = {OrderId};
    </Text>
  </ParameterSqlQuery>
  <ParameterSqlQuery>
    <Text>
	    SELECT
	      M.title AS "OrderPositionTitle",
	      OP.quantity AS "OrderPositionQuantity",
	      OP.unit_price AS "OrderPositionUnitPrice",
	      OP.quantity * OP.unit_price AS "OrderPositionTotalPrice"
    	FROM
    	  template.order_position OP
    	  LEFT JOIN template.material M USING(material_id)
		  WHERE
    		OP.order_id = {OrderId}
    	ORDER BY OP.order_position_id;
    </Text>
  </ParameterSqlQuery>
</Parameters>

DynamicColumns

Набор Sql-запросов данных для динамических колонок.

Необязательный тэг. Ожидает список тэгов <DynamicColumnSqlQuery>.

<DynamicColumns>
  <DynamicColumnSqlQuery Name="ParameternName">
    <Text>SQL-query</Text>
  </DynamicColumnSqlQuery>
</DynamicColumns>

DynamicColumnSqlQuery

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

Необязательный тэг. Содержит обязательный тэг <Text>, ожидающий текст SQL-запроса.

Обязательный атрибут Name - задает имя параметра для вставки данных.

Пример

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

<DynamicColumns>
  <DynamicColumnSqlQuery Name="City">
    <Text>
      SELECT
        row_number() over(PARTITION BY city.city_id) AS "RowNum",
        city.title AS "CityTitle",
        client.title AS "ClientTitle"
      FROM
          template.city
          LEFT JOIN template.client USING(city_id)
      ORDER BY city.city_id;
    </Text>
  </DynamicColumnSqlQuery>
</DynamicColumns>