What Is a Reporter?
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:
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:
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
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)
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
TitlePagereporter uses a template named
TitlePageto format a title page. The
TitlePagetemplate 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: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
getImplmethod that creates the implementation object, which is typically a DOM
Using Reporters in a MATLAB Program
To generate content in a report program, follow these steps:
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 package, which enables the code
to use short class names. Then, it creates a PDF report object
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
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
PubDate properties of
TitlePage reporter (
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
append method works by invoking the
getImpl method of that reporter. The
getImpl method creates the implementation of the reporter.
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 (
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.
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)