Руководство разработчика

Функция ЭКСПОРТ_ФОРМЫ

Функция ЭКСПОРТ_ФОРМЫ позволяет осуществлять передачу данных в офисные приложения MS Word и MS Excel, а также OpenOffice.org Writer и OpenOffice.org Calc. Документ создается в соответствующем приложении, а места подстановки данных помечаются ключевыми строками. Поддерживаются простые подстановки, когда все вхождения ключевой строки заменяются соответствующим текстом, а также табличные. Табличные подстановки позволяют создавать в документе копии исходной строки таблицы, помеченной ключевой строчкой. Столбцы в такой строке также помечаются ключевыми строками. Для наполнения структуры данных используются функции ДОБ_ПОДСТ, ДОБ_ТАБЛ_ПОДСТ и СБРОС_ПОДСТ.

ФУНКЦИЯ ТИП_ЛОГИКА: ЭКСПОРТ_ФОРМЫ(ТИП_СТРОКА: приложение, файл, опции)

Параметры

приложение
Идентификатор целевого приложения, доступны следующие варианты:
"DEFAULT"- автоматический выбор;
"EXCEL"- MS Excel;
"WORD"- MS Word;
"OPENOFFICE CALC"- OpenOffice.org Calc;
"OPENOFFICE WRITER"- OpenOffice.org Writer.
"XML"- запись данных в XML файл для последующего экспорта утилитой xmlexp.exe.
Если установлено значение "DEFAULT", будет выполняться автоматический выбор приложения в зависимости от того, что установлено на компьютере. В остальных случаях экспорт будет осуществляться в указанное приложение.
файл
Путь к файлу документа (шаблона), который будет использован для применения подстановок. Расширение файла помогает сделать автоматический выбор приложения в режиме "DEFAULT".
опции

Опции процесса экспорта:

  • Есть возможность указать название файла и путь к папке, в которую будет сохранен файл, например, "MyCharts/Chart_1.ods". Если указано только название файла, то он сохраняется в текущую папку Инфо-Бухгалтера.
  • Поддерживается команда закрытия документа после сохранения результата ">close", которую необходимо указывать после пути файла. Например, "Chart_1.ods>close".
  • При подстановках в шаблон есть возможность добавлять лист в сохраняемый файл. Для этого необходимо указать директиву ">ADD" после имени файла. Эта возможность поддерживается для экспорта в MS Excel и OpenOffice Calc. Опционально может быть указано имя нового листа: ">ADD=<имя_листа>". Если файл с указанным именем для сохранения результата уже существует, то он открывается и лист добавляется к существующим, иначе создается новый документ с одним листом. Директива ADD может комбинироваться с директивой CLOSE, например "output.xls>CLOSE>ADD=Документ2".

Возвращаемое значение

ДА – в случае успешного завершения экспорта, НЕТ – в случае ошибки.

Замечания:


При экспорте в Excel и OpenOffice Calc можно указать номер или имя листа в ключевой строке подстановки.

Например:
"#2:_ЗАМЕНИ_ЭТО" – "_ЗАМЕНИ_ЭТО" на втором листе,
"Часть2:_ЗАМЕНИ_ЭТО" – "_ЗАМЕНИ_ЭТО" на листе "Часть2".

При подстановках в Word и OpenOffice Writer часть ключевой строки перед ":" не учитывается.


При заполнении шаблонов в Excel и OpenOffice Calc не происходит автоматическая подгонка высот строк, которые содержат измененные ячейки. Это происходит из-за особенностей реализации этих приложений. Для обеспечения подгонки высоты строк для ячеек с многострочным текстом (в т.ч. объединенных) при разработке шаблона их следует особым образом пометить. Для помеченных ячеек библиотекой экспорта выполняется дополнительная обработка, восполняющая недостатки целевых приложений.

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

  1. для ячейки должен быть включен признак "перенос по словам";
  2. фон ячейки должен иметь цвет "Лаванда" RGB(204, 153, 255), номер в Excel 39, название в OpenOffice "фиолетовый 10".

После обработки таких ячеек цвет фона заменяется на белый.


Функция ЭКСПОРТ_ФОРМЫ позволяет производить подстановку изображений в шаблон документа с соблюдением параметров формата изображения-заглушки, установленного в шаблоне. Подстановка изображения производится как по названию изображения, которое задано в шаблоне, так и по порядковому номеру в шаблоне. Синтаксис указания подстановки изображения в шаблон офисного приложения приведен ниже.

@<имя_изображения>
@#<номер_изображения>

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

Использование порядкового номера не гарантирует точность подстановки в заданное место из-за того, что порядок присвоения номера изображению в документе точно неизвестен. Кроме того, в приложении Word изображения в документе разделяются на коллекции inline-shape (обтекание в тексте) и free floating shape (обтекание текстом), и в каждой коллекции свой порядок нумерации. То есть если в шаблоне документа два изображения: одно с обтеканием в тексте, другое с обтеканием перед текстом. В коде ниже указывается, что нужно осуществить подстановку во второе изображение в шаблоне документа.

ДОБ_ПОДСТ("@#2", путь_шаблона + "data.jpg")   
ЭКСПОРТ_ФОРМЫ("WORD", "imgsubst_sample.dotx","saved.doc>CLOSE"

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

Применение функции ЭКСПОРТ_ФОРМЫ для вставки изображений в шаблон аналогично функции ЭКСПОРТ_ГРАФИКА.

Инструкции удаления

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

Шаблон Microsoft Word / OpenOffice.org Writer

Инструкция Назначение Простой текст Таблица
"-~E~-" Удаление ячейки со смещением влево. Удаляется текст всех вхождений тега в документе. Подобно замене на пустую строку. Не поддерживается.
"-~U~-" Удаление ячейки со смещением вверх. Не поддерживается. Не поддерживается.
"-~C~-" Удаление одного или нескольких столбцов. Не поддерживается. Удаляется столбец текстовой таблицы целиком (с заголовком).
"-~R~-" Удаление одной или нескольких строк. Удаляются все строки текста, содержащие тег. Не поддерживается.
"-~T~-" Удаление таблицы целиком. Не поддерживается. Удаляется вся таблица с заголовком.

Шаблон Microsoft Excel / OpenOffice.org Calc

Инструкция Назначение Описание
"-~E~-" Удаление ячейки со смещением влево. Удаляется простая или объединенная ячейка. Если справа от удаляемой ячейки есть объединения, то удаление может не произойти. Для табличных подстановок удаление выполняется после заполнения таблицы.
"-~U~-" Удаление ячейки со смещением вверх. Удаляется простая или объединенная ячейка. Если снизу от удаляемой ячейки есть объединения, то удаление может не произойти. Для табличных подстановок удаление выполняется после заполнения таблицы.
"-~C~-" Удаление одного или нескольких столбцов. Удаление столбца целиком. Для объединенной ячейки удаляются все ее столбцы.
"-~R~-" Удаление одной или нескольких строк. Удаление строки целиком. Для объединенной ячейки удаляются все ее строки.
"-~T~-" Удаление таблицы целиком. Не поддерживается.

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

Допустим, у нас есть файл шаблона "PriceList.odt" со следующим содержимым:

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

// удаляем данные предыдущей подстановки, если такая была
СБРОС_ПОДСТ
ДОБ_ПОДСТ("_адрес", Адрес)                           // из реквизитов
ДОБ_ПОДСТ("_дата",  ДАТА_ТЕК)                        // текущая дата
ДОБ_ТАБЛ_ПОДСТ("_товары:", "_наим", 1, "Молоко")     // первый товар
ДОБ_ТАБЛ_ПОДСТ("_товары:", "_цена", 1, 34.99)

ДОБ_ТАБЛ_ПОДСТ("_товары:", "_наим", 2, "Сметана")    // второй товар
ДОБ_ТАБЛ_ПОДСТ("_товары:", "_цена", 2, 49.99)

ДОБ_ТАБЛ_ПОДСТ("_товары:", "_наим", 3, "Тан")        // третий товар
ДОБ_ТАБЛ_ПОДСТ("_товары:", "_цена", 3, 39.99)

// подставляем в OpenOffice.org Writer
ЭКСПОРТ_ФОРМЫ("OPENOFFICE WRITER", "PriceList.odt",
    "PriceList_" + СТР(ДАТА_ТЕК) + ".odt>CLOSE"

В результате будем иметь файл "PriceList_05.09.2013.odt" со следующим содержимым:


См. также: