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
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)
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.*
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.
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 (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
(rpt
).
import mlreportgen.report.* rpt = Report('myReport','pdf');
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');
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;
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)
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)
mlreportgen.dom.Text
| mlreportgen.report.Report
| mlreportgen.report.TableOfContents
| mlreportgen.report.TitlePage