.. _gs3_excel_template:

Excel-шаблоны (``.xls``, ``.xlsx``, ``.xlsm``)
==============================================================

В ApplicationServer используется прямое заполнение шаблона через Aspose.Cells.
OLE Automation (заполнение через MS Excel) не используется.

Если в данном разделе встречается пометка "не подтверждено", это означает:

- Функциональность отчетов, работавшая в :term:`Global 1`, может не работать при построении
  отчета на сервере приложений Global.
- Работу функциональности необходимо проверить на реальном решении для сервера
  приложений Global.

Базовая разметка
----------------

Теги в Excel-шаблонах:

- Подстановка значения:

  ``[#AttributeName#]``

- Открытие секции:

  ``[#&SectionName#]``

- Закрытие секции (после имени может быть макрокод):

  ``[#/SectionName  <macro code>#]``

Если атрибут не найден, значение заменяется на пустую строку.
Для обращения к мастер-выборке используйте ``super$``:

``[#super$AttributeName#]``

Секции и SQL
------------

Открывающий тег может ссылаться на выборку или содержать SQL:

- Выборка: ``[#&EntityName.Representation#]``
- SQL: ``[#&SectionName = select ...#]``

Тело секции повторяется для каждой строки выборки.

Многострочный открывающий тег
-----------------------------

.. versionadded:: v1.27.0-ms17


Для длинных SQL-разметок открывающий тег секции можно разнести
по нескольким строкам **в одном столбце**:

.. code-block:: text

   A1: [#&SectionName = select ...
   A2:     ... продолжение ...
   A3:     ... продолжение ... #]

Правила:

- ``[#&`` должен начинаться в ячейке (допускаются пробелы перед ним).
- Продолжение размещается в ячейках ниже **того же столбца**.
- Закрывающий ``#]`` находится в одной из строк продолжения.
- Эти строки не попадают в результат (они являются частью открывающего тега).

Подстановка значений в ячейках
------------------------------

- Если ячейка содержит **только один** тег, значение записывается с типом
  (число, дата, boolean и т.д.).
- Если в ячейке есть текст и теги вместе, теги заменяются строковыми
  значениями, результат записывается как строка.

Размножаемые колонки
--------------------

Поддерживается синтаксис ``param[*]`` для размножения колонок. Колонка
копируется по количеству ключей ``param[<key>]`` в выборке.

.. note::

   Поддержка нескольких тегов в одной ячейке при использовании ``param[*]``
   не подтверждена в AS и требует проверки.

Встроенные функции (макроязык)
------------------------------

Функции применяются внутри тегов, например ``[#FNum(nPrice,2)#]``.
Поддерживается вложение функций.

.. include:: _macro_language_functions_common.rst

Макросы Excel
-------------

AS сохраняет содержимое шаблона, но выполнение макросов на стороне сервера
не производится. Поддержка VBA-макросов в ``.xlsm`` и перенос макросов
в итоговый файл **не подтверждены** и должны быть проверены в целевом решении.

Пример (текстовое представление)
--------------------------------

.. code-block:: text

   A1: [#&Orders = select ...#]
   A2: [#OrderId#]    [#OrderDate#]    [#Total#]
   A3: [#/Orders#]