Format Reports by Defining Functions

Open Live Script

This example shows how you can use the Document Object Model (DOM) and Report APIs to write code that creates and formats a report. Use scripts and custom functions to generate and format your report when you do not want to create and use a custom template. Scripting and functions are useful when you have a simple report that does not require complicated formatting or content layouts. For reports with complicated layouts, writing scripts and functions that generate the content and layout is less efficient and maintainable than using a custom template. See Create HTML and PDF Templates, Create Microsoft Word Templates, and Add Holes in Microsoft Word Templates.

In this example, you execute a custom function that generates a report, rptpop. rptpop defines the document parts, adds text and plots by using additional custom functions, and appends the content to the report.

Inspect the Custom Function

Open the rptpop function to view the code. The function can create an HTML, DOCX, or PDF formatted report.

To start, rptpop creates a report, defines the header and styling, and appends the header to the report by using this code. 

function rptpop(doctype)
%RPTPOP DOM-based report example
%
%   This example is based on the MATLAB example: "Predicting the US
%   Population." That example was generated using MATLAB Publish. This
%   example is generated using the DOM and Report APIs. This example is
%   intended to illustrate a simple use of the APIs, one that does not
%   entail use of holes or templates.
%
%   rptpop() generates an HTML version of the report.
% 
%   rptpop(doctype) generates a report of the specified type:
%   "html", "docx", or "pdf".

%   Copyright MathWorks, 2013-2025

% These statements eliminate the need to qualify the names of DOM and
% Report API objects in this function, e.g., you can refer to
% mlreportgen.report.Report simply as Report.
import mlreportgen.dom.*
import mlreportgen.report.*

if nargin < 1
    doctype = "html";
end

% Create a report.
rpt = Report("population", doctype);

% Create a title for the report.
h = Heading(2, "Predicting the US Population");

% Create a border format object that effectively draws a light gray
% rule under the title.
b = Border();
b.BottomStyle = "single";
b.BottomColor = "LightGray";
b.BottomWidth = "1pt";

% Set the style of the title programmatically to be dark orange with 
% a light gray rule under it.
%
% Note that we could have achieved the same effect
% by defining a title style in a template associated with this object
% and setting the heading's StyleName property to the name of the 
% template-defined style, e.g.,
%
% h.StyleName = 'Title';
%
% This would allow us to change the appearance of the title without 
% having to change the code.
%
% Note also that we append the border and color format objects to the
% heading's existing Style array. This avoids overwriting the
% heading's existing OutlineLevel format.
h.Style = [h.Style {Color("DarkOrange"), b}];

% Append the heading to the document.
append(rpt, h);

To append content to the report without using custom templates, rptpop defines two nested functions, addBodyPara and addPlot. The addBodyPara nested function appends specified string text as a paragraph to the report.

function addBodyPara(rpt, text)
% Format report text and append it to a document.
import mlreportgen.dom.*;
p = Paragraph(text);
p.Style = {FontFamily("Arial"), FontSize("10pt")};
append(rpt, p);
end

The addPlot function appends figures to the report.

function addPlot(rpt)
% Add a snapshot of the current figure to the report with the Figure
% reporter.
import mlreportgen.report.*;

figReporter = Figure(gcf);

% Set image height and width.
figReporter.Scaling = "custom";
figReporter.Width = "5in";
figReporter.Height = "4in";

% Append image to document.
append(rpt, figReporter);

% Delete plot figure window.
delete(gcf);

end

rptpop uses these nested functions to add the text and figures to the report. For example, rptpop adds four paragraphs to the beginning of the report by using this code:

addBodyPara(rpt, "This example shows that using polynomials of " + ...
    "even modest degree to predict the future by extrapolating " + ...
    "data is a risky business.");
addBodyPara(rpt, "This example is older than MATLAB. It started as " + ...
    "an exercise in ""Computer Methods for Mathematical " + ...
    "Computations"", by Forsythe, Malcolm and Moler, published " + ...
    "by Prentice-Hall in 1977.");
addBodyPara(rpt, "Now, MATLAB and Handle Graphics make it " + ...
    "much easier to vary the parameters and see the results, " + ...
    "but the underlying mathematical principles are unchanged.");
addBodyPara(rpt, "Here is the US Census data from 1900 to 2000.");

rptpop then adds the first plot to the report by defining stock data, creating a plot by using MATLAB®, and calling the addPlot function.

% Time interval
t = (1900:10:2000)';

% Population
p = [75.995 91.972 105.711 123.203 131.669 ...
    150.697 179.323 203.212 226.505 249.633 281.422]';

% Plot
plot(t,p,"bo");
axis([1900 2020 0 400]);
title("Population of the U.S. 1900-2000");
ylabel("Millions");

% Add the plot to the document (see addPlot function below).
addPlot(rpt);

rptpop uses similar code to add additional paragraphs and plots to the report.

Execute rptpop and View the Report

To specify the format type of the report, enter the format type in the rptpop function input argument. For example, generate the report as an HTML document by executing this code. 

rptpop("html")

To try other formats, change the function input to "pdf" or "docx".

See Also

| | | |

Topics