API генерации отчета MATLAB Report Generator поддерживает создание средств поиска, которые ищут контейнеры данных заданные объекты и возвращают результаты в заслуживающую публикации форму. Средства поиска позволяют вам разделять поисковую логику от логики отчета в ваших генераторах отчетов. Средства поиска также способствуют повторному использованию поисковой логики, таким образом, ускоряя разработку генераторов отчетов. В этом примере показано, как разработать и использовать средство поиска, чтобы сгенерировать отчет.
Создание средства поиска влечет за собой создание класса MATLAB, который задает свойства и поведение средства поиска. Следующие разделы объясняют, что шаги должны были создать класс средства поиска. Объяснение использует класс под названием GrantFinder as an example
. Код для класса находится в файле, GrantFinder.m
, это сопровождает этот скрипт. GrantFinder
класс задает средство поиска, способное к нахождению и форматированию грантов, предоставленных американским Национальным фондом гуманитарных наук (NEH).
Создайте скелетный файл определения класса
Используйте редактор MATLAB (не Live Editor), чтобы создать скелетное определение класса для вашего средства поиска, например
Задайте базовый класс средства поиска
Задайте API отчета mlreportgen.finder.Finder
класс как базовый класс для вашего средства поиска.
Этот базовый класс задает свойства, которые характерны для средств поиска, включая
Container
: свойство раньше ссылалось на контейнер, который будет искаться средством поиска. Например, GrantFinder
используйте это свойство сохранить ссылку на базу данных предоставления, которую оно создает.
Properties
: свойство, используемое клиентами средства поиска, чтобы задать значения свойств, что объекту, должно быть, придется удовлетворить поиску. Например, это свойство позволяет клиенту GrantFinder задавать свойства предоставления, что предоставление, должно быть, придется возвратить в результате поиска базы данных предоставления NEH.
mlreportgen.finder.Finder
класс задает другие свойства и методы, которые должно задать ваше определение класса средства поиска. Это гарантирует, что ваше средство поиска работает с API Отчета.
Задайте конструктора средства поиска
Задайте функцию, которая создает экземпляр вашего средства поиска, например,
GrantFinder
конструктор использует xmlread
MATLAB функционируйте, чтобы считать XML-файл предоставления из диска и преобразовать его в Java документ DOM. Это затем передает документ DOM
mlreportgen.finder.Finder
конструктор, который устанавливает Java документ DOM как значение Container
средства поиска свойство. При хранении базы данных NEH как Java документ DOM позволяет средству поиска использовать стороннее программное обеспечение Java, чтобы искать базу данных. См. Java Xerces API DOM для получения дополнительной информации.
Конструктор также вызывает reset
функция, которая инициализирует переменные, раньше искала базу данных предоставления. Класс GrantFinder задает эту функцию. Точно так же ваш класс должен задать функцию сброса. reset
функция гарантирует, что клиент может использовать ваше средство поиска, чтобы провести несколько поисковых запросов его контейнера. Смотрите Задают Функцию Сброса для получения дополнительной информации.
Задайте find
Метод
Задайте метод, чтобы искать контейнер средства поиска объекты, которые соответствуют заданным пользователями ограничениям. Метод находки должен возвратить массив объектов результата, которые содержат объекты, которые он находит. Объекты результата являются объектами базового типа mlreportgen.finder.Result
. Возврат результатов находки как объекты результата позволяет пользователю вашего средства поиска добавлять результаты в главу отчета или отчета. Смотрите Задают Результат Средства поиска для получения дополнительной информации. Возврат результатов находки как массив MATLAB позволяет вам использовать цикл for, чтобы обработать результаты поиска, например
GrantFinder
find
метод иллюстрирует определение find
метод.
Этот метод находки использует getNodeList
, поисковая служебная функция, что GrantFinder
класс задает (см., Задают Поисковый Служебный метод) искать базу данных предоставления предоставления, которые соответствуют ограничениям значения свойства, заданным Properties
средства поиска свойство.
getNodeList
функционируйте устанавливает внутреннее свойство под названием NodeList
к результату его поиска. Результатом является Java DOM NodeList
объект (NodeList
) это содержит результаты поиска как список Java элементы DOM (Element
).
find
метод затем преобразует этот список узлов в массив объектов результата типа GrantResult
. Это использует GrantResult
конструктор, чтобы создать объект результата предоставления из Java DOM Element
объект, который содержит данные о предоставлении.
Define hasNext
и next
Методы
Ваше определение класса средства поиска должно задать hasNext
и next
методы. На его первом вызове, вашем hasNext
метод должен создать очередь результатов поиска и возвратить true, если очередь не пуста. На последующих вызовах hasNext
метод должен возвратить true
если очередь пуста, false
в противном случае. Ваш next
метод должен возвратить первый результат в очередь на ее первом вызове, следующий результат, на ее следующем вызове, и так далее, пока очередь не пуста.
Эти методы предназначаются, чтобы позволить клиенту вашего средства поиска использовать while
MATLAB цикл, чтобы искать контейнер вашего средства поиска, например,
GrantFinder
класс иллюстрирует hasNext
метод.
Этот метод сначала проверяет, создал ли он уже поисковую очередь, как обозначено IsIterating
средства поиска свойство. Если очередь уже существует и не пуста, этот метод возвращает
true
. если очередь существует и пуста, этот метод возвращает false
. Если очередь еще не существует (т.е. это - первый вызов метода), hasNext
метод создает очередь результата можно следующим образом. Во-первых, это использует свой внутренний getNodeList
метод, чтобы получить предоставления, которые соответствуют критериям поиска, заданным Properties
средства поиска свойство.
getNodeList
метод устанавливает внутреннее свойство средства поиска под названием NodeCount
к количеству найденных результатов. Если NodeCount
больше нуля, hasNext
метод устанавливает внутреннее свойство под названием NextNodeIndex
к 1. next
средства поиска метод использует это свойство сохранить состояние поисковой очереди, которая является следующим элементом в очереди. Наконец, если очередь не первоначально пуста, средство поиска возвращает
true
; в противном случае, false
.
GrantFinder
next
метод работает с очередью, созданной hasNext
метод.
Задайте поисковый служебный метод
find
вашего средства поиска и
hasNext
методы должны искать контейнер вашего средства поиска объекты, которые удовлетворяют поисковым ограничениям. Необходимо рассмотреть определение поисковой утилиты, которую могут использовать оба метода. Например, GrantFinder
hasNext
и next
методы оба делегата, ищущие на внутреннюю утилиту под названием getNodeList
. getNodeList
метод в свою очередь делегирует поиск к API поиска XML-документа под названием XPath
(см. пример XPath).
Создайте InvalidPropertyNames
Свойство
Ваше средство поиска должно задать свойство под названием InvalidPropertyNames
это задает свойства объектов, которые не могут использоваться, чтобы ограничить поиск. mlreportgen.finder.Finder
базовый класс использует это свойство проверить что заданные пользователями поисковые свойства, заданные Properties
вашего средства поиска свойство допустимо. В противном случае базовый класс выдает ошибку. Другими словами, если клиент устанавливает
Properties
вашего средства поиска свойство к недопустимым свойствам, базовый класс выдает ошибку. Таким образом основное средство поиска API Отчета обрабатывает проверку валидности свойства ваше средство поиска.
Если ваше средство поиска может использовать какое-либо поисковое свойство объекта в качестве поискового ограничения, это должно установить InvalidPropertyNames
пустое свойство. Например, GrantFinder
может обработать любое свойство предоставления. Это поэтому устанавливает это пустое свойство:
Задайте reset
Метод
Средство поиска должно смочь поддержать несколько поисковых запросов, чтобы избежать потребности создать средство поиска для каждого поиска. Поэтому основной класс средства поиска API Отчета обеспечивает ваш класс средства поиска, чтобы задать reset
метод, который сбрасывает переменные, используемые поисковой логикой вашего средства поиска, например,
Если подходящее определение не существует, необходимо создать класс, чтобы задать объекты результата, возвращенные средством поиска. Этот раздел показывает, как задать объект результата средства поиска. Это использует класс под названием GrantResult
как пример. GrantResult
класс задает результаты, возвращенные GrantFinder
класс, используемый в качестве примера в разделе Define a Finder. GrantResult.m
файл, который сопровождает этот скрипт, содержит код для GrantResult
класс. Определение результата средства поиска влечет за собой следующие задачи.
Задайте базовый класс результата
Задайте mlreportgen.finder.Result
как базовый класс для вашего класса результата, например,
Задайте Object
Свойство
Задайте свойство под названием Object
то, что клиенты вашего объекта результата могут использовать, чтобы получить доступ к найденному объекту, который содержит ваш объект результата. Задайте protected
как SetAccess
значение Object
вашего средства поиска свойство. Это гарантирует, что только ваш результат может задать найденный объект, который он содержит.
Ваш конструктор результата должен установить найденный объект как значение его Object
свойство. Ваш конструктор результата может использовать конструктора базового класса, чтобы выполнить эту задачу, например,
Отсоедините найденные свойства объектов
Object
вашего результата свойство позволяет клиенту получать доступ к найденному объекту и поэтому его свойствам. Однако доступ к свойствам может требовать дополнительного кода или специализированных знаний. Можно хотеть отсоединить некоторых или все свойства найденного объекта как свойства объекта результата. Например,
GrantResult
класс отсоединяет следующее подмножество свойств предоставления.
Это сохраняет клиент объекта результата средства поиска предоставления от необходимости извлечь эти свойства самой. Конструктор вашего результата должен извлечь значения свойств, которые будут отсоединены, и установил соответствующие свойства результата на извлеченные значения, например,
Обратите внимание на то, что GrantResult
объединения некоторые свойства предоставления в одно отсоединенное свойство. Например, это отсоединяет InstCity
предоставления,
InstState
, InstPostalCode
, и InstCountry
свойства в одно свойство результата под названием Location
.
В этом примере конструктор использует внутренние методы, чтобы извлечь свойства предоставления из объекта предоставления, который является Java DOM Element
объект, например,
Задайте getReporter
Метод
Необходимо задать getReporter метод для объекта результата, который возвращается, генератор отчетов возражают, что отчеты относительно найденного объекта, что объект результата содержит. Этот метод позволяет клиенту вашего средства поиска сообщать относительно результата операции находки просто путем добавления результата в Report
, Section
, или Chapter
объект. Например,
Отчет или add
главы метод знает, что объект результата должен иметь
getReporter
метод, который возвращает генератор отчетов, который форматирует данные результат, содержит. Таким образом, если вы добавляете объект результата в отчет или главу, add
метод вызывает getReporter
результата метод, чтобы получить генератор отчетов результата и добавляет генератор отчетов результата в отчет или генератор отчетов, заставляя данные о результате быть отформатированным и включенным в отчет.
GrantResult
определение класса задает getReporter
метод, который возвращает настроенную версию API Отчета mlreportgen.report.BaseTable
генератор отчетов. BaseTable
генератор отчетов генерирует таблицу с пронумерованным заголовком. GrantResult
класс настраивает BaseTable
генератор отчетов, чтобы сгенерировать таблицу свойств предоставления, например,
Следующий код показывает как GrantResult
класс настраивает BaseReporter
сгенерировать пронумерованную таблицу свойств предоставления:
Этот скрипт показывает, как использовать средство поиска, чтобы сгенерировать отчет. Этот скрипт использует пример GrantFinder, используемый в разделе Define a Finder, чтобы сгенерировать отчет PDF относительно предоставлений NEH к учреждениям в выбранных состояниях от 2 010 до 2012. Скрипт выполняет следующие задачи.
Импортируйте API генератора отчетов
Импортируйте классы, включенные в API Отчета MATLAB Report Generator. Импорт классов позволяет скрипту использовать дисквалифицированный (т.е. сокращенный) имена, чтобы относиться к классам.
import mlreportgen.report.* import mlreportgen.dom.*
Создайте контейнер отчета
Создайте контейнер PDF для отчета, с помощью API Отчета mlreportgen.report.Report
класс. Обратите внимание на то, что, потому что скрипт импортирует API Отчета, он может относиться к классу своим неполным именем.
rpt = Report('grant', 'pdf');
Создайте титульный лист отчета
Добавьте титульный лист в отчет, с помощью API Отчета TitlePage
класс.
add(rpt, TitlePage( ... 'Title', 'NEH Grants', ... 'Subtitle', 'By State from 2010-2012', ... 'Image', 'neh_logo.jpg', ... 'Author', 'John Doe' ... ));
Создайте оглавление отчета
Добавьте оглавление, с помощью API Отчета TableOfContents
класс.
add(rpt, TableOfContents);
Найдите данные об отчете
Используйте массив структур, чтобы задать состояния, которые будут включены в этот отчет. Каждая структура содержит данные для определенного состояния:
Name
: имя состояния
PostalCode
: состояние, почтовое (zip) код
Grants
: предоставления, сделанные к учреждениям в состоянии. Это поле первоначально пусто.
NGrants
: количество предоставлений, сделанных к учреждениям в этом состоянии (первоначально пустой)
states = struct( ... 'Name', {'California', 'Massachusetts', 'New York'}, ... 'PostalCode', {'CA', 'MA', 'NY'}, ... 'Grants', cell(1,3), ... 'NGrants', cell(1,3) ... );
Используйте средство поиска предоставления, чтобы заполнить Grants
и NGrants
поля структур состояния. Создайте средство поиска предоставления.
f = GrantFinder;
Цикл через массив состояния. Для каждого состояния используйте Properties
средства поиска свойство ограничить поиск грантов, предоставленных состоянию. Используйте эти свойства предоставления ограничить поиск:
InstState
: Задает индекс состояния, в который учреждение, которое получило предоставление, расположен.
YearAwarded
: Задает год, в котором был предоставлен грант.
Средство поиска обрабатывает значения свойств как регулярные выражения. Используйте этот факт, чтобы указать диапазон значений, 2010-2012, как значение YearAwarded
свойство.
n = numel(states); for i = 1:n f.Properties = [ {'InstState', states(i).PostalCode}, ... {'YearAwarded', '201[0-2]'}]; states(i).Grants = find(f); states(i).NGrants = numel(states(i).Grants); end
Создайте главу сводных данных предоставления
Создайте сводные данные предоставления как первую главу отчета. Глава сводных данных предоставления содержит заголовок и сводную таблицу предоставления. Каждая строка таблицы перечисляет общее количество предоставлений и общей суммы денег, присужденных учреждениям в состоянии в течение лет 2010-2012. Состояния появляются в таблице в порядке убывания количества предоставлений. Каждое состояние связывается гиперссылками к главе, которая детализирует гранты, предоставленные ему.
Создайте итоговый контейнер главы
Запустите путем создания контейнера главы..
ch = Chapter('Title', 'Grant Summary');
Создайте содержимое сводной таблицы предоставления
Запустите путем создания средства форматирования валюты Java. Используйте этот объект отформатировать сумму в долларах грантов, предоставленных состоянию.
currencyFormatter = java.text.NumberFormat.getCurrencyInstance();
Создайте массив ячеек, содержащий содержимое табличного заголовка.
header = {'State', 'Grants Awarded', 'Amount Awarded'};
Предварительно выделите массив ячеек, чтобы содержать табличное содержимое тела. Массив ячеек имеет строки и столбцы Rx3, где R является количеством состояний, и 3 количество итоговых элементов, о которых сообщают для каждого состояния.
body = cell(numel(states), 3);
Сортировка массива состояний количеством грантов, предоставленных им, с помощью sort
MATLAB функция.
sort
функция возвращает ind
, массив индексов к массиву состояний. Первый индекс ind
массив является индексом состояния с большинством предоставлений, вторым, со вторым самым большим количеством предоставлений, и т.д.
[~, ind] = sort([states.NGrants], 'descend');
Цикл через состояния количеством предоставлений, заполняя итоговую информацию для каждого состояния. Используйте переменную, rowIdx
, как индекс к строке массива ячеек, соответствующей текущему состоянию.
rowIdx = 0;
Следующая линия перестраивает states
массив в порядке полученных предоставлений и создает for
цикл, который присваивает каждую структуру в отсортированном states
массив к переменной state
на каждой итерации цикла.
for state = states(ind)
Обновите индекс строки, чтобы указать на строку массива ячеек, соответствующую текущему состоянию.
rowIdx = rowIdx+1;
Скрипт вводит гиперссылку на главу деталей предоставления для состояния как первая запись в таблице для состояния, например,
Следующая линия использует InternalLink
DOM конструктор, чтобы создать гиперссылку.
InternalLink
конструктор берет два аргумента, ID цели ссылки и текст гиперссылки. Скрипт использует индекс текущего состояния в качестве ID цели ссылки и имени состояния как текст ссылки. Позже, когда скрипт создает главу деталей предоставления, он вставляет цель ссылки в заголовок главы, ID которого является индексом состояния. Это завершает создание гиперссылки.
body(rowIdx, 1) = {InternalLink(state.PostalCode, state.Name)};
Присвойте общий номер предоставлений на это состояние к второму элементу в его строке массива ячеек.
body(rowIdx, 2) = {state.NGrants};
Вычислите общую сумму, присужденную этому состоянию.
totalAwarded = 0; for grant = state.Grants totalAwarded = totalAwarded + str2double(grant.AwardAmount); end
Используйте средство форматирования валюты, чтобы отформатировать общую сумму как сумму в долларах, например,
и присвойте результат форматирования как третий и итоговый элемент в массиве ячеек для этого состояния.
body(rowIdx,3) = {char(currencyFormatter.format(totalAwarded))};
end
Чтобы составить сводную таблицу, передайте ячейку заголовка и массивы ячейки основной области конструктору mlreportgen.dom.FormalTable
объект.
table = FormalTable(header, body);
Формальная таблица является таблицей, которая имеет заголовок и тело. FormalTable
конструктор берет два аргумента: массив ячеек, который задает содержимое заголовка таблицы и массива ячеек, который задает содержимое его тела. Конструктор преобразует содержимое массива ячеек в TableRow
DOM и
TableEntry
объекты, которые задают таблицу, избавляя скрипт от необходимости создать необходимые объекты таблицы самой.
Отформатируйте сводную таблицу предоставления
На данном этапе сводная таблица выглядит так:
Это не очень читаемо. Заголовок имеет тот же формат как тело, и столбцы не расположены с интервалами независимо.
В следующих шагах скрипт настраивает форматирование текста заголовка, чтобы выглядеть так:
Сначала скрипт задает ширину и выравнивание столбцов таблицы, с помощью TableColSpecGroup
DOM объект.
TableColSpecGroup
объект задает формат группы столбцов. Сводная таблица имеет только одну группу столбцов, таким образом, скрипт должен создать только один TableColSpecGroup
объект.
grp = TableColSpecGroup;
TableColSpecGroup
объект позволяет скрипту задать стиль по умолчанию столбцов таблицы. Скрипт задает 1.5in
как ширина по умолчанию столбцов и выравнивания по центру как выравнивание столбца по умолчанию.
grp.Style = {HAlign('center'), Width('1.5in')};
Скрипт использует TableColSpec
возразите, чтобы заменить выравнивание столбца по умолчанию для первого столбца.
specs(1) = TableColSpec;
specs(1).Style = {HAlign('left')};
grp.ColSpecs = specs;
table.ColSpecGroups = grp;
Обратите внимание, что скрипт мог использовать целые три TableColSpec
объекты, один для каждого столбца таблицы, чтобы заменить стили столбца группы. Первый TableColSpec
объект применяется к первому столбцу, второму к второму столбцу, и т.д. Скрипт должен присвоить только один объект спецификации столбца группе, потому что это заменяет стиль по умолчанию только для первого столбца. Однако, если бы это должно было изменить только третий столбец, это должно было бы присвоить три объекта спецификации столбца, оставив Style
свойство первых двух пустых объектов спецификации столбца.
Стиль таблицы по умолчанию переполняет записи таблицы. Таким образом, скрипт использует InnerMargin
DOM объект формата, чтобы создать некоторое пространство выше записей, чтобы разделить их от записей в строке выше их.
InnerMargin
объект создает пространство (внутреннее поле) между объектом документа и объектом, который содержит его, например, между текстом в записи таблицы и границами записи таблицы. InnerMargin
конструктор опционально берет четыре аргумента, левых, право, верхнюю часть, нижняя часть внутренние поля объекта документа.
Использование скрипта этот конструктор, чтобы создать главный внутренний граничный формат 3 точек. Это затем присваивает этот формат стилю записей в разделе тела сводной таблицы.
table.Body.TableEntriesStyle = {InnerMargin('0pt', '0pt', '3pt', '0pt')};
Наконец скрипт форматирует табличный заголовок, чтобы состоять из полужирного, белого текста на сером фоне:
table.Header.row(1).Style = {Bold, Color('white'), BackgroundColor('gray')};
Добавьте итоговую главу в отчет
add(ch, table); add(rpt, ch);
Создайте главы деталей предоставления
Цикл через структуры состояния.
for state = states
Поскольку каждое состояние создает главу, чтобы содержать детали предоставления состояния. Вставьте цель ссылки в заголовок главы, чтобы служить целью для гиперссылки в сводной таблице в первой главе.
ch = Chapter('Title', {LinkTarget(state.PostalCode), state.Name});
Цикл через предоставление заканчивается для состояния.
for grant = state.Grants
Для каждого результата предоставления добавьте результат в главу.
add(ch, grant);
Результат предоставления имеет getReporter
метод, который возвращает генератор отчетов, который составляет таблицу выбранных свойств предоставления. Глава add
метод предварительно сконфигурирован, чтобы получить генератор отчетов результата и добавить его глава. Таким образом добавление предоставления к главе эквивалентно добавлению таблицы свойства результата к главе, например,
end add(rpt, ch); end
Закройте объект отчета
Закрытие объекта отчета генерирует выходной файл PDF (grant.pdf
) то, что объект отчета задает.
close(rpt);
Отобразите отчет
rptview(rpt);
Источником базы данных, используемой в этом примере, является Национальный фонд гуманитарных наук (NEH). База данных содержит информацию о предоставлениях NEH на период 2010-2019. Это содержит приблизительно 6 000 записей в формате XML. Это доступно в Данных о Предоставлении NEH. Этот пример использует локальную копию XML-файла базы данных, NEH_Grants2010s.xml
.
База данных состоит из Grants
элемент, который содержит набор Grant
элементы, каждый из которых содержит набор элементов данных предоставления. Следующее является извлечением из базы данных, которая иллюстрирует ее структуру: