Документация

Задайте средство поиска

Создание средства поиска влечет за собой создание класса MATLAB, который задает свойства и поведение средства поиска. Следующие разделы объясняют, что шаги должны были создать класс средства поиска. Объяснение использует класс под названием GrantFinder as an example. Код для класса находится в файле, GrantFinder.m, это сопровождает этот скрипт. GrantFinder класс задает средство поиска, способное к нахождению и форматированию грантов, предоставленных американским Национальным фондом гуманитарных наук (NEH).

Создайте скелетный файл определения класса

Используйте редактор MATLAB (не Live Editor), чтобы создать скелетное определение класса для вашего средства поиска, например

Задайте базовый класс средства поиска

Задайте API отчета mlreportgen.finder.Finder класс как базовый класс для вашего средства поиска.

Этот базовый класс задает свойства, которые характерны для средств поиска, включая

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, чтобы обработать результаты поиска, например

GrantFinderfind метод иллюстрирует определение 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.

GrantFindernext метод работает с очередью, созданной 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);

Найдите данные об отчете

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

states = struct( ...
    'Name', {'California', 'Massachusetts', 'New York'}, ...
    'PostalCode', {'CA', 'MA', 'NY'}, ...
    'Grants', cell(1,3), ...
    'NGrants', cell(1,3) ...
    );

Используйте средство поиска предоставления, чтобы заполнить Grants и NGrants поля структур состояния. Создайте средство поиска предоставления.

f = GrantFinder;

Цикл через массив состояния. Для каждого состояния используйте Properties средства поиска свойство ограничить поиск грантов, предоставленных состоянию. Используйте эти свойства предоставления ограничить поиск:

Средство поиска обрабатывает значения свойств как регулярные выражения. Используйте этот факт, чтобы указать диапазон значений, 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). База данных содержит информацию о предоставлениях NEH на период 2010-2019. Это содержит приблизительно 6 000 записей в формате XML. Это доступно в Данных о Предоставлении NEH. Этот пример использует локальную копию XML-файла базы данных, NEH_Grants2010s.xml.

База данных состоит из Grants элемент, который содержит набор Grant элементы, каждый из которых содержит набор элементов данных предоставления. Следующее является извлечением из базы данных, которая иллюстрирует ее структуру: