What Are Reporters?

Reporters are MATLAB^® objects that generate formatted content when added to a MATLAB Report Generator™ Report object. MATLAB Report Generator provides reporters for generating common report components, such as title pages, tables of contents, chapters, subsections, figures, and MATLAB variables values. You can customize the content and appearance of these reporters. You can also create your own reporters. For a list of built-in Report API objects, enter this MATLAB command:

help mlreportgen.report

Reporters and DOM Objects

In addition to reporters, MATLAB Report Generator provides another set of objects for generating report content. These objects are Document Object Model (DOM) objects. They implement a model of a document used by HTML, Word, and other document creation software. The model defines a document as a hierarchy of objects commonly found in documents, such as text strings, paragraphs, images, and tables. The DOM API contains software objects that generate these basic document objects. For a list of the DOM objects, enter this MATLAB command:

help mlreportgen.dom

Reporters, by contrast, create high-level document structures, such as title pages, tables of contents and chapters, that occur in many, but not all types of documents. The advantage of reporters is that a single reporter can create content that would require many DOM objects. However, a report generator program typically requires both DOM and reporter objects. For example, a chapter reporter generates the title and page layout of a report chapter, but not its content. The DOM API provides text, paragraph, table, list, image, and other objects that you can use to create reporter content.

The following MATLAB program illustrates using both reporters and DOM objects to create a PDF report. The program uses a DOM Text object to add a block of text to the chapter. All other objects in this example (Report, TitlePage, TableOfContents, and Chapter) are reporter objects.

rpt = mlreportgen.report.Report("myreport","pdf");
append(rpt,mlreportgen.report.TitlePage("Title","My Report",...
   "Author","Myself"))
append(rpt,mlreportgen.report.TableOfContents)
ch = mlreportgen.report.Chapter("Title","Sample Text");
append(ch,mlreportgen.dom.Text...
   ("Here is sample text using a DOM Text object."))
append(rpt,ch)
close(rpt)
rptview(rpt)

Reporter Elements

A reporter typically includes the following elements:

• Template documents that define the appearance, fixed content, and holes for dynamic content generated by the reporter. A reporter typically provides a set of templates files, one for each supported output type: Word, PDF, and HTML. Each template file contains a library of templates used by the reporter to format its content. For example, the Report API TitlePage reporter uses a template named TitlePage to format a title page. The TitlePage template is stored in the template libraries of its template files. You can modify this template to rearrange or add content to a title page. For information, see Templates.

• Properties that specify the dynamic content generated by the reporter. These properties correspond to holes in the reporter template. A reporter fills the template holes with the values of the corresponding properties.

• MATLAB class that defines the reporter properties and methods you use to create and manipulate the reporter. Reporter class names begin with the prefix, mlreportgen.report. For example, the title page reporter is mlreportgen.report.TitlePage. You can omit the prefix in a MATLAB script or function by inserting this statement at the beginning of the script or function:

  import mlreportgen.report.*

  Likewise, you can include import mlreportgen.dom.* to use short DOM class names.

• Constructor method that creates a reporter object as an instance of the reporter class. The name of the constructor is the same as the name of the class.

• DOM object that contains the content generated by the report. This object is referred to as the implementation of the reporter. Each reporter has a getImpl method that creates the implementation object, which is typically a DOM DocumentPart object.

Using Reporters in a MATLAB Program

To generate content in a report program, follow these steps:

1. Create a Report Object

2. Create an Instance of the Reporter

3. Set the Properties of an Existing Reporter

4. Add the Reporter to a Report

5. Close the Report Object

The example program described in these steps creates a simple document that includes only a title page. However, the steps demonstrate the tasks to create a full report. The full program listing is shown after the step descriptions.

Create a Report Object

Create a Report object (mlreportgen.report.Report) to contain the content generated by the report. The report object uses a DOM Document object to hold content generated by reporters added to the report. This code imports the Report API namespace, which enables the code to use short class names. Then, it creates a PDF report object (rpt).

import mlreportgen.report.*
rpt = Report("myReport","pdf");

Create an Instance of the Reporter

Create an instance of the reporter class, that is, instantiate the reporter, using its constructor. The constructor can also set the properties of the reporter object it creates. For example, this code creates a title page reporter (tp) and sets its Title and Author properties.

tp = TitlePage("Title","My Report","Author","John Smith");

Set the Properties of an Existing Reporter

To set reporter properties after a program has created a reporter, the program can use MATLAB dot notation. For example, this code sets the Subtitle and PubDate properties of a TitlePage reporter (tp).

tp.Subtitle = "on My Project";
tp.PubDate = date;

Add the Reporter to a Report

To generate content using a reporter, a report program must add the reporter to the report object, using the append method of the report object. The append method works by invoking the getImpl method of that reporter. The getImpl method creates the implementation of the reporter. Then, the append method adds the implementation to the DOM Document object that serves as the implementation of the report object. You can also use the append method to add DOM objects to the report. You cannot, however, add another DOM Document to a report.

For example, this code adds the title page reporter (tp) to the report (rpt).

append(rpt,tp)

Close the Report Object

When a report program has finished adding content to a report, it must close the report, using the close method of the report object. Closing a report writes the report content to a document file of the type, such as PDF, specified by the constructor of the report object.

close(rpt)

This code is the complete program for the report, which includes only a title page.

import mlreportgen.report.*

rpt = Report("myReport","pdf");

tp = TitlePage("Title","My Report",...
    "Author","John Smith");
tp.Subtitle = "on My Project";
tp.PubDate = date;

append(rpt,tp)
close(rpt)
rptview(rpt)