Создание пользовательских отчетов при помощи MATLAB Report Generator

Автор Thomas Deck, MathWorks

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

При помощи MATLAB Report Generator™ можно быстро создать отчет на базе шаблонов. Используя DOM API для создания представления отчета в памяти системы, можно генерировать пользовательские отчеты для любого применения в форматах Microsoft^® Word, PowerPoint^®, PDF или HTML.

Используя в качестве примера документ Microsoft Word, в этой статье объясняется, как использовать DOM API для генерации как простого отчета, так и более сложного и кастомизированного отчета.

Код, который использовался в этом примере, доступен для скачивания.

Создание шаблона

Для генерации отчета при помощи DOM API, нужно сначала создать шаблон документа. Этот шаблон включает содержимое, которое не меняется при генерации отчета – например, заголовки и колонтитулы, а также заглушки – это те части документа, которые динамически наполняются при помощи функций MATLAB^®.

В этом примере мы начнем с создания шаблона в Word. Чтобы создать шаблон, нужно перейти в директорию SimpleReport в распакованном архиве, который прилагается к этой статье и выполнить скрипт copyTemplate. Этот скрипт копирует пустой шаблон из директории установки MATLAB в текущую директорию и переименовывает его в myTemplate.dotx. Файл myTemplate.dotx нужно открыть в Word.

Подсказка: Иногда Word открывает файл, но показывает “document1” вместо имени щаблона в заголовке окна. В этом случае вы не сможете сохранить изменения в шаблоне. Чтобы избежать этой проблемы, следует открыть шаблон, вызвав Word с параметром командной строки /N или при помощи скрипт “openTemplate2013”.

Когда документ открыт, нужно перейти во вкладку Разработчик и выбрать Режим конструктора. По умолчанию вкладка Разработчик отключена. Чтобы включить её, сделайте следующее:

1. Щелкните по вкладке Файл и выберите Параметры – Настроить ленту.
2. Выберите Основные вкладки и поставьте галочку Разработчик.

Режим конструктора позволяет увидеть заглушки и отличить их от фиксированного содержимого при помощи выделения заглушек.

Чтобы добавить новую заглушку, нужно поместить курсор в том место, где должна быть создана заглушка и нажать кнопку «Элемент управления содержимым «форматированный текст»» (“Aa”). Нажмите на кнопку Свойства, чтобы изменить свойства заглушки (Рисунок 1). Вводить текст в заглушке нет необходимости, но добавление текста, который бы указывал назначение заглушки, сделает шаблон более понятным. Этот текст не будет отображаться в окончательном отчете.

Рисунок 1. Шаблон отчета, открытый в Word 2013. Активна вкладка Разработчик, и выделены Режим конструктора, Элемент управления содержимым «форматированный текст» и Свойства.

 

Мы открываем окно Свойств элемента управления содержимым для указания Названия и Тега (они должны совпадать). Затем мы закрываем это диалоговое окно и сохраняем и закрываем шаблон.

Наполнение заглушек

После выполнения функции MATLAB fillFirstHole, генерируется новый документ.

function fillFirstHole
% Эта функция наполняет заглушку "firstHole" в myTemplate.dotx
   import mlreportgen.dom.*;
   
   doc = Document('firstDocument', 'docx', 'myTemplate');
   holeId = moveToNextHole(doc);
   fprintf('ID текущей заглушки: %s\n', holeId);
   textObj = Text('Всем привет!');
   append(doc, textObj);
   close(doc);
   
   rptview('firstDocument', 'docx');

end

Новый документ, firstDocument, имеет расширение docx и основан на myTemplate.dotx. Мы говорим DOM API перейти на первую заглушку, а затем создать объект класса Text, который содержит строку “Всем привет!”. Мы присоединяем этот объект к документу, закрываем документ и открываем firstDocument.docx для просмотра.

Подсказка: При возникновении сообщения об ошибке при запуске функции fillFirstHole, убедитесь, что myTemplate.dotx и firstDocument.docx закрыты.

Блочные и встроенные заглушки

В Microsoft Word можно создавать два типа заглушек: встроенные и блочные (Рисунок 2). Встроенная заглушка находится внутри параграфа и может содержать только элементы, которые могут быть в параграфе – такие, как текст, изображения и гиперссылки. Блочная заглушка может включать любое содержимое, включая другие параграфы.

Рисунок 2. Интерфейс Word для создания встроенных и блочных заглушек.

 

Чтобы создать встроенную заглушку, поместите курсор внутрь непустого параграфа и нажмите кнопку Элемент управления содержимым «форматированный текст».

Чтобы создать блочную заглушку, создайте пустой параграф и нажмите кнопку Элемент управления содержимым «форматированный текст».

Подсказка: Чтобы поместить встроенную заглушку непосредственно перед параграфом, добавьте пробел перед параграфом, в противном случае Word создаст блочную заглушку. Затем можно удалить этот пробел.

Добавление стилей

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

function fillFirstHoleWithStyle
% Эта функция наполняет заглушку "firstHole" в myTemplate.dotx
   import mlreportgen.dom.*;
   
   doc = Document('firstDocument', 'docx', 'myTemplate');
   holeId = moveToNextHole(doc);
   fprintf('ID текущей заглушки: %s\n', holeId);
   textObj = Text('Всем привет!', 'Heading 1');
   textObj.Bold = true;
   append(doc, textObj);
   close(doc);
   
   rptview('firstDocument', 'docx');   

end

Можно менять отдельные свойства – такие, как полужирное начертание (Bold) или цвет (Color), или использовать свойство ИмяСтиля для задания внешнего вида. Свойство ИмяСтиля применяет стиль Word к указанному объекту. Таким образом, внешний вид объекта контролируется стилем, заданным в вашем шаблоне.

Если свойство ИмяСтиля не задано, то стиль наследуется от параграфа в шаблоне.

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

DOM API позволяет использовать только те стили, которые заданы в шаблоне. Наиболее распространенные стили встроены в поставляемый шаблон. Чтобы скопировать различные встроенные стили в шаблон, примените новый стиль ко временному тексту, а затем удалите это текст.

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

Рисунок 3. Параметры области стилей в Word, настроенные для отображения только используемых стилей.

 

Решение о том, следует ли задать или изменить стиль в Word или же управлять внешним видом при помощи DOM API зависит от задачи. Если вы хотите использовать определенный формат или шаблон часто, то лучше создать стиль в Word. Обратите внимание, что Word позволяет задать стили для таблиц и списков. Если вы только хотите изменить определенную секцию вашего документа, то лучше будет управлять внешним видом из вашей функции MATLAB.

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

Генерация продвинутого отчета

Обширная библиотека классов из DOM API позволяет добавлять самые разные объекты в ваш отчет, такие, как текст, изображения, гиперссылки и таблицы. Перед тем, как начать создавать отчет, содержащий множество разных объектов, следует определить интерфейсы между функцией, которая создает отчет и функцией, которая получает данные, отображаемые в отчете.

Самый простой способ – это сделать так, чтобы имя каждого поля в структуре с данными для отчета соответствовало имени заглушки в шаблоне отчета. Тогда код в функции MATLAB, который наполняет заглушки, может представлять из себя простой цикл while.

Добавление изображений и таблиц

Мы начинаем со сбора данных в функции getAdvancedReportData в директории AdvancedReport. Эта функция определяет интерфейсы между отчетом и данными для отчета. Некоторые элементы, такие, как Заголовок (Title), являются обычным текстом. Другие – такие, как Автор (Author), зависят от переменных окружения в системе. Обе таблицы заполняются случайным предложением, сгенерированным функцией why в MATLAB.

Затем мы подготавливаем шаблон в соответствии с требованиями проекта и добавляем заглушки, определенные в нашем интерфейсе. Следующие объекты уже были заданы в шаблоне AdvancedReportTemplate.dotx:

• Стили Word, которые мы хотим использовать: 
• AR_Heading1-3 для заголовков глав (заголовки глав используются для создания оглавления).
• AR_Title и AR_SubTitle для встроенных заглушек на титульной странице.
• AR_Image и AR_Caption для отцентрованных изображений и нумерованных подписей к рисункам.
• AR_Normal для текста со шрифтом, отличающимся от стиля Обычный (Normal).
• AR_Table для измененного внешнего вида простой таблицы.
• Желаемые стили параграфов и заглушек
• Фиксированный заголовок с логотипом компании и пустой колонтитул, показывающий номера страниц
• Оглавление и список рисунков
• Скелет структуры, заданный фиксированными заголовками глав и подглав

Наконец, мы создаем отчет при помощи функции MATLAB createAdvancedReport. Мы обрабатываем все заглушки в цикле while. В цикле происходит переключение между следующими случаями:

“Стандартные” заглушки. В ветке ‘otherwise’ блока switch case, этим заглушкам просто назначается их текст. Внешний вид определяется Word исходя из примененного стиля.

Изображение. В этом случае наша структура reportData содержит путь к изображению, которое будет добавлено в отчет. В функции processImage объект Image (изображение) добавляется к параграфу со стилем AR_Image. В этом стиле выбрано выравнивание по центру, поэтому изображение отцентровано. Подпись к рисунку добавляется при помощи другого параграфа со стилем AR_Caption. Этот стиль обеспечивает автоматическую нумерацию рисунков и используется для создания списка рисунков.

Простая таблица. В функции processSimpleTable мы создаем целиком подглаву в блочной заглушке. Перед тем, как добавлять таблицу, мы присоединяем параграф со стилем AR_Heading2, чтобы добавить новый заголовок второго уровня в отчет. Мы создаем простую таблицу используя класс Table (таблица). Требуются только данные для таблицы и стиль для таблицы AR_Table. Этот стиль для таблицы в Word отвечает за отображение и форматирование таблицы.

Продвинутая таблица. В функции processAdvancedTable мы используем другую блочную заглушку для создания новой подглавы и еще одной таблицы – на этот раз с классом FormalTable. Этот класс позволяет нам создать таблицу полностью с нуля. Нам нужно добавлять каждую ячейку таблицы, но зато мы полностью контролируем внешний вид. Чтобы показать это, мы заполняем фон каждой ячейки таблицы случайным цветом.

Теперь мы готовы выполнить createAdvancedReport и сгенерировать продвинутый отчет.

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