Rptgen PDF
Rptgen PDF
Rptgen PDF
User's Guide
R2015a
How to Contact MathWorks
Phone: 508-647-7000
Getting Started
1
MATLAB Report Generator Product Description . . . . . . . . . 1-2
Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
v
Add Report Content Using Components . . . . . . . . . . . . . . . . . 2-5
Report Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Specify Report Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Create a Title Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Add a Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12
Add Introductory Text to the First Chapter . . . . . . . . . . . . . 2-14
Add an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16
Create the Magic Squares and Their Images . . . . . . . . . . . . 2-21
Create a For Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
Add a Chapter for Each Square . . . . . . . . . . . . . . . . . . . . . 2-24
Determine the Matrix Size . . . . . . . . . . . . . . . . . . . . . . . . . 2-26
Insert the Magic Square Size into the Report . . . . . . . . . . . 2-28
Create the Magic Square . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
Add Display Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32
Display the Magic Square . . . . . . . . . . . . . . . . . . . . . . . . . . 2-34
Set Up a Report
3
Report Setups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Setup Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Setup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Create a Report Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
vi Contents
Save a Report Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
Save a Setup Under Its Existing Name . . . . . . . . . . . . . . . . . 3-9
Save a Setup Under a New Name . . . . . . . . . . . . . . . . . . . . . 3-9
Generate a Report
4
Generate a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Run a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Report Output Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
vii
Report Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
viii Contents
Display Property Name/Property Value Pairs . . . . . . . . . . . . 5-9
Edit Table Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Enter Text into Table Cells . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Add, Replace, and Delete Properties in Tables . . . . . . . . . . 5-13
Format Table Columns, Rows, and Cells . . . . . . . . . . . . . . . 5-14
Zoom and Scroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
Select a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
ix
Header and Footers in Word Conversion Templates . . . . . . 6-10
x Contents
Create Custom Components
7
About Custom Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
xi
Edit, Save, or Delete a Stylesheet . . . . . . . . . . . . . . . . . . . . . . 8-5
Edit a Stylesheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Save a Stylesheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Delete a Stylesheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8
xii Contents
How to Compare XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Select Files to Compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4
Change Comparison Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
XML Comparison Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5
xiii
Document Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
DOM Object Help and Documentation . . . . . . . . . . . . . . . . 13-4
xiv Contents
Use Subforms in a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-31
xv
Create a Link Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-73
Create an External Link . . . . . . . . . . . . . . . . . . . . . . . . . . 13-74
Create an Internal Link . . . . . . . . . . . . . . . . . . . . . . . . . . 13-74
Add Text or Images to Links . . . . . . . . . . . . . . . . . . . . . . . 13-74
xvi Contents
Support for HTML Character Entities . . . . . . . . . . . . . . . 13-104
xvii
1
Getting Started
MATLAB Report Generator lets you create richly formatted Microsoft® Word, HTML, or
PDF reports that present results from your MATLAB programs and applications. You
can use the prebuilt, customizable Word and HTML templates to lay out and format
reports. You can also design and create reports based on your organization’s templates
and standards.
MATLAB Report Generator automatically captures results and figures across multiple
MATLAB functions and presents them within a single report.
Key Features
• Automated reporting from MATLAB
• Report formatting based on Word and HTML templates
• Report designer for creating custom Word, HTML, and PDF reports
• Selective report generation via logical control flow components, such as IF, THEN,
ELSE, and WHILE
• API for forms-based Word and HTML report generation
1-2
MATLAB Code and Results Presentation
In addition, MATLAB provides several methods for presenting MATLAB code and
results, including:
MATLAB enables you to publish your MATLAB code quickly, so that you can describe
and share your code with others, even if they do not have MATLAB software. You can
publish in various formats, including HTML, XML, and LaTeX. If Microsoft Word or
Microsoft PowerPoint® applications are on your Microsoft Windows® system, you can
publish to their formats as well.
On Windows platform, you can use the notebook command to create a Microsoft Word
document that contains text, MATLAB commands, and the output from MATLAB
commands. The document is a record of an interactive MATLAB session annotated with
text or a document embedded with live MATLAB commands and output.
To compare the MATLAB tools for presenting MATLAB code and results and MATLAB
Report Generator, see “Options for Presenting Your Code”.
1-3
1 Getting Started
You can use the Report Explorer graphical interface to create reports without having to
write code.
Using the programmatic approach, you can integrate report generation into analysis and
testing applications. For more information, see “Programmatic Report Creation”.
1-4
Report Creation Workflow
Report Generator
Open
Generate Report Create Add Apply Generate
M-code Explorer setup components stylesheet report
(GUI) file
To practice using this report creation workflow, see “Working with Components”.
1-5
1 Getting Started
1-6
Report Components
Report Components
Using the Report Explorer, you can interactively combine components to create a report
setup (see “Report Setup”) that specifies the content of a particular report or type of
report. You can then run the setup from the Report Explorer or the MATLAB command
line to create instances of the report.
Use a combination of the following types of components in your report setup file, based on
the goals for the report.
Use the Report Explorer to add components to a report setup file and to specify
component properties.
1-7
1 Getting Started
Report Explorer
• From the MATLAB Toolstrip, in the Apps tab, in the Database Connectivity and
Reporting section, click Report Generator.
• In the MATLAB Command Window, enter report.
1-8
Report Explorer
Library pane
• The Outline pane on the left shows the hierarchy of components in currently opened
report setup files. Report components can reside within other report components,
creating parent, child, and sibling relationships.
• The Library pane in the middle lists the objects available in the context of the Outline
pane.
1-9
1 Getting Started
Tip If the Report Explorer window opens with only two panes, one of the panes is hidden.
You can move the vertical boundaries between the panes to reveal any hidden pane, or to
make visible panes wider or narrower.
1-10
Supported Report Formats
Next, the report-generation process converts the XML source to one of these user-
specified report formats:
Note: RTF reports use placeholders (field codes) for dynamically generated content,
such as page numbers or images.
On Windows platforms, to display that content, press Ctrl+A, and then press F9.
On Linux® and Mac platforms, use the field code update interface for the program
that you are using to view the RTF document.
For reports that use the Word Document format, you must have Microsoft Word
software installed on the machine that you use to generate the report.
1-11
2
Note: You do not need to know the MATLAB software to use this example. However,
knowledge of MATLAB is helpful for understanding the MATLAB code that executes
during report generation.
This example includes separate sections for different kinds of report creation and
generation tasks. Each section builds on the previous sections. However, if you want to
work through a later section without having done the previous sections, you can view the
completed report setup file: Magic Squares Report.
2-2
Create a Report Setup File
a To save the report in the current working folder, select Present working
directory from the Directory list.
b Set File format to web (HTML) to create the report as an HTML file.
c In the Report description text box, replace the existing text with the following
text.
Tip Copy and paste this text from the HTML documentation into the Report
Explorer.
Note: When you change a Properties pane field, its background color changes. This
indicates that there are unapplied changes to that field. As soon as you perform any
action with another component, MATLAB Report Generator applies the changes, and
the background color becomes white again.
5 Save your report. Select File > Save As and name your report setup file
magic_squares.rpt.
2-3
2 Create Your First Report
To create the content for the report, see “Add Report Content Using Components” on
page 2-5.
2-4
Add Report Content Using Components
In this section...
“Report Components” on page 2-5
“Specify Report Variables” on page 2-7
“Create a Title Page” on page 2-9
“Add a Chapter” on page 2-12
“Add Introductory Text to the First Chapter” on page 2-14
“Add an Image” on page 2-16
“Create the Magic Squares and Their Images” on page 2-21
“Create a For Loop” on page 2-22
“Add a Chapter for Each Square” on page 2-24
“Determine the Matrix Size” on page 2-26
“Insert the Magic Square Size into the Report” on page 2-28
“Create the Magic Square” on page 2-29
“Add Display Logic” on page 2-32
“Display the Magic Square” on page 2-34
Report Components
Report components specify the information to include in the report. The following figure
shows a sample page from the report that you create in this example, highlighting
components that you use to produce the report.
2-5
2 Create Your First Report
Title Page
component
Chapter
component
Text
component
Text
component
Figure
Snapshot
component
2-6
Add Report Content Using Components
You could require that a user create these variables in the MATLAB workspace before
running the report. However, a better solution is to let the report itself create the
variables, using the Evaluate MATLAB Expression component.
To use the Evaluate MATLAB Expression component to define the report variables.
1 In the Outline pane on the left, select the root component of the report setup.
2 In the Library pane in the middle, under the MATLAB category, select Evaluate
MATLAB Expression.
3 In the Properties pane on the right, click the icon next to Add component to
current report to insert the Evaluate MATLAB Expression component into the
report.
You cannot edit the component information in the Properties pane until you have
added the component to the report.
In the Outline pane, the Eval component appears under the magic_squares report.
2-7
2 Create Your First Report
The icon in the upper left corner of the Eval component indicates that this
component cannot have child components. By default, any components you add with
the Eval component selected are siblings to this component.
The options for the Evaluate MATLAB Expression component appear in the
Properties pane.
4 To exclude the MATLAB code details and its output in this report, clear the Insert
MATLAB expression in report and Display command window output in
report check boxes.
5 In the Expression to evaluate in the base workspace text box, replace the
existing text with the following MATLAB code.
Tip Copy and paste this text from the HTML documentation into the Report
Explorer.
2-8
Add Report Content Using Components
magicSizeVector=[4 8 16 32];
largestDisplayedArray=15;
6 In the Evaluate this expression if there is an error text box, replace the existing
text with the following text.
Tip To execute these commands immediately, in the top right corner of the Report
Explorer, click the Eval Now button. This confirms that your commands are correct,
to reduce the chances of report generation problems.
7 Save the report. Select File > Save.
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
To create a title page for the report, use the Title Page component.
2-9
2 Create Your First Report
2 In the Options pane in the middle, under the Formatting category, double-click
Title Page to add the component to the report.
Because the Eval component icon indicates that this component cannot have
children, the Title Page component is a sibling of the Eval component. Likewise,
the Title Page component also cannot have child components.
Note: To use a Title Page component, you need to have a Chapter component in your
report. You have not yet added a Chapter component, so the Properties pane displays
a message indicating that a chapters is required for the Title Page component to
appear correctly. Because later in this example you add Chapter components to this
report, you can ignore that message.
3 In the Properties pane on the right, use the Main tab to enter the following title
page information.
2-10
Add Report Content Using Components
d In the field to the right of the Custom author field, enter Albrecht Durer.
Albrecht Dürer created an etching that contains a magic square. Your final
report includes an image of that etching.
e Select the Include copyright holder and year check box.
f In the next text box, enter The MathWorks.
g In the second text box, enter 1988.
4 In the Properties pane, click the Abstract tab and then enter the following text:
2-11
2 Create Your First Report
Add a Chapter
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
2-12
Add Report Content Using Components
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
1 In the Outline pane on the left, select the Title Page component.
2 In the Library pane in the middle, under the Formatting category, double-click
Chapter/Subsection.
The Eval, Title Page, and Chapter components are all child components of the
report's top level, and are siblings of one another.
The Chapter component can have child components. The next section explains how
to add child components to this Chapter component.
3 For the custom chapter title, in the Properties pane on the right, enter Magic
Squares Explained.
2-13
2 Create Your First Report
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
Include introductory text in the first chapter by adding the Paragraph and Text
components.
In the Outline pane, the new component appears as a child of the Chapter
component.
2-14
Add Report Content Using Components
3 By default, the Paragraph component inherits its text from its child components.
Add two Text components.
Note: The Text component must have the Paragraph component as its parent.
4 In the Library pane, under the Formatting category, double-click Text.
5 Double-click Text again to add a second component.
The % sign and angle brackets <> indicate to the MATLAB Report Generator
software that this is MATLAB code to evaluate. The command help('magic')
displays information about the MATLAB magic function.
8 In the Outline pane, select the second Text component.
9 In the Text to include in report text box, enter the following text.
Tip Copy and paste this text from the HTML documentation into the Report
Explorer.
2-15
2 Create Your First Report
Add an Image
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
The next steps create an image of Albrecht Dürer and include it in the report.
3 Move the Eval component under the Paragraph component so that the image
follows the introductory text by clicking the down arrow on the toolbar.
2-16
Add Report Content Using Components
4 With the Eval component still selected, do the following in the Properties pane on
the right:
Tip Copy and paste this text from the HTML documentation into the Report
Explorer.
durerData=load('durer.mat','-mat');
figure('Units','Pixels',...
'Position',[200 200 size(durerData.X,2)*.5 size(durerData.X,1)*.5 ]);
image(durerData.X);
colormap(durerData.map);
axis('image');
set(gca,...
'Xtick',[],...
'Ytick',[],...
'Units','normal',...
'Position',[0 0 1 1]);
clear durerData
2-17
2 Create Your First Report
This MATLAB code displays the Dürer etching in a MATLAB figure window.
c In the Evaluate expression if there is an error text box, replace the existing
text with the following text:
This code executes if an error occurs while loading the Dürer etching.
2-18
Add Report Content Using Components
2-19
2 Create Your First Report
Selecting this option specifies not to change the image's on-screen colors for
printing.
2-20
Add Report Content Using Components
The next three steps set up the report to delete the image from the MATLAB
workspace after the image has been added to the report.
8 In the Outline pane, select the Figure Snapshot component.
9 In the Library pane, under the MATLAB category, double-click Evaluate MATLAB
Expression.
10 In the Properties pane:
This code executes if an error occurs while deleting the Dürer etching.
11 Save the report.
2-21
2 Create Your First Report
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
2-22
Add Report Content Using Components
This For Loop component appears inside the Chapter component. However, the
magic squares should be processed after the first chapter, so the for component
should be a sibling of the Chapter component, not a child.
3 In the Outline pane, select the for component.
4 Click the left arrow to make the for component a sibling, not a child, of the
Chapter component.
2-23
2 Create Your First Report
a In the End text box, replace the existing text with the following text:
length(magicSizeVector)
This is the length of the vector that contains the various sizes for the magic
square matrices.
b In the Variable name text box, replace the existing text with the following text:
MAGIC_SQUARE_INDEX
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
2-24
Add Report Content Using Components
Next create a chapter for each square by adding a Chapter component to the report as a
child of the For Loop component. This causes the Report Generator to create a chapter on
each iteration of the For Loop during report generation.
2-25
2 Create Your First Report
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
2-26
Add Report Content Using Components
Extract the size of each magic square matrix from magicSizeVector using an Evaluate
MATLAB Expression component.
1 In the Outline pane on the left, select the bottom Chapter component.
2 In the Library pane in the middle, under the MATLAB category, double-click
Evaluate MATLAB Expression.
3 In the Properties pane on the right:
magic_Square_Size=magicSizeVector(MAGIC_SQUARE_INDEX);
This command extracts the next size for the magic square from the vector
of sizes initialized in the first Eval component of the report. The variable
magic_Square_Size represents the size of the current magic square being
processed.
c In the Evaluate expression if there is an error text box, replace the existing
text with the following:
This code executes if an error occurs while attempting to extract a value from
magicSizeVector.
2-27
2 Create Your First Report
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
Insert the size of the magic square into the report using the Paragraph and Insert
Variable components.
1 In the Outline pane on the left, select the bottom Eval component.
2 In the Library pane in the middle, under the Formatting category, double-click
Paragraph.
Do not change the properties. The variable that contains the size of the magic square
goes in this paragraph.
3 In the Outline pane, select the Paragraph component (below the for component).
2-28
Add Report Content Using Components
4 In the Library pane, under the MATLAB category, double-click Insert Variable.
5 In the Properties pane on the right:
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
2-29
2 Create Your First Report
To create the magic square and display the associated matrix or image, use the Evaluate
MATLAB Expression component.
1 In the Outline pane on the left, select the bottom Paragraph component.
2 In the Library pane in the middle, under the MATLAB category, double-click
Evaluate MATLAB Expression.
Tip Copy and paste this text from the HTML documentation into the Report
Explorer.
mySquare=magic(magic_Square_Size);
clf
imagesc(mySquare);
title(sprintf('Magic Square N=%i',magic_Square_Size))
set(gca,'Ydir','normal');
axis equal;
axis tight;
2-30
Add Report Content Using Components
c In the Evaluate expression if there is an error text box, replace the existing
text with the following:
This code executes if an error occurs while creating and displaying the magic
square.
2-31
2 Create Your First Report
Note: This section builds on the previous tasks described in the step-by-step example
summarized in “Create a MATLAB Report” on page 2-2.
If you have not completed the previous sections of this example, see open the completed
report setup file: Magic Squares Report.
Use Logical If, Logical Then, and Logical Else components to determine whether to
display the magic square as an array of numbers or as an image.
2 On the Library pane in the middle, under the Logical and Flow Control
category, double-click Logical If.
3 On the Properties pane on the right, in the Test Expression text box, replace the
existing text with the following text:
2-32
Add Report Content Using Components
magic_Square_Size<=largestDisplayedArray
To process the result of this Logical If component, create two child components
—Logical Then and Logical Else. If magic_Square_Size is less than or equal
to 15, the matrix variable appears in the report. If magic_Square_Size is greater
than 15, the matrix image appears in the report.
4 On the Outline pane, select the if component.
5 On the Library pane, under Logical and Flow Control, double-click Logical
Else.
6 On the Outline pane, select the if component again.
2-33
2 Create Your First Report
7 On the Library pane, under Logical and Flow Control, double-click Logical
Then.
Note: This section builds on the step-by-step example presented in “Create a MATLAB
Report” on page 2-2.
To see the completed report setup file, open Magic Squares Report.
2-34
Add Report Content Using Components
2 In the Library pane in the middle, under the MATLAB category, double-click Insert
Variable.
3 In the Properties pane on the right:
a In the Variable name text box, enter mySquare, which is the variable that
contains the magic square of the specified size.
b In the Title list, select None.
c In the Array size limit text box, enter 0.
This Variable component displays the magic square matrix, stored in the
mySquare variable.
4 In the Outline pane, select the else component.
5 In the Library pane, under the Handle Graphics category, double-click Figure
Loop.
2-35
2 Create Your First Report
7 In the Library pane, under the Handle Graphics category, double-click Figure
Snapshot.
8 In the Properties pane:
This option changes dark axes colors to light axes colors, and vice versa.
2-36
Add Report Content Using Components
2-37
2 Create Your First Report
2-38
Generate a Report
Generate a Report
Note: This section builds on the step-by-step example presented in “Create a MATLAB
Report” on page 2-2.
To see the completed report setup file, open Magic Squares Report.
On the toolbar, click the Report icon to generate the report. The following dialog box
appears.
1 A Message List window appears, displaying informational and error messages as the
report processes. While the report generates, specify the level of detail you would like
the Message List window to display. Options range from 0 (least detail) to 6 (most
detail). Click the list located under the title bar of the Message List window to choose
an option, as shown here.
Message level 3 (Important messages) is used for the remainder of this example.
2-39
2 Create Your First Report
At the beginning of this example you specified HTML as the output format of this report.
When processing finishes, the MATLAB Web browser opens and displays the report's
HTML file.
2-40
Generate a Report
2-41
3
Set Up a Report
Report Setups
In this section...
“Setup Hierarchy” on page 3-2
“Setup Files” on page 3-2
“Create a Report Setup” on page 3-3
A report setup is a set of MATLAB objects, called components, that specifies the content
and form of a report.
The MATLAB Report Generator provides a setup editor, called the Report Explorer, that
you use to create and edit report setups.
Once you create a setup, you can generate a report from it, using the Report Explorer or
MATLAB commands.
Setup Hierarchy
A report setup has a hierarchical structure that generally mirrors the structure of the
type of report that it defines.
For example, a report typically has a title page and one or more chapters. Each chapter
contains one or more sections, each of which contains one or more paragraphs, figures,
tables, lists, etc. A report setup typically comprises components that correspond to these
structural elements of a report.
Setup Files
The report generator stores setups in files called setup files. The name of a setup
file consists of the name of the setup that it stores followed by the file extension
3-2
Report Setups
.rpt. For example, the name of the setup file for a setup named myreport would be
myreport.rpt.
Once you create a template, you can execute it to generate an instance of the type of
report that it defines.
3-3
3 Set Up a Report
Create a new setup file either interactively from the Report Explorer or
programmatically.
The Outline pane displays a new setup named Unnamed, as a child of the Report
Generator node.
setedit myreport.rpt
3-4
Create a New Setup File
3-5
3 Set Up a Report
To make changes to a saved report setup, you must open its setup file. Open a report
setup either interactively from the Report Explorer or programmatically.
Tip Use the setedit command to obtain a list of all the report setups on the MATLAB
path.
1 If the Report Explorer is not already open, from the MATLAB Toolstrip, in the
Apps tab, in the Database Connectivity and Reporting section, click Report
Generator.
2 In the Report Explorer, in the Outline pane on the left, select the Report
Generator node.
The Library pane in the middle displays a list of all the setup files that exist on the
MATLAB path.
3 In the Library pane, select the setup file that you want to open.
The setup properties dialog box appears in the Properties pane on the right.
4 To open the setup, in the Report Explorer use one of these approaches:
The setup appears in the Outline pane as a child of the Report Generator node.
3-6
Open a Report Setup
Tip Use the setedit command to obtain a list of all the report setups on the MATLAB
path.
1 If the Report Explorer is not already open, from the MATLAB Toolstrip, in the
Apps tab, in the Database Connectivity and Reporting section, click Report
Generator..
2 In the Report Explorer, select File > Open or select the file open button on the
Report Explorer toolbar.
The setup appears in the Outline pane as a child of the Report Generator node.
This command opens the Report Explorer, if it is not already open, and opens the
simple-rpt setup in the Report Explorer.
Tip If a setup exists on the MATLAB path, you do not need to specify its full path when
using the setedit command. Use the setedit command to obtain a list of all the report
setups on the MATLAB path.
The newly opened report appears in the Outline pane as a child of the Report
Generator node.
3-7
3 Set Up a Report
Closing a setup removes the setup from the Report Explorer and from memory.
3-8
Save a Report Setup
3-9
3 Set Up a Report
You can then modify the setup programmatically. For example, the following code loads a
setup into memory, sets its output type to PDF, and generates a report.
setupRoot = rptgen.loadRpt('simple-report');
setupRoot.Format = 'pdf-fop';
setupRoot.execute;
3-10
Insert Components
Insert Components
In this section...
“Point-and-Click Method” on page 3-11
“Drag-and-Drop Method” on page 3-11
“Fix Context Violations” on page 3-11
Point-and-Click Method
1 In the Report Explorer, in the Outline pane, select the parent node of the component
to be inserted. For example, if you are inserting a paragraph into a section, select the
section that will contain the paragraph.
2 In the Library pane, select the type of component that you want to insert in the
report setup.
3 In the Properties pane, select the Add component to current report button.
Drag-and-Drop Method
1 In the Report Explorer, in the Library pane, select the type of component that you
want to insert in the setup.
2 Drag the component from the Library pane into the Outline pane and drop it onto
the parent of the component to be created.
Although you can create an invalid setup hierarchy, you cannot generate a report from
an invalid hierarchy. You must fix the context violations first. For example, move
components from invalid contexts to valid contexts (see “Move Components” on page
3-13).
3-11
3 Set Up a Report
The Properties dialog box for the component appears in the Properties pane.
2 Use the Properties dialog box to set component properties.
You can use MATLAB expressions to compute the value of any string property of a
component. A string property is a property whose value is a string of text. To specify
a MATLAB expression as a string property value, in the Properties dialog box, in the
property edit box, enter %<expr>, where expr is a MATLAB expression that evaluates to
a string.
3-12
Move Components
Move Components
In this section...
“Point-and-Click Method” on page 3-13
“Drag-and-Drop Method” on page 3-14
Point-and-Click Method
1 In the Report Explorer, in the Outline pane, select the component that you want to
move.
2 Reposition the component in the setup hierarchy, using one of these approaches:
Note: The move buttons and commands are enabled only if they are valid in the
context of the component to be moved. For example, if a component cannot move
further to the right in the hierarchy, the Move Right button is disabled.
The following table summarizes the available move buttons and commands.
3-13
3 Set Up a Report
Drag-and-Drop Method
1 In the Report Explorer, in the Outline pane, select the component that you want to
move.
2 Drag the component and drop it on the component that you want to be its parent.
3-14
Delete Components
Delete Components
1 In the Report Explorer, in the Outline pane, select the component that you want to
delete.
2 Delete the component, using one of these approaches:
3-15
3 Set Up a Report
Deactivate Components
You can deactivate any component in a report setup. Deactivating a component causes it
to be skipped during generation of a report.
Deactivating components can be useful for debugging setups. For example, you can
deactivate a component that you suspect is causing an error or you can activate only the
components you want to debug, thereby cutting the time required to verify a fix.
1 In the Report Explorer, in the Outline pane, select the component that you want to
deactivate (or reactivate).
2 Select the appropriate Activate/Deactivate Component option from either the
Edit menu or from the context menu of the component.
3-16
Send Components to the MATLAB Workspace
Sending components to the workspace can be useful for creating or debugging MATLAB
programs that create report setups and generate reports from them.
1 In the Report Explorer, in the Outline pane, select the component that you want to
send to the workspace.
2 From the context menu of the component, select Send to Workspace.
3-17
4
Generate a Report
Generate a Report
In this section...
“Run a Report” on page 4-2
“Report Output Options” on page 4-2
Run a Report
You can generate a MATLAB Report Generator report using one of these methods:
• In the Report Explorer Outline pane, select a report and do one of the following
actions:
•
In the Report Explorer toolbar, click the Report button .
• Press CTL+R.
• Select File > Report.
• From the MATLAB command line, use the report command. For example, to print
the system1_description report in PDF format, use:
4-2
Generate a Report
4-3
4 Generate a Report
In this section...
“Report Options Dialog Box” on page 4-4
“Report Output Format” on page 4-5
“PDF Stylesheets” on page 4-8
“Web Stylesheets” on page 4-8
“RTF (DSSSL Print) and Word Stylesheets” on page 4-9
“Report Generation Processing” on page 4-10
“Location of Report Output File” on page 4-11
“Report Description” on page 4-12
The Report Options dialog box in the Properties (right hand) pane of the Report Explorer.
4-4
Select Report Generation Options
To set defaults for report generation options that you can override with the Report
Options dialog box or with individual components, use the Report Generator Preferences
pane. For details, see “Report Generation Preferences” on page 4-13.
4-5
4 Generate a Report
If you use a template, then from the list of templates, you can specify a template other
than the default template. Each output format that does not use a template has a default
stylesheet associated with it. Specify the stylesheet in the text box next to the File
format text box.
For more information about using templates for report generation, see “Generate a
Report Using a Template”.
If you do not use a template, then you can specify in the Stylesheet field, you can specify
a stylesheet.
4-6
Select Report Generation Options
Tip To create and use customized styles, see “Create a New Stylesheet”.
PDF reports only support bitmap (.bmp), .jpeg (.jpg), and Scalable Vector Graphics
(.svg).
The SVG format is only supported for Simulink models and Stateflow charts. For
example, MATLAB figures do not display in SVG when you select the SVG format for
PDF reports.
RTF reports use placeholders (field codes) for dynamically generated content, such as
page numbers or images.
On Windows platforms, to display that content, press Ctrl-A, and then press F9.
On Linux and Mac platforms, use the field code update interface for the program that
you are using to view the RTF document.
In the Report Generator Preferences pane, use the Format ID preference to specify the
default output format for reports.
Stylesheets
For each output format, you can choose from several stylesheets for each report output
format. For details, see:
4-7
4 Generate a Report
Note: Some Web and Print stylesheets include an automatically generated list of titles,
which includes table titles and figures with titles.
PDF Stylesheets
Web Stylesheets
4-8
Select Report Generation Options
4-9
4 Generate a Report
Option Purpose
View report after View the report automatically. When report generation
generation finishes, the viewer associated with the report output
format displays the report.
4-10
Select Report Generation Options
Option Purpose
contents. If a report requires multiple compilations, the
processing can be quite time-consuming.
Folder
In the Report Explorer, in the Report Options dialog box, use the Directory field to
specify the name of the folder in which to store the generated report file. Specify a folder
to which you have write privileges.
Folder Option
The same folder as the report Same as setup file
setup file
The current working folder Present working directory
Temporary folder Temporary directory
Another folder Custom.
You can use %<VariableName> notation to specify a folder in the Custom text box. For
more information, see “%<VariableName> Notation” on the Text component reference
page.
4-11
4 Generate a Report
In the Report Explorer, in the Report Options dialog box, use the Filename field to
specify a file name for the report file. Select one of the following options.
You can use %<VariableName> notation to specify a file name in the Custom text
box. For more information, see “%<VariableName> Notation” on the Text component
reference page.
To maintain the previous version of the setup file when you save updates to the setup
file, select If report already exists, increment to prevent overwriting.
Images are placed in a folder with the same name as the report file. For example,
testreport.html images are placed in a folder named testreport_files.
Report Description
To record notes and comments about your report setup, use the Report Description
field. This text that you enter appears in the Properties pane when you select a report
setup file in the Outline pane.
4-12
Report Generation Preferences
In this section...
“Report Generator Preferences Pane” on page 4-13
“File Format and Extension” on page 4-14
“Image Formats” on page 4-15
“Report Viewing” on page 4-15
“Reset to Defaults” on page 4-16
To specify report generation options for a specific report, in the Report Explorer, use the
Report Options dialog box. For details, see “Select Report Generation Options” on page
4-4.
To open the Report Generator Preferences pane, use one of these approaches:
4-13
4 Generate a Report
Note: For reports that use the Word Document format, you must have Microsoft Word
installed on the machine that you use to generate the report.
4-14
Report Generation Preferences
The Extension preference reflects the standard file extension for the file format
specified with the Format ID preference. You can change the extension.
Image Formats
To set the default image formats associated with the output format for a report, use the
following preferences.
Preference Purpose
Simulink Images Specify the format for Simulink images to include in the
report.
Stateflow Images Specify the format for Stateflow charts to include in the
report.
HG Images Specify the format for Handle Graphics images to
include in the report.
Note: The default preferences for image formats should work in most viewing
environments. However, some image formats do not display in some viewing
environments.
Report Viewing
To control how you view a generated report, you can set the following preferences.
Preference Purpose
View command Specify the MATLAB command you want to use to view
the report.
4-15
4 Generate a Report
Preference Purpose
Visible in Report Deselect this check box to make the current output
Explorer format unavailable in the Report Explorer. For example,
if your specified report format is Word document and
you deselect this check box, then the Microsoft Word
document format is no longer available for reports
created using the Report Explorer.
Animate Report Explorer Select this check box if you want components in the
when generating reports Outline pane to be animated as the report generates.
This box is selected by default.
Reset to Defaults
To reset all of the preferences in the Output Format Options section of the Report
Generator Preferences pane, click Reset to Defaults.
The Reset to Defaults button does not change the Animate Report Explorer when
generating reports preference.
4-16
Change Report Locale
Alternatively, you can change the language directly in Java from the MATLAB command
line. The following example sets the language to Italian:
java.util.Locale.setDefault(java.util.Locale.ITALY)
Alternatively, you can set the preferred language directly in your .rpt file:
This displays the properties of the report, which are stored in the variable ans.
Access the report's Language property from the command line through this variable.
By default, Language is auto, which indicates that the system's default language is
in use.
2 Override the default value of Language by setting this property to your desired
language; for example, en for English or it for Italian.
4-17
4 Generate a Report
In this section...
“Why Convert XML Documents?” on page 4-18
“Convert XML Documents Using the Report Explorer” on page 4-18
“Convert XML Documents Using the Command Line” on page 4-20
“Edit XML Source Files” on page 4-20
Note: The report-generation process can only convert XML source files created by the
latest version of the software.
The Convert Source File Properties pane appears. All XML files in your current
folder appear in the Options pane in the middle.
4-18
Convert XML Documents to Different File Formats
2 Select your XML source file using one of the following options:
• Click Browse in the Properties pane on the right to browse to the location of your
XML source.
• Double-click a file name in the Options pane in the middle to automatically enter
it into the Source file field in the Properties pane.
3 Select your output format and stylesheet:
For more information about available formats and predefined stylesheets, see
“Report Output Format”.
4-19
4 Generate a Report
4-20
Create a Report Log File
• As a debugger
• As a reference to a report setup file
• To share information about a report setup file through email
To generate a log file, click File > Log File. An HTML version of the log file with the
name <report_template_file_name_log>.html is saved in the same folder as the
report setup file.
4-21
4 Generate a Report
To generate a MATLAB file, load a report setup file into the Report Explorer and click
File > Generate MATLAB File. After the MATLAB file generates, it opens in the
MATLAB Editor. The filename for the generated file is the file name of the report setup
file , preceded by “build.”
This example generates a MATLAB file from the figloop_tutorial.rpt report setup
file, which is part of the MATLAB Report Generator software. The example then uses the
report function to generate a report from the MATLAB file. For more information about
this function, see the report reference page.
1 Start the Report Explorer by entering report in the MATLAB Command Window.
2 In the Options pane in the middle, double-click figloop_tutorial.rpt to open its
report setup file.
3 In the Outline pane on the left, click Report - figloop_tutorial.rpt to select
it.
4 In the Report Explorer menu bar, click File > Generate MATLAB File.
4-22
Generate MATLAB Code from Report Setup File
5 To generate the figloop_tutorial report from this MATLAB file, run the
following command in the MATLAB Command Window:
report(buildfigloop_tutorial);
The MATLAB Report Generator software runs and displays the report.
4-23
4 Generate a Report
4-24
Troubleshooting Report Generation Issues
Memory Usage
By default, the MATLAB software sets a limit of 100 MB on the amount of memory the
Oracle Java Virtual Machine (JVM™) software can allocate. The memory that the report
generation process uses to build a document must fit within this limit. If you are having
trouble processing large reports, it might be helpful to increase the amount of memory
that MATLAB Report Generator and Simulink Report Generator software can allocate.
See the following sections for more information.
One way to increase the amount of JVM memory available to the MATLAB Report
Generator and Simulink Report Generator software is to run the MATLAB software with
-nodesktop mode enabled.
To increase the amount of JVM memory available by increasing the MATLAB JVM
memory allocation limit, from the MATLAB Toolstrip, in the Home tab, in the
Environment section, select Preferences. Use the General > Java Heap Memory
dialog box.
4-25
5
Components
Components are MATLAB objects that specify the content of a report. Add components
to specify the types of content that commonly occur in reports. The MATLAB Report
Generator provides a set of components for specifying the types of content that commonly
occur in MATLAB-based reports. The Simulink Report Generator provides additional
components to facilitate generation of reports from Simulink models. You can also create
custom components to handle content specific to your application.
Using the Report Explorer, you can interactively combine components to create a report
setup that specifies the content of a particular report or type of report. For general
information about working with components, see:
• “Insert Components”
• “Set Component Properties”
Use a combination of the following types of components in your report setup file, based on
your goals for the report.
5-2
Components
Component Formatting
When you generate a report, in the Report Options dialog box, in the File format field
you specify the type of report output you want. For example, you can generate a report in
PDF, HTML, or Microsoft Word format.
For each format, you can choose to apply styles from either of these style definition
sources:
The output format and the associated template or stylesheet that you select for a report
determines most aspects of the formatting of the generated report. For example, a report
template or stylesheet typically uses different font sizes for chapter titles and section
titles. For details, see “Report Output Format”.
Several components include properties that you can set to specify formatting details for
that specific instance of a component. For example, for the MATLAB Property Table,
you can specify formatting such as whether to display table borders or the alignment of
text in table cells.
5-3
5 Add Content with Components
Component Usage
Title Page Generate a title page for a report.
Chapter/Subsection Parent components that generate the content of a chapter or
chapter subsection.
Paragraph Specify the content and text format of a paragraph of text. Can
serve as the parent of one or more text components, enabling use
of multiple text formats (for example, bold, regular, or italic) in
the same paragraph.
Text Format strings of generated text.
List Generate a list from a cell array of numbers or strings or parent
components (for example, Paragraph components) that specify the
items in a list. You can create multilevel lists by embedding list
components within list components.
Link Generate a hyperlink from one location in a report to another or
to an external location on the user’s file system or the Worldwide
Web.
Image Insert an image into a report.
Array-Based Table Generate a table from a cell array of numbers or strings.
Table Parent a table body component. See “Table Formatting
Components”.
5-4
Table Formatting Components
Component Usage
Table Parent a table body component. Can also parent column
specification components and a table header and a table
footer component. Specifies properties of the table as a whole
(for example, its title, number of columns, and border).
Table Body Parent the rows that make up the table body. Specifies the
default vertical alignment of entries in a table body.
Table Column Specify attributes of a table column, such as its width and
Specification borders and the default horizontal alignment of column
entries.
Table Entry Parent a component that determines a table entry’s content,
such as a paragraph, image, list, or another table component.
Specifies attributes of a table entry, such as the number of
rows and columns that it spans.
Table Footer Parent the row components that generate the content of a
table footer.
Table Header Parent the row components that generate the content of a
table header.
Table Row Parent the table entry components that generate the content
of a table row.
Tip Inserting a Table component into a setup also inserts all the descendant components
required to generate a 2x2 table, creating a table template. Edit this template to create a
table that suits your needs.
5-5
5 Add Content with Components
In this section...
“About Property Table Components” on page 5-6
“Open the Example Report Template” on page 5-8
“Examine the Property Table Output” on page 5-8
“Select Object Types” on page 5-9
“Display Property Name/Property Value Pairs” on page 5-9
“Edit Table Titles” on page 5-12
“Enter Text into Table Cells” on page 5-12
“Add, Replace, and Delete Properties in Tables” on page 5-13
“Format Table Columns, Rows, and Cells” on page 5-14
“Zoom and Scroll” on page 5-16
“Select a Table” on page 5-16
5-6
Property Table Components
The component used in this example represents MATLAB Report Generator property
table components, all of which exhibit similar behavior.
5-7
5 Add Content with Components
setedit figloop-tutorial
5-8
Property Table Components
You can select a different object type on which to report in the Object type list in the
Properties pane for the component.
1 In the Properties pane for the Handle Graphics Property Table component, clear the
Split property/value cells check box.
2 Click Edit. The table is now in nonsplit mode. Nonsplit mode supports more than
one property name/property value pair per cell and text.
3 For the property name and property value to appear in adjacent horizontal cells
in the table, select the Split property/value cells check box. The table is now in
5-9
5 Add Content with Components
split mode. Split mode supports only one property name/property value pair per cell.
If more than one property pair appears in a cell, only the first pair appears in the
report; all subsequent pairs are ignored.
Display Options
Property name/property value pairs can appear in cells in several ways. To specify how
a given property name/property value pair appears in a cell, select that field in the table
(for this tutorial, select the Name property). Choose Value from the display options
drop-down list at the bottom of the dialog box. In the selected table row, only the value
appears.
5-10
Property Table Components
Format Options
To specify alignment for text in a given cell, in the toolbar at the bottom of the dialog box
use the four justification buttons.
Select the HandleVisibility table row. Then select the double-justify button (the last
button to the right).
5-11
5 Add Content with Components
To enter text into the HandleVisibility table cell, double-click the cell. A gray box
appears with the label for the cell property.
5-12
Property Table Components
If you type text outside the angle brackets, the text appears as is in the report. Text
inside the table brackets must specify a valid property name. If you enter an invalid
property name, the property name appears in the report without a property value.
1 In the Figure Property Table window, select a table row above which you want add a
new property.
2
Click the Add Row Above Current Cell button
5-13
5 Add Content with Components
b In the Properties Type drop-down list at the upper-right of the dialog box, select
a property type.
c In the Properties list, select the property you want to add.
d Click the << Add button, or double-click the property name. The property
appears in the table row.
Alternatively, if you know the name of the property you want to add, enter the
property name directly into the cell as described in “Enter Text into Table Cells”. For
information about adding new table rows, see “Add and Delete Columns and Rows”.
To replace a property in a cell of a table in split mode, follow the instructions in “Adding
Table Properties” on page 5-13.
Note: You cannot use these steps to delete a property in a cell when the table is in
nonsplit mode.
To add or delete a column or row, select a cell and then click one of the buttons described
in the following table.
Note: You cannot delete a row or column when it is the only row or column in the table.
Button Action
Add column (added to the left of the selected column)
5-14
Property Table Components
Button Action
Delete selected column
Resize Columns
To resize the width of a column, click and drag its vertical borders as needed.
To merge or split table cells, select a row and then click one of the buttons described in
the following table.
Button Action
Merge cells downward
Split cells
1 Place your cursor in a cell and right-click to invoke its context menu.
2 Choose Cell borders > Top, Bottom, Right, or Left to toggle the specified border
on or off.
5-15
5 Add Content with Components
Button Action
Zoom in
Zoom out
You can scroll vertically and horizontally using the table scroll bars.
Select a Table
To display property name/property value pairs, you can select a preset table or use a
custom table.
• A preset table is built-in and formatted. You can select a preset table in the preset
table selection list in the upper-left of the Figure Prop Table window. To apply a
preset table, select the table and click Apply.
• To create a custom table, select a preset table and modify it to fit your needs by
adding and/or deleting rows and properties. You may want to start with the Blank
4x4 preset table.
Note: You cannot save a custom table as a preset table. If you do so, you lose all
changes to the custom table.
5-16
Summary Table Components
In this section...
“About Summary Table Components” on page 5-17
“Open the Example Report Template” on page 5-18
“Select Object Types” on page 5-19
“Add and Remove Properties” on page 5-19
“Set Relative Column Widths” on page 5-20
“Set Object Row Options” on page 5-20
5-17
5 Add Content with Components
The component used in this example represents MATLAB Report Generator summary
table components, all of which exhibit similar behavior
5-18
Summary Table Components
setedit figloop-tutorial
To add a property:
5-19
5 Add Content with Components
Note: After making changes in the Report Explorer, click Apply to make the changes
take effect.
You can define your own properties by entering their names into the Property columns
table using valid variable notation. For more information, see “%<VariableName>
Notation” on the Text component reference documentation.
5-20
Logical and Looping Components
A looping component runs its child components a specified number of times. There are
several looping components, such as logical loops and Handle Graphics loops.
For an example that uses loop components, see “Edit Figure Loop Components”.
5-21
5 Add Content with Components
In this section...
“Figure Loop in a Report” on page 5-22
“Figure Properties” on page 5-23
“Loop on the Current Figure” on page 5-24
“Loop on Visible Figures” on page 5-24
“Loop on Figures with Tags” on page 5-24
“Modify Loop Section Options” on page 5-24
setedit figloop-tutorial
2 To display the Handle Graphics figures, enter:
figloopfigures
The figures Membrane Data, An Application, and Peaks Data appear on the
screen because their visible property is 'on'. The Invisible Membrane Data
and An Invisible Application figures do not appear on screen because their
visible property is 'off'. These invisible figures exist, but they are hidden.
3 In the Report Explorer, in the Outline pane on the left, select the Figure Loop
component called Figure Loop Section 1.
5-22
Edit Figure Loop Components
Figure Properties
Figure properties control which figures appear in the report. Table 1.1 of the figloop-
tutorial report includes a summary of the properties of the figures used in this
tutorial.
5-23
5 Add Content with Components
For this example, do not change these properties. For more information, see “Add,
Replace, and Delete Properties in Tables” on page 5-13.
1 Select the Data figures only (Exclude applications) option to exclude figures
from the loop whose HandleVisibility parameter is 'off'.
2 To generate the report, in the Report Explorer toolbar click the Report button.
In the generated report, scroll down to “Chapter 2 Figures in Report.” The Membrane
Data and Peaks Data figures appear in the generated report.
1 In the Include figures selection list, select the All figures with tags option.
2 In the list of tags, delete membrane.
3 Click Report to generate the report.
5-24
Edit Figure Loop Components
in each loop appear in the report by using the options in the Figure Loop component's
Section Options pane.
• Create Section for Each Object in Loop — Create an individual section for each
object found in the loop, using the object title as the section title. This option is useful
when a loop does not contain a Chapter/Subsection component that organizes the loop
results.
• Display the Object Type in the Section Title — Precede section titles with object
titles. Enable this option by selecting Create section for each object in loop. For
example:
5-25
6
In this section...
“Templates for Report Conversion” on page 6-2
“Custom Templates” on page 6-2
“Custom Component Styles” on page 6-2
“Benefits of Using Templates” on page 6-2
Custom Templates
The MATLAB Report Generator comes with default HTML and Word templates. You can
create customized versions of these templates to meet your report formatting and layout
requirements. You can use a custom template to generate a report. Specify the name of
the custom template in the Report Options dialog box, in the Template field.
• Is faster.
6-2
Report Conversion Templates
• Does not use Java memory to convert report XML content to HTML, Word, or PDF.
Converting report XML content without using a template can cause Java to run out of
memory.
Also, templates allow you to use your knowledge of Word and HTML document
formatting to format reports.
Related Examples
• “Generate a Report Using a Template” on page 6-4
• “Copy a Conversion Template” on page 6-12
• “Customize Microsoft Word Report Styles” on page 6-18
• “Customize Microsoft Word Part Templates” on page 6-21
• “Customize a Microsoft Word Title Page Template” on page 6-30
• “Create a Custom HTML Template” on page 6-36
More About
• “Report Conversion Templates” on page 6-2
• “Conversion Template Contents” on page 6-5
6-3
6 Template-Based Report Formatting
• Unzipped — Generate the report files in a subfolder of the current folder. The
subfolder has the report name.
• Zipped — Package report files in a single compressed file that has the report
name, with a .zip extension.
• Both Zipped and Unzipped
5
In the toolbar, click the Report button ( ).
More About
• “Report Conversion Templates” on page 6-2
6-4
Conversion Template Contents
Default Styles
The default conversion template includes styles that the Report Explorer uses to
format components during report generation. Most styles begin with rg (for example,
rgTitle). Styles for syntax highlighting MATLAB code begin with MWSG, for example,
MWSHKeywords. The default style names and formatting are the same for the Word and
HTML templates, to the extent applicable. For example, page break formatting applies
when you use a Word template, but not an HTML template.
You can modify the built-in styles, but do not delete them. In addition, you can define
your own styles and use them in components that allow you to specify a style, such as the
Paragraph component.
6-5
6 Template-Based Report Formatting
6-6
Conversion Template Contents
6-7
6 Template-Based Report Formatting
6-8
Conversion Template Contents
Part Templates
The conversion templates include template parts to format specific elements of a report.
rgSect4Title
rgSect5Title
rgListTitle List
6-9
6 Template-Based Report Formatting
Part templates include fill-in-the-blanks hole markup. The report converter fills holes
with content that the MATLAB Report Generator generates.
For example, the rgChapter part template in the default Word conversion template
includes an rgChapterTitle hole.
The report converter fills the rgChapterTitle hole with the contents of the Title
property of top-level Chapter/Section components in a report.
You can rearrange or delete holes to change the order in which generated content
appears in the report or to omit content. Do not add holes. If you add holes, the report
converter ignores them.
You can also specify headers and footers for the rgRectoTitlePage,
rgVersoTitlePage, and rgChapter part templates.
6-10
Conversion Template Contents
Related Examples
• “Generate a Report Using a Template” on page 6-4
• “Copy a Conversion Template” on page 6-12
• “Customize Microsoft Word Report Styles” on page 6-18
• “Customize Microsoft Word Part Templates” on page 6-21
• “Customize a Microsoft Word Title Page Template” on page 6-30
More About
• “Report Conversion Templates” on page 6-2
6-11
6 Template-Based Report Formatting
Select a folder that is on the MATLAB path (for example, in the MATLAB folder in
your home folder).
Specify the file name, using the default file extension for a Word template (.dotx).
5 Click Save.
Results
A template you create by copying a template appears in the list of Word or HTML
templates. The initial name of the copy in the list of templates is Copy of ORIGINAL,
where ORIGINAL is the name of the template that you copied. The name in the list is not
the file name you used when you saved the copy.
To change the template name that appears in the list of templates, in the Template
Properties dialog box, specify the name in the Display name field. For details, see “Set
Conversion Template Properties” on page 6-15.
Related Examples
• “Set Conversion Template Properties” on page 6-15
• “Open a Conversion Template” on page 6-14
• “Move a Conversion Template” on page 6-16
• “Delete a Conversion Template” on page 6-17
• “Customize Microsoft Word Report Styles” on page 6-18
• “Customize Microsoft Word Part Templates” on page 6-21
• “Customize a Microsoft Word Title Page Template” on page 6-30
6-12
Copy a Conversion Template
More About
• “Report Conversion Templates” on page 6-2
6-13
6 Template-Based Report Formatting
If you open a default template, you cannot edit it. To edit a template, make a copy of the
default template and open the copy.
To open both the template and the template stylesheet, in the Template Browser click
Open stylesheet.
Related Examples
• “Copy a Conversion Template” on page 6-12
• “Set Conversion Template Properties” on page 6-15
More About
• “Report Conversion Templates” on page 6-2
6-14
Set Conversion Template Properties
Related Examples
• “Copy a Conversion Template” on page 6-12
• “Open a Conversion Template” on page 6-14
More About
• “Report Conversion Templates” on page 6-2
6-15
6 Template-Based Report Formatting
1 In Report Explorer, select Tools > Edit Document Conversion Template. The
Template Browser appears in the Report Explorer.
2 In the Report Explorer, select the template to move.
3 In the Template Browser, select Move template.
4 In the file browser, navigate to the new location for the template file. Enter a file
name, using the appropriate extension for the type of template (.dotx or .htmtx).
5 Click Save. The Path property in the Template Browser shows the new location.
Related Examples
• “Copy a Conversion Template” on page 6-12
• “Open a Conversion Template” on page 6-14
• “Delete a Conversion Template” on page 6-17
More About
• “Report Conversion Templates” on page 6-2
6-16
Delete a Conversion Template
Related Examples
• “Copy a Conversion Template” on page 6-12
• “Open a Conversion Template” on page 6-14
• “Move a Conversion Template” on page 6-16
More About
• “Report Conversion Templates” on page 6-2
6-17
6 Template-Based Report Formatting
You can customize report styles in a custom Word conversion template or add styles to a
custom Word template.
For more information about Word styles, see the Microsoft Word documentation.
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of templates in the middle pane, select the custom template that contains
the style you want to customize.
3 In the Properties pane, click Open stylesheet. The Word Manage Styles dialog
box appears.
4 Use the Manage Styles dialog box to modify or create styles.
Styles that begin with rg (for example, rgParagraph) are the default styles used
for report components. A default style applies to all instances of a component with
which it is associated. (In the Report Explorer, some components allow you to replace
the name of a default style with the name a style that you create. This allows you to
specify different styles for different instances of the same component.)
For details, see “Create Styles in a Microsoft Word Template” on page 6-18.
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
6-18
Customize Microsoft Word Report Styles
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of templates in the middle pane, select a custom template.
3 In the Properties pane, click Open stylesheet.
4 If applicable, select an existing style to use as a starting point for the new style.
5 Click the New Style button.
6 Specify a name for the new style and define the style characteristics. To save the new
style definition, click OK and close the dialog box.
7 In the Manage Styles dialog box, click OK.
8 In Word, save and close the template.
Related Examples
• “Customize Microsoft Word Part Templates” on page 6-21
• “Customize a Microsoft Word Title Page Template” on page 6-30
More About
• “Report Conversion Templates” on page 6-2
6-19
6 Template-Based Report Formatting
6-20
Customize Microsoft Word Part Templates
In this section...
“Custom Word Part Templates” on page 6-21
“Display the Developer Ribbon in Word” on page 6-22
“Customize a Word Conversion Part Template” on page 6-22
“Set Default Text Style for a Hole” on page 6-23
“Distinguish Inline and Block Holes” on page 6-25
“Avoid Changing Block Holes to Inline Holes” on page 6-26
“Delete a Hole” on page 6-26
“Add an Inline Hole” on page 6-28
“Add a Block Hole” on page 6-29
If you delete a hole in a part template, then the generated report does not include the
component data associated with that hole. For example, the rgRectoTitlePage part
template includes an rgAuthor hole. If you delete the rgAuthor hole, then reports
generated with the template do not include the author, even if the report has a Title
Page component that specifies a value for the Author property.
The only kind of holes that you can add to a part template are the holes that the
Report Explorer supports for that part template. For example, for the rgChapter part
template, you can only reinsert rgChapterTitlePrefix, rgChapterTitleNumber,
rgChapterTitle, and rgChapterContent holes. Do not add multiple instances of the
same kind of hole in a part template.
6-21
6 Template-Based Report Formatting
Tip If you do not see Developer check box in the list, set Customize the Ribbon to
Main Tabs.
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of templates in the middle pane, select a custom template.
3 In the Properties pane, click Open template.
4 At the beginning of the template, position the cursor in the first paragraph and click
the Quick Parts button.
5
In the Insert tab, select the Quick Parts button.
6 In the Quick Parts Gallery, select the part template (for example, rgChapter).
7 Edit the copy of the part template. For example, remove a hole by right-clicking and
selecting Remove Content Control.
8 In the template, select the part template, including all of its holes.
9 In the Quick Parts Gallery, select Save Selection to Quick Part Gallery.
6-22
Customize Microsoft Word Part Templates
10 In the Create New Building Block dialog box, set Name to the part template name
(for example, rgChapter) and the Category to mlreportgen. Click OK.
11 In the template, delete the customized part template.
12 Save the main template.
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of templates in the middle pane, select the custom template that has the
hole you want to set the default text style for.
3 In the Template Browser, click Open template.
4
In the Insert tab, select the Quick Parts button.
5 In the Quick Parts Gallery, select the part template that contains the hole (for
example, rgChapter).
6 Right-click in the text area of the hole whose default text style you want to specify.
For example, in rgChapter, right-click in the rgChapterTitle hole.
7 Select Properties.
8 In the Content Control Properties dialog box, select the Use a style to format text
typed into the empty control check box.
9 From the Style list, select a style to use an existing style or select New Style to
create a new style to use as the default style and click OK.
6-23
6 Template-Based Report Formatting
10 Select the part template and click the Quick Parts button.
11 Click Save Selection to Quick Part Gallery.
12 In the Create New Building Block dialog box, set Name to the part template name
(for example, rgChapter) and the Category to mlreportgen. Click OK.
13 Save and close the template.
6-24
Customize Microsoft Word Part Templates
• Use an inline hole is for content that you can include in a Word paragraph.
• Use a block hole for content that you cannot embed in a paragraph.
You can configure the Word editor to provide visual cues that indicate whether a hole is
an inline or block hole.
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
• Inline hole — The bounding box does not include the paragraph marker.
• Block hole — The bounding box does includes the paragraph marker.
6-25
6 Template-Based Report Formatting
You can accidentally change a block hole to an inline hole by removing the paragraph
marker of an inline hole that is followed by a block hole. For example, if you delete the
paragraph marker for the rgChapterTitle inline hole, the rgChapterContent block
hole changes to an inline hole.
Delete a Hole
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of Word templates in the middle pane, select the custom template that you
want to edit.
3 In the Template Browser, click Open template.
4 To display Word paragraph markers (if they are not already visible), on the Word
ribbon in the Home tab, click the Show/Hide button.
5
In the Word ribbon, in the Insert tab, click the Quick Parts button.
6 Select the part template to customize. For example, select rgChapter to customize
the part template for a chapter.
6-26
Customize Microsoft Word Part Templates
Tip To display Word markup for the part template, on the Word ribbon, in the
Developer tab, click Design Mode.
7 Write down the name of the part template you are customizing, because you need to
enter that name later in this procedure.
8 In the rgChapter part template, delete the rgChapterTitlePrefix hole. Select
the hole markup and click the Delete key.
9 In the template, select all of the contents of the part template.
10 Right-click and select Properties.
11 In the Content Control Properties dialog box, in the Title and Tag fields, enter the
name of the template part you are customizing rgChapter. Click OK.
12 In the template, select all of the contents of the part template. In the Insert tab,
click the Quick Parts button.
13 Click Save Selection to Quick Part Gallery.
14 In the Create New Building Block dialog box, set Name to the part template name
(for example, rgChapter) and the Category to mlreportgen. Click OK.
15 In the template, select all of the contents of the part template and click the Delete
button.
16 Save and close the template.
6-27
6 Template-Based Report Formatting
Note: If you do not have a custom Word conversion template, see “Copy a Conversion
Template” on page 6-12.
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of Word templates in the middle pane, select the custom template that you
want to edit.
3 In the Template Browser, click Open template.
4 To display Word paragraph markers, click the Show/Hide button.
5 Position the Word insertion mark at the point in a paragraph where you want to add
an inline hole.
Tip If the hole is the only content in a paragraph or is at the end of a paragraph, add
several blank spaces and insert the hole before the spaces.
6 Click the Rich Text Control button . Word inserts a rich text control at the
insertion point.
7 To see hole markup, on the Word ribbon, in the Developer tab click Design Mode.
8 Right-click in the hole and select Properties.
9 In the dialog box, in the Title and Tag fields, enter the name of the hole. Use a
Report Explorer hole name. For example, if you insert an rgChapterTitlePrefix
hole, set the Title and Tag fields to rgChapterTitlePrefix.
10 In the template, select all of the contents of the part template. In the Insert tab,
click the Quick Parts button.
11 Click Save Selection to Quick Part Gallery.
12 In the Create New Building Block dialog box, set Name to the part template name
(for example, rgChapter) and the Category to mlreportgen. Click OK.
6-28
Customize Microsoft Word Part Templates
13 In the template, select all of the contents of the part template and click the Delete
button.
14 Save and close the template.
Related Examples
• “Copy a Conversion Template” on page 6-12
• “Customize Microsoft Word Report Styles” on page 6-18
• “Customize a Microsoft Word Title Page Template” on page 6-30
More About
• “Report Conversion Templates” on page 6-2
• “Conversion Template Contents” on page 6-5
6-29
6 Template-Based Report Formatting
In this section...
“Create a Custom Template” on page 6-30
“Change the Color of a Report Title” on page 6-31
“Assign the Template to a Report” on page 6-33
“Customize Title Page Content and Layout” on page 6-34
The Report Explorer default Word document conversion template contains document
part templates for the front (recto) and back (verso) side of a report title page. The Report
Explorer file converter for the Word (from template) output type uses the title page
part templates to produce the title pages in the Word output.
This example shows how to create a custom template that changes the color of the title
and how to customize the layout of a title page. The example uses a custom template
with the Report Generator magic square report example.
Note: To complete the rest of this example, you need a custom Word conversion template.
If you have a custom template that you want to use for this example, you can skip to
“Change the Color of a Report Title” on page 6-31.
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the list of templates, select the Default Word Template.
3 In the Template Browser, click Copy template.
4 In the file browser, navigate to the folder on the MATLAB path that you want to use
for the custom template. For the file name, enter magic-square and click Save.
5 In the list of templates, select Copy of Default Word Template.
6 At the top of the Template Properties dialog box, use these settings:
6-30
Customize a Microsoft Word Title Page Template
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the Report Explorer list of Word templates, select Magic Square Template.
3 In the Template Browser, click Open style sheet. In Word, the template opens,
with the Manage Styles dialog box displayed.
4 In the Manage Styles dialog box, select the rgTitle style and click Modify.
6-31
6 Template-Based Report Formatting
5 In the Modify Style dialog box for rgTitle, click the down arrow for Automatic.
Select the blue color box and click OK.
6-32
Customize a Microsoft Word Title Page Template
6-33
6 Template-Based Report Formatting
7 Generate the report. Select the magic_squares report. In the Report Explorer
1 In the Report Explorer, select Tools > Edit Document Conversion Template.
2 In the Report Explorer list of Word templates, select Magic Square Template. In
the Report Options pane, click Open template.
3 With the cursor in the first (and only visible) paragraph in the template, in the
Insert tab, select the Quick Parts button.
6-34
Customize a Microsoft Word Title Page Template
4 In the Quick Parts gallery, select rgRectoTitlePage to insert of the front title page
part template in the main document conversion template.
Tip To display Word markup for the part template, on the Word ribbon, in the
Developer tab, click Design Mode.
5 Highlight the rgImage hole and drag it above the rgTitle hole.
6 Delete the rgAuthor hole.
7 Select the rgRectoTitlePage part template and click the Quick Parts button.
8 Click Save Selection to Quick Part Gallery.
9 In the Create New Building Block dialog box, set Name to rgRectoTitlePage and
the Category to mlreportgen. Click OK.
10 In the template, select the contents of the part template (including the section break)
and click the Delete button.
11 Save and close the template.
Suppose that you use the custom template to generate a report that has a Title Page
component that specifies an image and an author. The generated report displays the
image at the top of the title page and does not include an author.
Related Examples
• “Copy a Conversion Template” on page 6-12
• “Customize Microsoft Word Report Styles” on page 6-18
More About
• “Report Conversion Templates” on page 6-2
• “Conversion Template Contents” on page 6-5
6-35
6 Template-Based Report Formatting
In this section...
“Copy an HTML Template” on page 6-36
“Select an HTML Editor” on page 6-37
“Edit HTML Styles in a Template” on page 6-37
Select a path that is on the MATLAB path (for example, in the MATLAB folder in your
home directory).
Specify the file name, using the default file extension for a HTML template
(.htmtx). Click Save.
5 In the list of templates in the middle pane, select the template copy you just created.
6 In the Properties pane, in the Template id and Display name fields, specify a
unique ID and display name for the template.
The display name is the name that appears in the Report Explorer list of templates.
The template ID is what you use to identify a template when using a command-line
interface.
7 To save the template properties you entered, move the cursor outside of the
Properties pane and click.
6-36
Create a Custom HTML Template
When you open an HTML stylesheet, the Report Explorer automatically replaces
FileName with the template that you selected.
1 In the list of templates in the middle pane, select the custom template that you want
to edit.
Tip If the Report Explorer middle pane does not show a list of templates, then select
Tools > Edit Document Conversion Template.
2 In the Properties pane, click Open stylesheet.
3 In the HTML editor, edit the cascading style sheet (CSS).
For information about editing a cascading style sheet, see documentation such as the
W3Schools.com CSS tutorial.
4 Save the style sheet.
Related Examples
• “Generate a Report Using a Template” on page 6-4
• “Customize Microsoft Word Report Styles” on page 6-18
• “Customize Microsoft Word Part Templates”
6-37
6 Template-Based Report Formatting
More About
• “Report Conversion Templates”
6-38
7
7-2
Create Custom Components
Tip You can also create a custom component by clicking the Create a new user-
defined reporting component link in the Report Explorer Properties pane on the
right.
• The Outline pane on the left displays the structure of components you create.
• The Options pane in the middle lists properties you add to components.
• The Properties pane on the right specifies the behavior of component properties.
7-3
7 Create Custom Components
3 Specify properties of the component in the Properties pane of the Report Explorer.
For more information, see “Define Components” on page 7-6.
4 Specify tasks you want the component to perform by editing the MATLAB files that
comprise the framework of the component. For more information, see “Specify Tasks
for a Component to Perform” on page 7-13.
5 Build the component. For more information, see “Build Components” on page
7-11.
After you build the custom component, you can use it to specify options for your
generated report in the report setup file.
7-4
Create Custom Components
Note: You must restart the MATLAB software session before using a newly created or
rebuilt component.
7-5
7 Create Custom Components
Define Components
In this section...
“Required Component Data” on page 7-6
“Specify the Location of Component Files” on page 7-6
“Set Component Display Options” on page 7-7
“Specify Component Properties” on page 7-9
“Modify Existing Components” on page 7-11
“Build Components” on page 7-11
“Rebuild Existing Components” on page 7-12
“Remove a Component” on page 7-12
1 The path where you want to put the folder that contains all files for the component.
For information on how to specify this folder, see “Specify the Location of Component
Files” on page 7-6.
2 Properties of the component. For more information, see “Specify Component
Properties” on page 7-9.
3 Display options for the component, including its display name, category, and
description. For more information, see “Set Component Display Options” on page
7-7.
Specify these directories in the following fields in the Component File Location area of
the Properties pane:
7-6
Define Components
1 Class Directory Field. Specify a class name for your component. The build process
creates a folder with the name you specify and places the component's files in it. The
class folder name must be unique for each component in the package. By convention,
component class names begin with an uppercase or lowercase letter c; for example,
cUserDefinedComponent.
2 Package Directory Field. Specify the folder in which to store files for groups of
components you create. Files for each component are stored in a subfolder with the
name you entered into Class Directory Field.
3 Parent Directory Field. Specify this folder when you create a package for the first
time. This folder is the parent folder of the Package Directory.
1 Display Name. Specify a display name for the component to appear in the list of
components for its associated category. Component categories and display names
appear in the Options pane in the middle of the Report Explorer.
2 Description. Enter a description for the component. This description appears when
you click the component name or category name in the Options pane in the middle of
the Report Explorer. Make the description informative, but brief.
7-7
7 Create Custom Components
3 Category Name. Specify the category of components to which the new component
belongs. The component appears under this category in the Options pane in the
middle of the Report Explorer.
Predefined choices appear in the Category name list. Select a component category
from this list.
To create a custom component category, type the name for the category into the
Category name field. This category name appears in the list of available categories
in the Report Explorer.
4 child components.
7-8
Define Components
You add properties to a component from the properties list. Each property has a default
value that you can modify as needed.
1 Right-click the name of the component to which you want to add properties in the
Outline pane on the left. Select Add new property from its context menu.
7-9
7 Create Custom Components
2 Right-click the name of a predefined property in the Options pane in the middle.
From the context menu, select Add property.
3 Left-click the name of a property in the Options pane, and then drag it on top of a
component in the Outline pane on the left.
4 Double-click the property name in the Options pane in the middle. The property is
added to the component and property values appear in the Properties pane on the
right.
5 Click the Add Property button on the Properties pane on the right.
7-10
Define Components
1 Property Name. Create a name for the new property. A property name must be a
valid MATLAB variable name, and must be unique within a component.
2 Data Type. Specify the property's data type. Options are:
• Double
• Enumeration
• Integer
• String
• String Vector
• %<Parsed String>
Use this data type to include the value of a variable in the MATLAB workspace in
a component. For more information about this data type, see “%<VariableName>
Notation” on the Text reference page.
• True/False
3 Default Value. Set a default value for the property. The default value must be
compatible with the data type. If incompatibilities exist between the default value
and the data type, the component might not build.
4 Dialog Prompt. This text appears next to the widget on the component's dialog box.
It indicates what the property does and how it affects report generation.
Note: When the component builds, a colon is appended to your entry in the Dialog
prompt field. Your entry appears in the Properties pane with the colon appended.
Build Components
After you have entered all data required for defining the component, you build it by
clicking the Build Component button. The build process creates all files needed for the
7-11
7 Create Custom Components
component and stores them in the specified folder. For more information about specifying
where components are stored, see “Specify the Location of Component Files” on page
7-6.
If you select a component using Tools > Create component from, the component's
fields are filled in automatically and the button becomes active.
After you have finished modifying the component, click the Rebuild Constructor
button to rebuild the component. Writable files in the component's folder location are not
overwritten.
Remove a Component
To remove a component:
7-12
Specify Tasks for a Component to Perform
Note: You must specify the format and content of your report output by editing
execute.m. This file is called during report generation to invoke your component's tasks.
Optionally, you can specify additional component properties and behavior by editing
other MATLAB files.
7-13
7 Create Custom Components
Where:
One or more default lines of code within the execute.m file show each property for the
component. Here is an example of a component property line within an execute.m file:
The following sections describe how to edit execute.m to create additional report
elements.
Create Tables
To create a table, replace the Source property value with the name of a cell array or
structure:
out = execute(rptgen.cfr_table(...
'Source', tableSrc,...
'numHeaderRows',1,...
'TableTitle','Example Title'),...
parentDoc);
Create Lists
To create a list, replace the Source property value with the name of a cell vector:
out = execute(rptgen.cfr_list(...
'Source', listSrc,...
'ListStyle','orderedlist',...
'ListTitle','Example List'),...
parentDoc);
7-14
Specify Tasks for a Component to Perform
Create Text
To create text, replace the ParaText property value with a text string:
out = execute(rptgen.cfr_paragraph(...
'ParaText', paraSrc,...
parentDoc);
Create Figures
figSrc = gcf;
out = execute(rptgen_hg.chg_fig_snap(...
'FigureHandle', figSrc,...
'Title', '',...
'isResizeFigure', 'manual',...
'PrintSize', [6 4],...
'PrintUnits', 'inches'),...
parentDoc);
The following code runs child components. The first line calls execute.m for child
components. The second line appends the results of running the child components to the
report:
childOut = thisComp.runChildren(parentDoc);
out = parentDoc.createDocumentFragment(out, childOut);
7-15
7 Create Custom Components
olstring = getOutlineString(thisComp)
Where:
Customize the string to include additional information about the component, such
as information about its properties. In the following example, the truncatestring
function converts input data into a single-line string. If the data is empty, the second
argument is the return value, The third argument is the maximum allowed size of the
resulting string.
cInfo = '';
pstring = rptgen.truncateString(thisComp.string,'<empty>',16);
Use a dash (-) as a separator between the name and additional component information,
as follows:
if ~isempty(cInfo)
olstring = [olstring, '-', cInfo];
end
Where:
7-16
Specify Tasks for a Component to Perform
Note: Do not modify fields that are not explicitly included in this file. These fields are
subject to change in future releases.
The description n getDescription.m is the same value as the Description field in the
Report Explorer. The following example shows how to edit the compDesc string in this
file to change a component's description to An example component:
7-17
7 Create Custom Components
The display name in getName.m is the same value as the Display name field in the
Report Explorer. The following example shows how to edit the compName string in this
file to change a component's display name to Example Component:
The category name in getType.m is the same value as the Category name field in the
Report Explorer. The following example shows how to edit the compCategory string in
this file to change a component's category name to Custom Components:
Register Components
You can register components in the Report Explorer using rptcomps2.xml. This file also
helps build the list of available components.
The content of this file must be consistent with the values in the getName.m and
getType.m files. If you have changed values in either of these files, you must also
change their values in rptcomps2.xml. You must restart the MATLAB software session
for the Report Explorer to display new information.
The viewHelp.m file displays a help file for the component within the MATLAB Help
browser. To display the help file, highlight the name of the component in the Report
Explorer and click Help.
7-18
Customized Components
Customized Components
In this section...
“Fetching Securities Data and Displaying It in a Table” on page 7-19
“Displaying Securities Data in Two Tables” on page 7-24
Because this example fetches ticker values for the security Google, set the
Default value to 'GOOG'. (The single quotation marks are required to specify a
string value for this field.)
7-19
7 Create Custom Components
3 To build the new component, click the Build button in the Report Explorer. The
Equity Values component now appears in the Options pane in the middle of the
Report Explorer.
4 Edit the component's execute.m file to retrieve stock market data and display it in
a table in the generated report.
function out=execute(thisComp,parentDoc,varargin)
7-20
Customized Components
function olstring=getOutlineString(thisComp)
7-21
7 Create Custom Components
try
currQuote = fetch(yahoo, thisComp.Ticker);
quoteStr = sprintf('Last value: %g', currQuote.Last);
catch
quoteStr = sprintf('Warning: ...
"%s" is not a valid symbol.', thisComp.Ticker);
end
dlgStruct = thisComp.dlgMain(name,...
thisComp.dlgContainer({
7-22
Customized Components
thisComp.dlgWidget('Ticker',...
'DialogRefresh',true,...
'RowSpan',[1 1],'ColSpan',[1 1]);
thisComp.dlgText(quoteStr,...
'RowSpan',[2 2],'ColSpan',[1 1]);
},'Stock',...
'LayoutGrid',[3 2],...
'RowStretch',[0 0 1],...
'ColStretch',[0 1]));
The Properties pane for the component, Equity Values, now looks as follows.
7 Click File > Report to generate the report. The following output appears in the
report.
7-23
7 Create Custom Components
1 Create a report setup file and save it as stockreport.rpt. Add two Equity
Values components to the setup file.
2 Edit the entry in the New marker property field to change the ticker property of
the second component to '^GSPC' (S&P 500 index).
The report displays two tables of data, one for Google® and another for the S&P 500
index.
7-24
Customized Components
7-25
8
Stylesheets
In this section...
“Built-In Versus Custom Stylesheets” on page 8-2
“Customize Stylesheets Using Data Items” on page 8-3
The following table lists report output formats and their default stylesheets.
The following table shows a list of properties for the built-in stylesheets.
Properties of Stylesheets
Name Description
Description A description of the stylesheet.
Display name The stylesheet name that appears in the Options pane.
Transform type The process used to generate reports that use a specified stylesheet.
Supported types are:
• HTML
• FO (Formatting Object) for PDF reports
• DSSSL (Document Style Semantics and Specification Language) for
RTF and Word reports
8-2
Stylesheets
Name Description
Note: This field is not editable.
In most cases, the stylesheets provided with the MATLAB Report Generator software
should be more than adequate for your needs. However, you may want to modify
the built-in stylesheets to meet special requirements. For example, suppose one of
the built-in stylesheets meets your requirements, but you want to change the page
orientation. You can create a custom stylesheet by editing the built-in stylesheet to your
specifications.
Data items can be of different types, some of which require different editing methods.
For more information about editing data items, see “Edit Stylesheet Data Items” on page
8-9.
Tip See the Help area at the bottom of the Properties pane on the right for a description
of a specific data item that you are editing.
8-3
8 Create Custom Stylesheets
a Drag the data item you want to add from the Options pane in the middle to the
stylesheet in the Outline pane on the left.
b In the Properties pane on the right, edit the data items for the selected style. For
more information, see “Edit Stylesheet Data Items” on page 8-9
5 Save the stylesheet. For information about how to save a stylesheet, see “Save a
Stylesheet” on page 8-7.
8-4
Edit, Save, or Delete a Stylesheet
In this section...
“Edit a Stylesheet” on page 8-5
“Save a Stylesheet” on page 8-7
“Delete a Stylesheet” on page 8-8
Edit a Stylesheet
To edit a stylesheet:
1 In Report Explorer, select a report setup file in the Outline pane on the left.
2 From the menu bar, click Tools > Edit Stylesheet.
• The Outline pane on the left displays the structure of stylesheets you create.
• The Options pane in the middle lists stylesheets available for customizing.
8-5
8 Create Custom Stylesheets
You can use the Report Explorer to work with stylesheets as follows.
8-6
Edit, Save, or Delete a Stylesheet
Save a Stylesheet
You must save a stylesheet before you can use it to convert a source file or associate it
with a report. To use the Report Explorer to save a stylesheet:
1 Select the stylesheet that you want to save in the Outline pane on the left.
8-7
8 Create Custom Stylesheets
2 Select File > Save As from the menu bar and specify a new name for the stylesheet
(to avoid overwriting built-in stylesheets). You must save the file in a folder in your
MATLAB path for the stylesheet to appear in the Report Explorer. The file name
must be unique in the MATLAB path.
By convention, MATLAB Report Generator stylesheets have .rgs as their file name
extension.
Delete a Stylesheet
To use the Report Explorer to delete a stylesheet that you created:
1 Select the stylesheet that you want to delete in the Outline pane on the left.
2 Click the stylesheet to delete from the Options pane in the middle.
3 Click Delete stylesheet in the stylesheet's Properties pane on the right.
You must restart the MATLAB software session for deleted stylesheets to disappear from
the Options pane.
8-8
Edit Stylesheet Data Items
In this section...
“Data Item Categories in Built-In Stylesheets” on page 8-9
“Edit Data Items in Simple or Advanced Edit Mode” on page 8-13
“Data Items” on page 8-13
8-9
8 Create Custom Stylesheets
You can set up font mappings for non-English PDF fonts. The PDF stylesheets override
those mappings. For details, see
8-10
Edit Stylesheet Data Items
8-11
8 Create Custom Stylesheets
8-12
Edit Stylesheet Data Items
Note: This section gives instructions for simple edit mode, except where explicitly
specified otherwise.
The user interface is in simple edit mode when the data item appears in a pane labeled
Value. It is in advanced edit mode when the data item appears in a pane labeled Value
(XML). To switch from simple to advanced edit mode, click Edit as XML.
Edit values for most data items in PDF and HTML stylesheets in either simple edit mode
or advanced edit mode. Edit values for RTF stylesheets in simple edit mode only. Data
items in RTF stylesheets do not support advanced edit mode.
Note: To modify content for headers and footers you edit stylesheet cells, which do not
appear in either simple or advanced mode. For more information, see “Stylesheet Cells
for Headers and Footers” on page 8-23.
Data Items
Select a stylesheet from the Options pane in the middle of the Report Explorer. The
Outline pane on the left shows the name of the current style data item inside its
8-13
8 Create Custom Stylesheets
stylesheet. The Options pane in the middle shows a list of available stylesheet data
items. The Properties pane on the right displays Stylesheet Editor: Data. It also
includes the following information:
• The value of the data item is in a pane labeled Value in simple edit mode or Value
(XML) in advanced edit mode.
• To the right of the value is the Edit as XML toggle button.
• The Preview pane includes a partial view of the stylesheet that specifies the data
item. The data in this pane is not editable.
• The Help pane contains information about the data item. This information is not
editable.
8-14
Edit Stylesheet Data Items
In the previous figure, theShow Comments data item is of type Boolean. Its current
value is true(1). Change this value using the menu list for the value field. In this case,
the only other possible value is false(2).
8-15
8 Create Custom Stylesheets
Edit Strings
For the values of some data items, the Report Explorer displays text in the editable
Value field. You can specify an XML expression, though you are not required to do so.
To make complex changes to a stylesheet, consider using Advanced edit mode. This
enables you to edit XML expressions directly in the Value (XML) pane. If this pane does
not appear, click Edit as XML to switch to advanced edit mode.
Make sure that you enter valid XML. Invalid XML values generate an error, which
appears at the top of the Properties pane.
For PDF or HTML stylesheets, you can modify the layout, contents, and format of a title
page by using the Stylesheet Editor.
• Book Titlepage Recto to specify properties for the front side of the title page
• Book Titlepage Verso to specify properties for the back side of the title page
3 In the Properties pane, select Add to current stylesheet and edit the properties.
8-16
Edit Stylesheet Data Items
To adjust the grid used to position the title page elements (such as the title and author)
on the page, in the Properties pane specify:
To view the grid layout on the generated title page, select Show grid.
By default, all of the title page elements appear on the title page. To exclude display of a
title page element:
8-17
8 Create Custom Stylesheets
1 In the Properties pane, in the Include on title page list, select an element to
exclude.
2 Click the right arrow button. The element appears in the Exclude from Title Page
list.
1 In Properties pane, in the Include on title page list, select the title page element.
2 Adjust the applicable properties:
• Layout options — Specify which title page grid row and column in which you
which you want the element to appear. To span multiple rows or columns, specify
numbers for the Span row and Span column properties.
• Format options — For text elements, specify the font size, whether to use bold or
italics, text color, and text alignment.
• Transform options — You can use these options to specify XSLT code to customize
the contents and format of title page elements. Use the XPath property to
specify the path to the XSLT object that you want to modify. Use the Transform
property to specify the custom content and layout.
To change values for generation of the report's table of contents (TOC), select the
appropriate values from a matrix of check boxes.
The following figure shows the values for the Generate Toc data item on the PDF
stylesheet. Select the check boxes to control the values that appear in the report's title
page and table of contents.
8-18
Edit Stylesheet Data Items
The Title Placement data items, which are in the Miscellaneous category, control the
position of titles for figures and tables.
Selecting one of these data items for editing causes the Properties pane on the right
to display possible values in a menu list. Specify whether you want the title to appear
before or after a given figure or table.
8-19
8 Create Custom Stylesheets
Modify Attributes
An attribute is a data item that specifies information for an XML element. An attribute
must be a child of an attribute set. For more information, see “Edit Attribute Sets” on
page 8-20.
Note: The information in the Help area of the Properties pane of an attribute describes
the set to which the attribute belongs.
An attribute set consists of a group of attributes. Selecting an attribute set in the Outline
pane on the left causes the Properties pane to list the attributes that belong to that set.
To edit a specific attribute, expand the attribute set in the Outline pane and select the
attribute you want to edit.
To edit the attribute set, type text in the Inherit attribute sets area of the Properties
pane.
Here is an example of the Report Explorer showing the Formal Object Properties
attribute set in the Properties pane.
8-20
Edit Stylesheet Data Items
Data items in RTF stylesheets appear as varpair data items, which are name/value
pairs of information. RTF stylesheets are the only type of stylesheet that includes
varpair data items.
Edit varpair data items as strings or as Boolean values. Boolean values appear as true
(#t) and false (#f).
8-21
8 Create Custom Stylesheets
on the right looks different from code associated with other kinds of MATLAB Report
Generator stylesheets.
8-22
Stylesheet Cells for Headers and Footers
In this section...
“About Stylesheet Cells and Cell Groups” on page 8-23
“Headers and Footers” on page 8-24
“Add Content to Headers and Footers Using Templates” on page 8-26
“Insert Graphics Files” on page 8-27
“Modify Fonts and Other Properties” on page 8-27
The MATLAB Report Generator software defines a page as six cells. These cells
correspond to the left, right, and center of the page's header and the left, right, and
center of the page's footer.
A cell group consists of one or more stylesheet cells. Two cell groups are available for
PDF reports: Header Content and Footer Content.
The Properties pane for each cell in a cell group lists the group's current stylesheet cell
definitions. These definitions appear in a two-column list of Conditional cell values.
The first column displays the name of a condition. The second column displays content
that appears in the report if the specified condition is met.
For example, the stylesheet cell Page sequence - Blank specifies the content for a
blank page; by default, the content is empty. Similarly, Cell - Right Side specifies
the content for the right side of the header on every page.
8-23
8 Create Custom Stylesheets
You can use many combinations of conditions and values to customize content of headers
and footers. The MATLAB Report Generator software provides several predefined
conditions that are frequently used. These predefined cells appear in the Properties
panes for the Header Content and for Footer Content cell groups.
You can use the Properties pane of a stylesheet cell to specify content that satisfies
specified conditions. The Properties pane for a stylesheet cell includes the following.
8-24
Stylesheet Cells for Headers and Footers
When the File Converter processes a page, it evaluates settings that are relevant to each
of the six cells on the page and adds content accordingly. If there are no conditions in
effect for a given cell, the File Converter uses the default values for the cell group.
8-25
8 Create Custom Stylesheets
Possible conditions and their values as coded in XML are shown in the following table.
Use standard logical operators (such as = , != , and, or) and nested expressions
(characters between parentheses are an expression within an expression) to specify
complex conditions. You can use complex conditions to set the position of headers and
footers on pages. You can also use them to specify other settings, such as where in the
report the content appears.
• Text
• Author names
• Page numbers
• Titles for chapters and sections
• Chapter numbering
• Draft information
• Comments
• Graphics
Templates used by the File Converter are Extensible Style Language Transformations
(XSLT), which is a language for transforming XML documents into other XML
8-26
Stylesheet Cells for Headers and Footers
documents. For details about XSLT, see the Web site for the World Wide Web
Consortium (W3C®) at http://www.w3.org/TR/xslt.
1 In the Append template list, select the type of content you want to add.
2 Click Append.
The Properties pane on the right displays default content for the type you select.
Edit the XML code to change the default content.
1 Specify the name of the file in the Header Content or Footer Content stylesheet
cell.
2 Edit the values of the Region Before Extent and Region After Extent data
items. These are located in the Pagination and General Styles folder of the
Options pane for PDF formatting.
For an example of adding a graphic file to a header, see “Add Graphics to Headers in
PDF Reports” on page 8-30.
Note: PDF reports only support bitmap (.bmp), jpeg (.jpg), and Scalable Vector
Graphics (.svg) images in headers and footers.
8-27
8 Create Custom Stylesheets
Each of these attribute sets is a pagination style data item for PDF stylesheets. You can
edit a particular attribute in the set by selecting it in the Outline pane on the left.
For an example of modifying font size and other properties of a PDF report, see “Change
Font Size, Page Orientation, and Paper Type of a Generated Report” on page 8-35.
8-28
Customized Stylesheets
Customized Stylesheets
In this section...
“Number Pages in a Report” on page 8-29
“Add Graphics to Headers in PDF Reports” on page 8-30
“Change Font Size, Page Orientation, and Paper Type of a Generated Report” on page
8-35
“Edit Font Size as a Derived Value in XML” on page 8-37
1 Define a basic stylesheet cell in the Header Content cell group with a condition of
right.
8-29
8 Create Custom Stylesheets
3 Click Append.
This example shows how to include an image in the center of the header of each page in
a PDF report, excluding the report's title page and the first page of each chapter. You do
this by editing default header content for a PDF stylesheet. This example uses the report
setup file mfile-report.rpt.
You can use any bitmap or jpeg file as image content. You must know the size of the
image so that you can allow enough room for it in the header. This example uses the
sample_logo.bmp image, which is shown here.
8-30
Customized Stylesheets
Note: PDF reports only support bitmap (.bmp), jpeg (.jpg), and Scalable Vector
Graphics (.svg) images.
To include this image file in the center of each header in the body of a PDF report:
setedit mfile-report
2 Create a custom stylesheet.
a Select Tools > Edit Stylesheet in the menu bar of the Report Explorer.
b Click New FO (PDF) in the Properties pane on the right.
c As the Display name, enter Logo stylesheet for PDF.
d As Description, enter Company logo in center of header.
e Save the stylesheet as logo_stylesheet.rgs in a folder on your MATLAB
path.
3 Open the cell group for editing.
a Scroll through the Options pane on the left to the Pagination and General
Styles folder.
b Double-click Header Content in the Options pane.
c Click Body page – Center from the list of cells in the Properties pane on the
right.
8-31
8 Create Custom Stylesheets
The Properties pane on the right shows the XML code that tells the File
Converter to include the graphic.
8-32
Customized Stylesheets
4 By default, the name of the graphic is logo.bmp. Change all instances of this name
to sample_logo.bmp in the Value (XML) field.
5 Save the stylesheet.
6 Make sure that the amount of room available in the header is large enough to
accommodate the image file.
a In the Options pane in the middle, double-click Region Before Extent, which
is in the Pagination and General Styles folder.
8-33
8 Create Custom Stylesheets
b By default the value for the height of the header is 0.4 inch. Replace this value
with 1.0in.
c Save the stylesheet.
7 Generate the report with the new styles.
8-34
Customized Stylesheets
a Open the report by entering the following command in the MATLAB Command
Window:
setedit wsvar-report
b In the Report Format and Stylesheet area of the Properties pane, change the
format to DocBook (no transform).
c Check the If report already exists, increment to prevent overwriting
check box.
d Select File > Report to generate the report.
a Select Tools > Convert Source File from the Report Explorer menu bar to
open the File Converter.
b From the Source file selection list, enter wsvar-report0.xml.
c From the File format selection list, select Acrobat (PDF).
d From the Stylesheet selection list, select Unnumbered Chapters and
Sections.
e Click Convert File.
8-35
8 Create Custom Stylesheets
The MATLAB Report Generator software converts the XML source file for
wsvar-report to PDF format, and then opens the PDF document.
3 Make the report headers more prominent.
The Section Title Level 1 Properties data item appears in the Outline pane
on the left as a child of the Custom Large Section Headers stylesheet.
g In the Properties pane on the right, select the Font Size attribute.
The Properties pane on the right displays an XML expression specifying font
size as a multiple of the Body Font Size attribute.
h Click Edit as string.
The size of the font is now fixed at 18 points, rather than being a multiple of the
body font size attribute.
j Select File > Save to save the stylesheet.
k Save the stylesheet as customheader.rgs, in a folder in your MATLAB path.
8-36
Customized Stylesheets
a In the Stylesheet Editor: Main Properties pane on the right, click Send to
File Converter
The PDF report appears with horizontally oriented pages of slightly different
dimensions.
8-37
8 Create Custom Stylesheets
4 In the Attributes area of the Properties pane on the right, click Font Size - <xml>.
8-38
Customized Stylesheets
The font size value is a product of $body.font.master and 2.0736. To change the
font size to a larger size, change the multiplication factor to 3.0736.
Tip You specify the value for the $body.font.master data item in the Body Font
Master property. This property is in the Pagination and General Styles category in
the Options pane in the middle. The default value of this data item is 10. Changing this
value causes the derived values to change accordingly.
8-39
8 Create Custom Stylesheets
The MATLAB Report Generator also provides basic PDF font support for some non-
English languages, including:
• Japanese
• Korean
• Russian (Cyrillic)
• Add or modify specifications for PDF font usage for supported non-English languages.
• Create PDF font support for a non-supported language.
• Change the default English fonts, if you do not specify a stylesheet.
The language font map specifications indicate what font to use on a specific platform (for
example, Windows) for basic report elements such as body text.
8-40
PDF Fonts for Non-English Platforms
The PDF stylesheet settings override the PDF font mapping entries.
If you do not specify a PDF stylesheet, then you can use PDF language font mapping
entries to change the default fonts for English reports.
lang_font_map.xml File
Use an XML editor with the lang_font_map.xml file to enter all the PDF font
mappings for your reports.
Installing the MATLAB Report Generator software loads the lang_font_map.xml file
in the following location:
<matlabroot>/toolbox/shared/rptgen/resources/fontmap
8-41
8 Create Custom Stylesheets
• name_map — Contains name_mapping elements that specify the name of the font, the
language, and the font usage in the report (for example, body text).
• file_map— Contains entries for the location of the font files for the fonts specified in
the name_map.
For example, the following lang_font_map.xml file includes name_map and file_map
entries that provide basic PDF font support for Japanese (ja), Korean (ko), and Russian
(ru).
lang_font_map.xml example
<?xml version="1.0" encoding="UTF-8" ?>
<lang_font_map>
<name_map>
<name_mapping lang="ja" platform="win" usage="body">MS Gothic</name_mapping>
<name_mapping lang="ja" platform="win" usage="monospace">MS Gothic</name_mapping>
<name_mapping lang="ja" platform="win" usage="sans">MS Gothic</name_mapping>
<name_mapping lang="ja" platform="win" usage="title">MS Gothic</name_mapping>
8-42
PDF Fonts for Non-English Platforms
<file_map>
<file_mapping lang="ja" platform="win" name="MS Gothic">msgothic.ttc</file_mapping>
<file_mapping lang="ja" platform="win" name="MS PGothic">msgothic.ttc</file_mapping>
• Type 1 (PostScript®)
• TrueType
• OpenType®
Fonts in other formats, such as bitmap fonts for the X Window System (X11), produce
poor MATLAB Report Generator report output.
Some TrueType fonts are grouped into packages called TrueType Collections. To specify a
collection in the language font map file, specify the individual font within the TrueType
Collection.
In addition to the font name, the weight (e.g., bold) and slant (e.g., italic, oblique) may
distinguish one font from another in the same family.
8-43
8 Create Custom Stylesheets
The approach you use to identify font names depends on your computer platform.
a Right-click any of constituent font and select Properties. The properties box
displays the name of the file containing that font.
Mac OS X provides an application called Font Book (in the /Applications folder) that
provides information about available fonts on the system. The application shows all the
fonts on your system. Hover over a specific font to see a datatip with the font name and
the path to the font.
Linux distributions use a variety of conventions for the location of fonts, or how those
font folders can be found. By default, MATLAB Report Generator searches these folders,
in this order:
1 /.fonts/
2 /usr/local/share/fonts/
3 /usr/X11R6/lib/fonts/
4 /usr/share/fonts/
You can specify alternative folders in the fonts.conf file (in the /etc/fonts/ folder).
8-44
PDF Fonts for Non-English Platforms
• lang specifies the two letter ISO 639-1 code corresponding to the language of the
report.
• platform specifies the operating system platform:
• win — Windows
• mac — Mac OS X
• glnx— Linux
• usage specifies the kind of report element or font:
• body
• title
• monospaced
• sans (sanserif)
Each of the platforms (Windows, Mac, and Linux) has a different default search path for
fonts. If the lang_font_map.xml file does not contain a full file path for a font, the
MATLAB Report Generator uses a platform-specific approach to search for the font.
On Windows platforms, the MATLAB Report Generator searches for fonts in <windir>/
Fonts, where winder is an operating system environment variable. The typical location
is C:\Windows or C:\Winnt.
8-45
8 Create Custom Stylesheets
• ~/Library/Fonts
• /Library/Fonts
• Network/Library/Fonts
• System/Library/Fonts
• System/Folder/Fonts
On Linux platforms, the convention for locating fonts can differ, depending on the Linux
distribution. The MATLAB Report Generator follows the Debian® convention of finding
the list of font folders in the /etc/fonts/fonts.conf file.
If the MATLAB Report Generator does not find the fonts.conf file in /etc/fonts/
folder, it searches the following folders, in the following order:
1 /.fonts
2 /usr/local/share/fonts
3 /usr/X11R6/lib/fonts
4 /usr/share/fonts
8-46
9
The XML comparison tool processes the results into a report that you can use to explore
the file differences.
The XML comparison tool compares the files using the “Chawathe” algorithm, as
described in this paper:
Change Detection in Hierarchically Structured Information, Sudarshan Chawathe,
Anand Rajaraman, and Jennifer Widom; SIGMOD Conference, Montreal, Canada, June
1996, pp. 493-504.
This conference paper is based upon work published in 1995: see http://
dbpubs.stanford.edu:8090/pub/1995-45.
XML comparison reports display in the Comparison Tool. For more information about the
Comparison Tool, see “Comparing Files and Folders” in the MATLAB documentation.
The XML comparison report shows a hierarchical view of the portions of the two XML
files that differ. The report does not show sections of the files that are identical.
If the files are identical you see a message reporting there are no differences.
Note: It might not be possible for the analysis to detect matches between previously
corresponding sections of files that have diverged too much.
For information about creating and using XML comparison reports, see:
9-2
Compare XML Files
9-3
9 Comparing XML Files
• For two files in the same folder, select the files, right-click and select Compare
Selected Files/Folders.
• To compare files in different folders:
If the selected files are XML files, the XML comparison tool performs a Chawathe
analysis on the files and displays a report in the Comparison Tool.
The file you right-click to launch the XML comparison tool displays on the right side of
the report.
For more information about comparisons of other file types with the Comparison
Tool, such as text, MAT or binary, see “Comparing Files and Folders” in the MATLAB
documentation.
9-4
How to Compare XML Files
To compare files using the Comparison Tool, from the MATLAB Toolstrip, in the File
section, select the Compare button. In the dialog box select files to compare.
If the files you select to compare are XML files and you select an XML comparison, the
XML comparison tool performs a Chawathe analysis of the XML files, and generates an
report.
where filename1 and filename1 are XML files. This XML comparison functionality is
an extension to the MATLAB visdiff function.
To change comparison type, either create a new comparison from the Comparison Tool,
or use the Compare Against option from the Current Folder browser. You can change
comparison type in the Select Files or Folders for Comparison dialog box. If you want
the MATLAB text differences report for XML files, change the comparison type to Text
comparison in the dialog before clicking Compare.
See Also
For an overview, see “Compare XML Files” on page 9-2.
For explanations on how to use and understand the report and the XML comparison
functionality, see “Explore the XML Comparison Report” on page 9-6
9-5
9 Comparing XML Files
To step through differences, use the Comparison tab on the toolstrip. To move to the
next or previous group of differences, on the Comparison tab, in the Navigate section,
click the arrow buttons to go to the previous or next difference.
9-6
Explore the XML Comparison Report
Use the toolbar buttons or the Comparison menu for the following functions:
Use the View tab controls on the toolstrip for the following functions:
Tip Right-click to expand or collapse the hierarchy within the selected tree node.
• Collapse All — Collapses all items in the tree to the most compact view possible.
Unexpected Results
If you see unexpected results within an XML comparison report, try reading the
documentation section on “How the Matching Algorithm Works” on page 9-10.
Note: It may not be possible for the analysis to detect matches between previously
corresponding sections of files that have diverged too much.
9-7
9 Comparing XML Files
You can zip the temporary files (such as log files) created during XML comparisons, for
sharing or archiving. While the comparison report is open, enter:
xmlcomp.zipTempFiles('c:\work\myexportfolder')
The destination folder must exist. The output reports the zip file name:
To view the log file for the last comparison in the MATLAB Editor, enter:
xmlcomp.showLogFile
1 On the Comparison tab, in the Comparison section, select Save As > Save to
Workspace.
The xmlcomp.Edits object contains information about the XML comparison including
file names, filters applied, and hierarchical nodes that differ between the two XML files.
Edits = xmlcomp.compare(a.xml,b.xml)
9-8
Explore the XML Comparison Report
9-9
9 Comparing XML Files
In this section...
“Why Do I See Unexpected Results?” on page 9-10
“How the Chawathe Algorithm Works” on page 9-10
“Why Use a Heuristic Algorithm?” on page 9-12
“Examples of Unexpected Results” on page 9-12
The Chawathe algorithm attempts to match elements that are of the same category.
The Chawathe paper refers to these categories as labels. In the following XML example
documents (with labels A, B, and C):
• The three C elements on the left are compared with the three C elements on the right
• The single B element on the left is compared with the two B elements on the right
9-10
How the Matching Algorithm Works
Sequences are matched using a Longest Common Subsequence (LCS) algorithm. For
example, if C elements are matched on their text content, the LCS of the above sequences
is given by:
You can define a score for matching elements of a particular label in different ways. For
instance, in the above example, C elements can be matched on text content, B can be
matched on text content and on Name, and A on the number of B and C elements they
have in common. To determine whether elements match or not, the Chawathe algorithm
compares the score to a threshold.
The implementation can specify scoring methods, thresholds, the definition of labels, and
the order in which labels are processed. These can be defined separately for each problem
domain or type of XML file. The XML comparison tool provides suitable definitions
for a set of common XML file types, and uses a default definition for any type of XML
document it does not recognize.
9-11
9 Comparing XML Files
Also a user's expectations can depend on context information that is not available
to the matching algorithm (e.g., prior knowledge of the precise sequence of changes
applied). This means even a mathematically optimal algorithm might match elements
unexpectedly from a user's perspective.
The XML comparison tool performs best when the files to be compared are mostly
similar. It becomes slower for files that contain more differences.
Elements could fail to match even if they were matched in comparisons of previous
versions of the documents. A seemingly small change in one of the properties used for
matching can cause this to happen if it tips the score under the threshold.
9-12
How the Matching Algorithm Works
The left A and the middle A have two out of three B elements in common, resulting in a
matching score of 2/3=0.66. The XML comparison tool marks the A elements as matched
and the report shows that their contents have been modified.
When a user makes a further change to the middle document (resulting in the right
document), and this new document is compared again to the left document, the matching
score for A drops to 1/3=0.33. The algorithm considers the A elements unmatched this
time. In this case, the difference between the two documents is marked as a deletion of A
from the left document and an insertion of a new A into the right document.
This problem is likely to occur when there is little information available inside a single
element to score a match. A seemingly small change in one of the properties used for
matching could tip the score under the threshold, and therefore result in a large change
in the outcome of the comparison.
Sometimes unexpected matches of similar items occur across different parts of the
hierarchy. In the following example, C elements are matched on name:
9-13
9 Comparing XML Files
In this case, the user might expect to see the very first C element on the left marked as
deleted, with the second and third C elements matched to the corresponding C element
on the right. However, this might not happen, if the first C on the left is matched to the
second C on the right, even though these two C elements exist in very different parts of
the document hierarchy. This mismatch would result in the third C element on the left
being marked as deleted, which the user might find unexpected.
This case is likely to occur when there are several potential matching candidates for a
particular element. In other words, when elements of a particular label tend to be very
similar. Whether such a spurious cross-matching occurs or not depends on all of the
other C elements within the two documents. The LCS algorithm used for matching the
two sequences favors local matches over distant ones. In other words, sub-sequences
of elements that are close together in the first sequence tend to be matched to sub-
sequences of elements that are close together in the second sequence. However, this
locality is not always guaranteed, and the outcome depends on how other elements in the
sequence are matched.
9-14
How the Matching Algorithm Works
It is difficult to distinguish many similar potential matches and this could produce
unexpected results. In the following example, B elements are scored on name, p1, and p2,
and the score is compared to a threshold of 0.5.
The right document contains one B element more than the left document, and therefore
one of the B elements on the right must remain unmatched and the tool will mark one as
inserted. However, since most B elements on the left potentially match most B elements
on the right, it is impossible to predict exactly how the sequences will be matched. For
instance, the comparison could generate the following result:
“B name=”1” …” > “B name=”2” …”
“B name=”2” …” > “B name=”new” …”
“B name=”3” …” > “B name=”3” …”
“B name=”4” …” > “B name=”4” …”
In this case, “B name= “1” on the right remains unmatched. As in the previous example,
this depends on how all of the other B elements in the two documents are matched. This
situation is likely to occur when elements have several potential matching candidates.
9-15
10
Array-Based Table
Convert rectangular array into table and insert it into report
Description
This component converts a rectangular cell array into a table and inserts the table into
the report.
Table Content
• Workspace variable name: Specifies the workspace variable name with which to
construct the table.
• Collapse large cells to a single description: Consolidates large cells into one
description.
Formatting Options
• Table title: Specifies the title of your table.
• Cell alignment:
• left
• center
• right
• double justified
• Column widths: Inputs a vector with m elements, where m equals the number
of columns in the table. Column sizing is relative and normalized to page width.
For example, say that you have a 2-by-3 cell array and input the following into the
Column widths field:
[1 2 3]
The report output format for the cell array is such that the second column is twice the
width of the first column, and the third column is three times the width of the first
column. If the vector is greater than the number of columns in the table, the vector
10-2
Array-Based Table
If you use this field, it is recommended that you specify a width for each column. Any
width not specified defaults to 1. MATLAB displays a warning when defaulting any
unspecified column width to 1.
• Table grid lines: Displays grid lines, which create borders between fields, in the
table.
• Table spans page width (HTML only): Sets the table width to the width of the
page on which it appears.
Header/Footer Options
Designating a row as a header or footer row causes the contents of the row to appear in
boldface.
Example
Consider the following cell array in the MATLAB workspace:
{'foo','bar';[3],[5]}
foo bar
3 5
10-3
10 Components — Alphabetical List
Class
rptgen.cfr_table
See Also
Table, Table Body, Table Column Specification, Table Entry, Table Footer,
Table Header, Table Row, Chapter/Subsection, Empty Component, Image, Link,
List, Paragraph, Text, Title Page
10-4
Axes Loop
Axes Loop
Run child components for all axes objects in MATLAB workspace
Description
The Axes Loop component runs its child components for all axes objects in the MATLAB
workspace. For information about working with looping components, see “Logical and
Looping Components”.
Object Selection
• Loop type:
• Loop on axes with handle visibility "on": Loops only on visible axes
objects.
• Loop on all axes: Loops on all axes objects.
• Search terms: Specifies search terms for the loop. For example, to search for Tag
and My Data, enter "Tag" ,"My Data".
Section Options
• Create section for each object in loop: Inserts a section in the generated report
for each object found in the loop.
• Display the object type in the section title: Automatically inserts the object type
into the section title in the generated report.
• Create link anchor for each object in loop: Creates a hyperlink to the object in
the generated report.
10-5
10 Components — Alphabetical List
Class
rptgen_hg.chg_ax_loop
See Also
Axes Snapshot, Figure Loop, Figure Snapshot, Graphics Object Loop,
Handle Graphics Linking Anchor, Handle Graphics Name, Handle Graphics
Parameter, Handle Graphics Property Table, Handle Graphics Summary
Table
10-6
Axes Snapshot
Axes Snapshot
Insert image of selected MATLAB axes objects into the generated report
Description
Inserts an image of selected MATLAB axes objects into the generated report.
Format
• Image file format: Specifies the image file format. Select Automatic HG Format
to automatically choose the format best suited for the specified report output format.
Otherwise, choose an image format that your output viewer can read. Automatic HG
Format is the default option. Options include:
• Automatic HG Format (uses the Handle Graphics file format selected in the
Preferences dialog box)
• Bitmap (16m-color)
• Bitmap (256-color)
• Black and white encapsulated PostScript
• Black and white encapsulated PostScript (TIFF)
• Black and white encapsulated PostScript2
• Black and white encapsulated PostScript2 (TIFF)
• Black and white PostScript
• Black and white PostScript2
• Color encapsulated PostScript
• Color encapsulated PostScript (TIFF)
• Color encapsulated PostScript2
• Color encapsulated PostScript2 (TIFF)
• Color PostScript
• Color PostScript2
• JPEG high quality image
10-7
10 Components — Alphabetical List
Print Options
• Paper orientation:
• Landscape
• Portrait
• Rotated
• Use figure orientation: Uses the orientation for the figure, which you set
with the orient command.
• Full page image (PDF only): In PDF reports, scales images to fit the full
page, minimizes page margins, and maximizes the size of the image by using
either a portrait or landscape orientation.
For more information about paper orientation, see the orient command in the
MATLAB documentation.
• Image size:
• Use figure PaperPositionMode setting: Sets the image size in the report
to the PaperPositionMode property of the figure. For more information about
paper position mode, see orient in the MATLAB documentation.
• Automatic (same size as onscreen): Sets the image in the report to the
same size as it appears on the screen.
10-8
Axes Snapshot
• Custom: Specifies a custom image size. Specify the image size in the Size field and
Units list.
• Size: Specifies the size of the figure snapshot in the format [w h] (width, height).
This field is active only if you choose Custom in the Image size selection list.
• Units: Specifies the units for the size of the figure snapshot. This field is active only if
you choose Set image size in the Custom selection list.
• Invert hardcopy: Sets the InvertHardcopy property of Handle Graphics figures.
This property inverts colors for printing; that is, it changes dark colors to light colors
and vice versa. Options include:
• Automatic: Automatically changes dark axes colors to light axes colors. If the
axes color is a light color, it is not inverted.
• Invert: Changes dark axes colors to light axes colors and vice versa.
• Don't invert: Does not change the colors in the image displayed on the screen
for printing.
• Use figure's InvertHardcopy setting: Uses the InvertHardcopy
property set in the Handle Graphics image.
• Make figure background transparent: Makes the image background
transparent.
Display Options
• Scaling: Controls size of the image, as displayed in a browser. Making an image
larger using this option does not affect the storage size of the image, but the quality
of the displayed image may decrease as you increase or decrease the size of the
displayed image.
Generally, to achieve the best and most predictable display results, use the default
setting of Use image size.
• Use image size: Causes the image to appear the same size in the report as on
screen (default).
• Fixed size: Specifies the number and type of units.
• Zoom: Specifies the percentage, maximum size, and units of measure.
• Size: Specifies the size of the snapshot in the format w h (width, height). This field is
active only if you choose Fixed size in the Scaling list.
10-9
10 Components — Alphabetical List
• Max size: Specifies the maximum size of the snapshot in the format w h (width,
height). This field is active only if you choose Zoom from the Scaling list.
• Units: Specifies the units for the size of the snapshot. This field is active only if you
choose Zoom or Fixed size in the Image size selection list.
• Alignment: Only reports in PDF or RTF format support this property. Options are:
• Auto
• Right
• Left
• Center
• Title: Specifies text to appear above the snapshot.
• Caption: Specifies text to appear under the snapshot.
Class
rptgen_hg.chg_ax_snap
See Also
Axes Loop, Figure Loop, Figure Snapshot, Graphics Object Loop, Handle
Graphics Linking Anchor, Handle Graphics Name, Handle Graphics
Parameter, Handle Graphics Property Table, Handle Graphics Summary
Table
10-10
Chapter/Subsection
Chapter/Subsection
Group portions of report into sections with titles
Description
This component groups portions of the report into sections. Each section has a title and
content.
Chapter Numbering
By default, chapters are numbered and sections are not numbered. Specify chapter and
section numbering using a stylesheet. For more information about chapter and section
numbering options in Web and print stylesheets, see “Report Output Format”.
Section Title
• Title: Specifies a title to display in the generated report:
1 In the Report Options dialog box, set File format to one of these values:
10-11
10 Components — Alphabetical List
To take effect, the style you specify must be defined in the template that you
use to generate the report. For example, if you use a Word template that defines
a Heading 2 style, you can enter Heading 2 as the style name. For more
information about template styles, see “Report Conversion Templates”.
• Numbering: Specifies a numbering style for the report:
Class
rptgen.cfr_section
See Also
Empty Component, Image, Link, List, Paragraph, Table, Text, Title Page
10-12
Comment
Comment
Insert comment into XML source file created by report generation process
Description
This component inserts a comment into the XML source file created by the report-
generation process. This comment is not visible in the generated report.
This component can have children. Child components insert their output into the XML
source file, but this does not appear in the generated report.
1 Edit the XML source file (which has the same name as your report file, but has a xml
extension).
2 Find the comment area in the XML source file by locating the comment tags <-- and
-->.
3 Remove the comment tags.
4 Convert the XML source file using the rptconvert command.
Properties
• Comment text: Specifies comments to include in the report.
• Show comment in Generation Status window: Displays comments in the
Generation Status tab while the report generates.
• Status message priority level: Specifies the priority level of the status messages
that appear during report generation. Priority options range from 1 Error
messages only to 6 All messages. The default is 3 Important messages. This
option is only available if you select the Show comment in Generation Status
window option.
10-13
10 Components — Alphabetical List
Class
rptgen.crg_comment
See Also
“Convert XML Documents to Different File Formats”, Import File, Nest Setup
File, Stop Report Generation, Time/Date Stamp
10-14
Empty Component
Empty Component
Group components to move, activate, or deactivate them, or create blank space in list
Description
This component does not insert anything into the generated report. It can have any
component as a child. You can use it to group components together so that you can easily
move, activate, or deactivate them, or create a blank space in a list.
If the MATLAB Report Generator software does not recognize a given component when
loading a report setup file, it replaces the unrecognized component with this component.
Class
rptgen.crg_empty
See Also
Chapter/Subsection, Image, Link, List, Paragraph, Table, Text, Title Page
10-15
10 Components — Alphabetical List
Description
This component evaluates a specified MATLAB expression. You can include code and/or
command-line output in the report.
Properties
• Insert MATLAB expression in report: Causes the MATLAB expression that this
component evaluates to appear in the report.
• Display command window output in report: Includes the command window
output that results from the evaluation of the specified MATLAB expression.
• Expression to evaluate in the base workspace: Specifies the expression to
evaluate in the MATLAB workspace. .
If you are using Simulink Report Generator, then you can use functions such as
Rptgen.getReportedBlock to filter the modeling elements on which to report
and to perform special reporting on specific elements. For more information, in the
Simulink Report Generator documentation, see “Loop Context Functions”.
• Evaluate this expression if there is an error: Evaluates another MATLAB
expression if the specified expression produces an error. You must enter in this field
the expression to evaluate in case of an error.
If you do not change the default error handling code, then when you generate the
report, and there is an error in the MATLAB code that you added:
• If you clear Evaluate this expression if there is an error check box, then the
complete report is generated, without displaying an error message at the MATLAB
command line.
• If you select Evaluate this expression if there is an error check box, then
the complete report is generated and an error message appears at the MATLAB
command line.
10-16
Evaluate MATLAB Expression
To stop report generation when an error occurs in the MATLAB code that you added,
change the second and third lines of the following default error handling code, as
described below:
warningMessageLevel = 2;
displayWarningMessage = true;
failGenerationWithException = false;
failGenerationWithoutException = false;
To stop report generation and display an exception, change the default code to:
displayWarningMessage = false;
failGenerationWithException = true;
To stop report generation without displaying an exception, change the default code to:
displayWarningMessage = false;
failGenerationWithoutException = true;
If you want to completely replace the default error handling code, use the
evalException.message variable in your code to return information for the
exception.
Class
rptgen.cml_eval
See Also
Insert Variable, MATLAB Property Table, MATLAB/Toolbox Version Number,
Variable Table
10-17
10 Components — Alphabetical List
Figure Loop
Apply child components to specified graphics figures
Description
This component applies each child component to specified figures in the report. For more
information about working with this component, see “Logical and Looping Components”.
Figure Selection
• Include figures
• Current figure only: Includes only the current figure in the report.
• Visible figures: Loops on all visible figures. The Data figures only option
is checked by default and excludes figures with HandleVisibility = 'off'
from the loop.
• All figures with tags: Loops on figures with specified tags, select When
you select a given tag, all figures with that tag appear in the loop, regardless of
whether each figure is visible or whether its HandleVisibility attribute is 'on'
or 'off'.
The tag field (located under All figures with tags) shows selected tags. To
add tags to this field, type in the tag names, separating them with new lines.
• Loop Figure List: Shows all figures that are included in the loop. If the report setup
file generates new figures or changes existing figures, figures in the Loop Figure
List are not the figures that are reported on.
Section Options
• Create section for each object in loop: Inserts a section in the generated report
for each object found in the loop.
• Display the object type in the section title: Inserts the object type automatically
into the section title in the generated report.
10-18
Figure Loop
• Create link anchor for each object in loop: Creates a hyperlink to the object in
the generated report.
Class
rptgen_hg.chg_fig_loop
See Also
Axes Loop, Axes Snapshot, Figure Snapshot, Graphics Object Loop,
Handle Graphics Linking Anchor, Handle Graphics Name, Handle Graphics
Parameter, Handle Graphics Property Table, Handle Graphics Summary
Table
10-19
10 Components — Alphabetical List
Figure Snapshot
Insert snapshot of Handle Graphics figure into report
Description
This component inserts a snapshot of a Handle Graphics figure into the report.
Format
• Image file format: Specifies the image file format. Select Automatic HG Format
to automatically choose the format best suited for the specified report output format.
Otherwise, choose an image format that your output viewer can read. Automatic HG
Format is the default option. Other options include:
• Automatic HG Format (uses the Handle Graphics file format selected in the
Preferences dialog box)
• Bitmap (16m-color)
• Bitmap (256-color)
• Black and white encapsulated PostScript
• Black and white encapsulated PostScript (TIFF)
• Black and white encapsulated PostScript2
• Black and white encapsulated PostScript2 (TIFF)
• Black and white PostScript
• Black and white PostScript2
• Color encapsulated PostScript
• Color encapsulated PostScript (TIFF)
• Color encapsulated PostScript2
• Color encapsulated PostScript2 (TIFF)
• Color PostScript
• Color PostScript2
• JPEG high quality image
10-20
Figure Snapshot
Print Options
• Paper orientation:
• Landscape
• Portrait
• Rotated
• Use figure orientation: Uses the orientation for the figure, which you set
with the orient command.
• Full page image (PDF only): In PDF reports, scales images to fit the full
page, minimizes page margins, and maximizes the size of the image by using
either a portrait or landscape orientation.
For more information about paper orientation, see the orient command in the
MATLAB documentation.
• Image size:
10-21
10 Components — Alphabetical List
• Custom: Specifies a custom image size. Set the image size in the Size field and
Units list.
• Size: Specifies the size of the figure snapshot in the form w h (width times height).
This field is active only if you choose Custom from the Image size selection list.
• Units: Specifies units for the size of the figure snapshot. This field is active only if you
choose Custom in the Image size selection list.
• Invert hardcopy: Sets print colors using the figure's InvertHardcopy property,
which inverts colors for printing. Options include:
• Automatic: Automatically changes dark axes colors to light axes colors. If the
axes color is a light color, it is not inverted.
• Invert: Changes dark axes colors to light axes colors and vice versa.
• Don't invert: Does not change the colors in the image.
• Use figure's InvertHardcopy setting: Uses the value of the
InvertHardcopy property set in the Handle Graphics image.
• Make figure background transparent: Makes the image background
transparent.
Display Options
• Scaling:
• Auto
10-22
Figure Snapshot
• Right
• Left
• Center
• Title: Specifies a title for the figure:
Class
rptgen_hg.chg_fig_snap
See Also
Axes Loop, Axes Snapshot, Figure Loop, Graphics Object Loop, Handle
Graphics Linking Anchor, Handle Graphics Name, Handle Graphics
Parameter, Handle Graphics Property Table, Handle Graphics Summary
Table
10-23
10 Components — Alphabetical List
For Loop
Iteratively execute child components
Description
This component functions like the MATLAB for loop, except that instead of executing a
statement, it executes its child components. It must have at least one child component to
execute.
Loop Type
The loop type can have incremented indices or a vector of indices. For more information
on for loops and indices, see for in the MATLAB documentation.
Workspace Variable
• Show index value in base workspace: Displays the loop index in the MATLAB
workspace while other components execute.
• Variable name: Allows you to specify the variable name. The default is
RPTGEN_LOOP.
• Remove variable from workspace when done: Removes the loop index from
the MATLAB workspace. This option is only available if you select the Show index
value in base workspace option.
10-24
For Loop
Class
rptgen_lo.clo_for
See Also
Logical Else, Logical Elseif, Logical If, Logical Then, While Loop
10-25
10 Components — Alphabetical List
Description
This component runs its child components for each Handle Graphics object that is
currently open in the MATLAB workspace. The component inserts a table into the
generated report.
Select Objects
• Exclude GUI objects (uicontrol, uimenu, ...): Excludes graphical interface objects,
such as uicontrol and uimenu, from the loop.
• Loop list: Specifies the loop level for Handle Graphics objects:
Section Options
• Create section for each object in loop: Inserts a section in the generated report
for each object found in the loop.
• Display the object type in the section title: Inserts the object type automatically
into the section title in the generated report.
• Create link anchor for each object in loop: Creates a hyperlink to the object in
the generated report.
10-26
Graphics Object Loop
Class
rptgen_hg.chg_obj_loop
See Also
Axes Loop, Axes Snapshot, Figure Loop, Figure Snapshot, Handle Graphics
Linking Anchor, Handle Graphics Name, Handle Graphics Parameter, Handle
Graphics Property Table, Handle Graphics Summary Table
10-27
10 Components — Alphabetical List
Description
This component designates a location to which links point. It should have a looping
component as its parent.
Properties
• Insert text: Specifies text to appear after the linking anchor.
• Link from current: Sets the current model, system, block, or signal as the linking
anchor:
Class
rptgen_hg.chg_obj_anchor
10-28
Handle Graphics Linking Anchor
See Also
Axes Loop, Axes Snapshot, Figure Loop, Figure Snapshot, Graphics Object
Loop, Handle Graphics Name, Handle Graphics Parameter, Handle Graphics
Property Table, Handle Graphics Summary Table
10-29
10 Components — Alphabetical List
Description
This component inserts the name of a Handle Graphics object as text into the report. You
can use this component to create a section title based on the current figure by making it
the first child component of a Chapter/Subsection component, and then selecting the
Chapter/Subsection component's Get title from first child component option.
Properties
• Display name as:
• Type Name
• Type –Name
• Type: Name
• Show name of current:
• Figure: Shows the name of the current figure. The first nonempty figure
parameter determines the name.
• Axes: Shows the name of the current axes. The first nonempty axes parameter
determines the name.
• Other Object: Sets the name of the current object to the figure's
CurrentObject parameter and its first nonempty parameter.
Class
rptgen_hg.chg_obj_name
10-30
Handle Graphics Name
See Also
Axes Loop, Axes Snapshot, Figure Loop, Figure Snapshot, Graphics Object
Loop, Handle Graphics Linking Anchor, Handle Graphics Parameter, Handle
Graphics Property Table, Handle Graphics Summary Table
10-31
10 Components — Alphabetical List
Description
This component inserts a property name/property value pair from a Handle Graphics
figure, axes, or other object.
Property Selection
• Get property from current: Reports on a specified Handle Graphics object:
Display Options
• Title: Specifies a title for the generated report:
10-32
Handle Graphics Parameter
Class
rptgen_hg.chg_property
See Also
Axes Loop, Axes Snapshot, Figure Loop, Figure Snapshot, Graphics Object
Loop, Handle Graphics Linking Anchor, Handle Graphics Name, Handle
Graphics Property Table, Handle Graphics Summary Table
10-33
10 Components — Alphabetical List
Description
This component inserts a table that reports on property name/property value pairs.
For more information on using this component, see “Property Table Components”.
• Figure
• Axes
• Object
• Filter by class: Specifies a class or classes for the table.
Table
You can select a preset table, which is already formatted and set up, from the list in the
upper-left corner of the attributes page.
To create a custom table, edit a preset table, such as Blank 4x4. Add and delete rows
and add properties. To open the Edit Table dialog box, click Edit.
For details about creating custom property tables, see “Property Table Components”.
• Preset table: Specifies the type of table to display the object property table.
• Defaults
• Callbacks
• Graphics
• Printing
• Blank 4x4
10-34
Handle Graphics Property Table
For the property name and property value to appear together in one cell, clear the
Split property/value cells check box. In this case, the table is in nonsplit mode,
which supports more than one property name/property value pair per cell. It also
supports text.
Before switching from nonsplit mode to split mode, make sure that you have only one
property name/property value pair per table cell. If you have more than one property
name/property value pair or any text, only the first property name/property value pair
appears in the report; subsequent pairs and text are omitted.
• Display outer border: Displays the outer border of the table in the generated
report.
Table Cells
Select table properties to modify. The selection in this pane affects the availability of
fields in the Title Properties pane.
If you select Figure Properties, only the Contents and Show options appear. If you
select any other object in the Table Cells pane, the Lower border and Right border
options appear.
Title Properties
• Contents: Enables you to modify the contents of the table cell selected in the Table
Cells pane. Options include:
• Left
• Center
• Right
10-35
10 Components — Alphabetical List
• Double justified
• Show as: Enables you to choose the format for the contents of the table cell. Options
include:
• Value
• Property Value
• PROPERTY Value
• Property: Value
• PROPERTY: Value
• Property - Value
• PROPERTY - Value
• Alignment: Aligns text in the table cells. Options are:
• Left
• Center
• Right
• Double-justified
• Lower border: Displays the lower border of the table in the generated report.
• Right border: Displays the right border of the table in the generated report.
Class
rptgen_hg.chg_prop_table
See Also
Axes Loop, Axes Snapshot, Figure Loop, Figure Snapshot, Graphics Object
Loop, Handle Graphics Linking Anchor, Handle Graphics Name, Handle
Graphics Parameter, Handle Graphics Summary Table
10-36
Handle Graphics Summary Table
Description
This component inserts a table that summarizes Handle Graphics object properties. Each
row in the table represents an object. Each column in the table represents a property.
You can specify object properties to include in the report.
Properties
• Object type: Specifies the object type to display in the generated report. Options
include:
• figure
• axes
• object
The available options in the Select Objects pane depend on your selection in the
Object type menu.
• Table title: Specifies a title for the table in the generated report. Options include:
Property Columns
• Property columns: Specifies object properties to include in the table in the
generated report.
• To add a property:
10-37
10 Components — Alphabetical List
Some entries in the list of available properties (such as Depth) are “virtual”
properties which you cannot access using the get_param command. The properties
used for property/value filtering in the block and system loop components must be
retrievable by the get_param. Therefore, you cannot configure your summary table to
report on all blocks of Depth == 2.
• Remove empty columns: Removes empty columns from the table in the generated
report.
• Transpose table: Changes the summary table rows into columns in the generated
report, putting the property names in the first column and the values in the other
columns.
Object Rows
Insert anchor for each row: Inserts an anchor for each row in the summary table.
Figure Selection
The options displayed in the Figure Selection pane depend on the object type selected
in the Object type list:
• Include figures
• Current figure only: Includes only the current figure in the report.
• Visible figures: Executes child components for figures that are currently
open and visible. The Data figures only option is checked by default. This
option excludes figures with HandleVisibility = 'off' from the loop.
• All figures with tags: Includes all figures with a specified tag regardless
of whether they are visible or their HandleVisibility parameter is 'on' or
'off'. The tag selection list, located under this option, shows available tags.
You can add tag names to this list.
• Data figure only (Exclude applications): Shows only data figures.
• Loop Figure List: Shows figures within the current set of figures to display.
• If Object type is axes, the following options appear:
10-38
Handle Graphics Summary Table
• Loop type:
Class
rptgen_hg.chg_summ_table
10-39
10 Components — Alphabetical List
See Also
Axes Loop, Axes Snapshot, Figure Loop, Figure Snapshot, Graphics Object
Loop, Handle Graphics Linking Anchor, Handle Graphics Name, Handle
Graphics Parameter, Handle Graphics Property Table
10-40
Image
Image
Insert image from external file into report
Description
This component inserts an image from an external file into the report. It can have the
Chapter/Subsection or Paragraph component as its parent. If the Paragraph
component is its parent, you must select the Insert as inline image check box.
Class
• File name: Specifies the image file name. You can enter this name manually, or use
the Browse button (...) to find the image file.
The image must be in a format that your viewer can read. An error like the following
appears if you specify the name of an image file that does not exist:
This field supports %<VariableName> notation. For more information about this
notation, see “%<VariableName> Notation” on page 10-98 on the Text component
reference page.
• Copy to local report files directory: Saves a copy of the image to a local report
files folder.
Display Options
• Scaling: Controls size of the image, as displayed in a browser. Making an image
larger using this option does not affect the storage size of the image, but the quality
of the displayed image may decrease as you increase or decrease the size of the
displayed image.
Generally, to achieve the best and most predictable display results, use the default
setting of Use image size.
10-41
10 Components — Alphabetical List
• Use image size: Causes the image to appear the same size in the report as on
screen (default).
• Fixed size: Specifies the number and type of units.
• Zoom: Specifies the percentage, maximum size, and units of measure.
• Size: Specifies the size of the snapshot in the format w h (width, height). This field is
active only if you choose Fixed size from the Scaling list.
• Max size: Specifies the maximum size of the snapshot in the format w h (width,
height). This field is active only if you choose Zoom from the Scaling list;
• Units: Specifies units for the size of the snapshot. This field is active only if you
choose Zoom or Fixed size in the Image size selection list.
• Alignment: Only reports in PDF or RTF formats support this format property.
Options are:
• Auto
• Right
• Left
• Center
• Title: Specifies text to appear above the snapshot.
• Caption: Specifies text to appear under the snapshot.
• Full page image (PDF only): In PDF reports, scales images to fit the full page,
minimizes page margins, and maximizes the size of the image by using either a
portrait or landscape orientation.
Preview
The image that you specify in the Image file name field appears in this pane. You
cannot preview Adobe PostScript images, or images with formats that the imread
function does not support, such as gif.
10-42
Image
Class
rptgen.cfr_image
See Also
Chapter/Subsection, Empty Component, List, Paragraph, Table, Text, Title
Page
10-43
10 Components — Alphabetical List
Import File
Import ASCII text file into report
Description
This component imports an ASCII text file into the report.
Properties
• File name: Specifies the name of the file to import into the text field. You can enter a
name, or use the Browse button (...) to find the file.
• Import file as: Specifies formatting for the imported file. Options include:
• Plain text (ignore line breaks): Imports the file as plain text without any
line breaks (no paragraphs). If you select this option, the Import File component
acts like the Text component, so it should have the Paragraph component as its
parent.
The examples in this section use the following text as the input file:
This is the first row of text from the imported file.
The second row follows a line break in the first row.
Plain text (ignore line breaks) produces the following formatting for the
example file:
This is the first row of text from the imported file.
The second row follows a line break in the first row.
10-44
Import File
The File Contents field displays the first few lines of the file to be imported.
10-45
10 Components — Alphabetical List
Class
rptgen.crg_import_file
See Also
Comment, Nest Setup File, Stop Report Generation, Time/Date Stamp
10-46
Insert Variable
Insert Variable
Insert variable values into report
Description
This component inserts the value (and, optionally, the name) of each the following
variables into the report:
Source
• Variable name: Specifies the name of the variable:
Display Options
• Title: Specify a title for the report:
10-47
10 Components — Alphabetical List
• Array size limit: Limits the width of the display in the generated report. Units
are in pixels. The size limit for a given table is the hypotenuse of the table width
and height [sqrt(w^2+h^2)]. The size limit of a given text string is the number of
characters squared. If you exceed the size limit, the variable appears in condensed
form, such as [64x64 double]. Setting a size limit of 0 displays the variable in full,
regardless of its size.
• Object depth limit: Specifies the maximum number of nesting levels to report on for
a variable value
• Object count limit: Specifies the maximum number of nested objects to report on for
a variable value
• Display as: Choose a display style from the menu:
Class
rptgen.cml_variable
10-48
Insert Variable
See Also
Evaluate MATLAB Expression, MATLAB Property Table, MATLAB/Toolbox
Version Number, Variable Table
10-49
10 Components — Alphabetical List
Link
Insert linking anchors or pointers into report
Description
This component inserts linking anchors or pointers into the report.
For a PDF report, if you open the report from MATLAB (for example, if you open the
report right after generating it), the link does not work. However, if you open a PDF
report outside of MATLAB (for example, from Adobe Acrobat), the link works properly.
Properties
• Link type: Select the type of link to insert into the report. Options include:
For a Web link, the link identifier options are context sensitive; their formats
differ depending on the link type you select. For example, to link to an external file
foo.txt, specify the link identifier as follows:
• On UNIX systems:
file:///home/janedoe/foo.txt
• On Microsoft Windows systems:
H:\foo.txt
For a link to a MATLAB command, enter matlab: followed by a space and the
MATLAB command that you want the link to execute.
• Link text: Specifies text to use in the link.
10-50
Link
Examples
10-51
10 Components — Alphabetical List
10-52
Link
• In Link text, enter For a detailed explanation, click here. (with the
period).
10-53
10 Components — Alphabetical List
10 Click the link to move to near the top of the report, to “Chapter 1. Magic Squares
Explained.”.
10-54
Link
Link to a Model
This example shows how to add a link to a Simulink model. To view the model, you must
have the Simulink software installed.
10-55
10 Components — Alphabetical List
Class
rptgen.cfr_link
See Also
Chapter/Subsection, Empty Component, List, Paragraph, Table, Text, Title
Page
10-56
List
List
Create bulleted or numbered list from cell array or child components
Description
This component creates a bulleted or numbered list from a cell array or child
components.
List Content
• Create list from workspace cell array: Creates the list from of the 1-by-
n or n-by-1 cell array. This option is not available when this component has
child components — in this case, the list automatically generates from the child
components.
• List title: Specifies the title of the list.
• List title style name: Specifies the style to use with the list title. To specify a style,
perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a list style defined in the template
that you use to generate the report. For more information about template styles,
see “Report Conversion Templates”.
List Formatting
• List style:
• Bulleted list
10-57
10 Components — Alphabetical List
• Numbered list.
• Numbering style: Specifies a numbering style for numbered lists. This setting is
supported only in the RTF/DOC report format. Options include:
• 1,2,3,4,...
• a,b,c,d,...
• A,B,C,D,...
• i,ii,iii,iv,...
• I,II,III,IV,...
• List style name: Specifies the style to use with the list. To specify a style, perform
these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be defined in the template that you use
to generate the report.
• Show parent number in nested list (1.1.a): Displays all level numbers in a nested
list. You can create a nested list by putting one cell array inside another or by nesting
one List component inside another. Following is an example of how a list appears
when you select this option:
1. Example
2. Example
2.1. Example
2.2. Example
2.2.a. Example
2.2.b. Example
3. Example
This option is not available if you select Show only current list value (a).
• Show only current list value (a): Displays only the current list value. Following is
an example of how a list appears when you select this option:
10-58
List
1. Example
2. Example
1. Example
2. Example
1. Example
2. Example
3. Example
This option is not available if you select Show parent number in nested list
(1.1.a).
This report setup file generates a report that includes the following bulleted lists:
• sky
• varname, the table from the variable
• test, a snapshot of the image
• grass
• clouds
• sun
• information
10-59
10 Components — Alphabetical List
• red
• green
• blue
Wherecolors is:
colors={'red','green','blue'}
Class
rptgen.cfr_list
See Also
Chapter/Subsection, Empty Component, Link, Paragraph, Table, Text, Title
Page
10-60
Logical Else
Logical Else
Specify an else condition for a Logical If component
Description
This component acts as an else when it is the child of the Logical If component. You
can specify this component in one of the following ways:
• if
then
else
• if
then
elseif
elseif
.
.
.
else
Properties
If component has no children, insert text: Inserts specified text into your report
when the Logical Else component has no child components. In this case, this
component acts like the Text component.
Class
rptgen_lo.clo_else
10-61
10 Components — Alphabetical List
See Also
For Loop, Logical Elseif, Logical If, Logical Then, While Loop
10-62
Logical Elseif
Logical Elseif
Specify an elseif condition for a Logical If component
Description
This component acts as an elseif when it is the child of the Logical If component.
You must specify this component as follows:
if
then
elseif
elseif
.
.
.
else
Properties
• Test expression: Specifies a MATLAB expression to evaluate.
• If component has no children, insert text: Inserts the specified text into the
report when the Logical Elseif component has no child components. In this case,
this component acts like the Text component.
Class
rptgen_lo.clo_else_if
See Also
For Loop, Logical Else, Logical If, Logical Then, While Loop
10-63
10 Components — Alphabetical List
Logical If
Specify logical if condition
Description
This component acts as a logical if; it can have the Logical Then, Logical Elseif,
or Logical Else components as children components. This component executes its
child components when the specified workspace expression is true. It displays a specified
string when it has no child components. You can specify this component as follows:
• if
then
• if
then
else
• if
then
elseif
elseif
.
.
.
else
Properties
• Test expression: Specifies a MATLAB expression to evaluate.
• If component has no children, insert text: Inserts specified text into the report
when the Logical If component has no children.
10-64
Logical If
Class
rptgen_lo.clo_if
See Also
For Loop, Logical Else, Logical Elseif, Logical Then, While Loop
10-65
10 Components — Alphabetical List
Logical Then
Specify a then condition for a Logical If component
Description
This component acts as a then when it is the child of the Logical If component. You
can specify this component as follows:
• if
then
• if
then
else
• if
then
elseif
elseif
.
.
.
else
Attributes
If component has no children, insert text: Inserts specified text into the report when
the Logical Then component has no children. In this case, this component acts like the
Text component.
Class
rptgen_lo.clo_then
10-66
Logical Then
See Also
For Loop, Logical Else, Logical Elseif, Logical If, While Loop
10-67
10 Components — Alphabetical List
Description
This component inserts a table that includes MATLAB object property name/property
value pairs.
Table
Select a preset table, which is already formatted and set up, in the preset table list in the
upper-left corner of the attributes page.
• Default
• Blank 4x4
To apply the preset table, select the table and click Apply.
• Split property/value cells: Splits property name/property value pairs into separate
cells. Select the Split property/value cells check box for the property name and
property value to appear in adjacent cells. In this case, the table is in split mode; only
one property name/property value pair per cell is allowed. If more than one name/
property pair exists in a cell, only the first pair appears in the report; subsequent
pairs are ignored.
Clear the Split property/value cells check box for a given property name and
property value to appear together in one cell. In this case, the table is in nonsplit
mode, which supports more than one property name/property value pair. It also
supports text.
Before switching from nonsplit mode to split mode, make sure that you have only one
property name/property value pair per table cell.
• Display outer border: Displays the outer border of the table in the generated
report.
10-68
MATLAB Property Table
• Table Cells: Modifies table properties. The selection in this pane affects the available
fields in the Cell Properties pane.
Cell Properties
Available options in the Cell Properties pane depend what you select for Table Cells.
If you select Workspace Properties, only the Contents and Show options appear. If
you select any other option, the Lower border and Right border options appear.
• Contents: Modifies the contents of the table cell selected in the Table Cells pane.
• Show as: Specifies the format for the contents of the table cell. Options include:
• Value
• Property Value
• PROPERTY Value
• Property: Value
• PROPERTY: Value
• Property - Value
• PROPERTY - Value
• Alignment: Specifies how to align the contents of the selected table cell in the Table
Cells field. Options include:
• Left
• Center
• Right
• Double justified
• Lower border: Displays the lower border of the table in the generated report.
• Right border: Displays the right border of the table in the generated report.
For details about using this dialog box to create custom property tables, see “Property
Table Components”.
10-69
10 Components — Alphabetical List
Class
rptgen.cml_prop_table
See Also
Evaluate MATLAB Expression, Insert Variable, MATLAB/Toolbox Version
Number, Variable Table
10-70
MATLAB/Toolbox Version Number
Description
Using the Table Filter, specify whether this component reports version information for
all installed MathWorks products or just those products required for a model.
For the specified set of products, this component inserts a table showing any of these
columns that you specify:
• Version number
• Release number
• Release date
• Is required for model
You can list all your MathWorks products by typing ver at the MATLAB command line.
Table Title
Table title: Specifies the table title. The default is version number.
Table Filter
Show only toolboxes required for model: When you select this option, the report
shows version information for only those products required for a model or chart. By
default, the report shows version information for all installed MathWorks products.
Note: This option uses the Simulink Manifest Tools analysis to determine what products
appear in the version information table. See “Analysis Limitations” for Manifest Tools
analysis limitations.
10-71
10 Components — Alphabetical List
Table Columns
• Version number: Includes the product version number (for example, 3.4) for all
installed MathWorks products or for only those products required for a model or
chart.
or
• Release number: Includes the MathWorks release number (for example, R2009b) for
all installed MathWorks products or for only those products required for a model or
chart.
• Release date: Includes the release date of for all installed MathWorks products or for
only those products required for a model.
• Is required for model: Indicates “Yes” for each MathWorks product required for a
model or chart.
Class
rptgen.cml_ver
See Also
Evaluate MATLAB Expression, Insert Variable, MATLAB Property Table,
Variable Table
10-72
Nest Setup File
Description
This component runs another report setup file at the point where the Nest Setup File
component is located in the current report setup file.
The components of the inserted report setup file are stored in the current report setup
file at the same level as the Nest Setup File component. Thus, inserted components
have the same parent component as the Nest Setup File component.
Properties
• Report filename: Specifies the name of the report setup file to import and run. You
can enter a path to the file or use the browse button (...) to find the file. You can
enter an absolute path or a relative path, relative to the report into which you nest
the report.
• Nest all reports with specified file name: Nests all reports with the same name
as specified in the Report filename option.
• Inline nested report in this report: Inserts the nested report in the original report
setup file where this component is located.
• Recursion limit: Allows you to nest a report setup file inside itself by setting a
recursion limit in this field. The recursion limit sets a limit on the number of times
the report setup file can run itself.
• Insert link to external report: Creates two separate reports, one using the original
report setup file and one using the nested report setup file. The report that includes
the nested report includes an absolute path link to the nested report.
• Link to external report is relative: If you select Insert link to external report,
then you can use the Link to external report is relative option to ensure the link
to the nested report is a relative link. This feature facilitates including the report on a
Web site.
• Increment file name to avoid overwriting: Appends a number to the file name of
report that includes the nested report, to preserve earlier versions of current report
file.
10-73
10 Components — Alphabetical List
The Nest Setup File dialog box displays the report description of the nested report, if the
nested report has a report description.
Example
In the following example, the report setup file R2 is nested in R1:
[-] Report - R1.rpt [-] Report - R2.rpt
[ ] Chapter [ ] 1
[-] B [ ] 2
[ ] Nest Setfile - R2.rpt [-] Chapter
[ ] C [ ] 4
[ ] D [ ] 5
The generated report is identical to the one generated by the following report setup file:
[-] Report - R1.rpt
[ ] Chapter
[-] B
[ ] 1
[ ] 2
[-] Section 1
[ ] 4
[ ] 5
[ ] C
[ ] D
Components that determine their behavior from their parents, such as Chapter/
Subsection, are affected by components in the parent report setup file.
Class
rptgen.crg_nest_set
See Also
Comment, Import File, Stop Report Generation, Time/Date Stamp
10-74
Paragraph
Paragraph
Insert paragraph text into report
Description
This component inserts a paragraph into the report. The paragraph text is taken from a
child text component, or from text that you enter in the Paragraph Text field.
Title Options
• No paragraph title (default): Specifies no title for the paragraph.
• Get title from first child: Gets the title of the paragraph from its first child
component, which should be a Text component.
• Custom title: Specifies a custom title for the paragraph.
Style Name
Specifies the style to use with the paragraph title. To specify a style, perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a paragraph style (or a linked
paragraph/character style for Word reports) defined in the template that you use
10-75
10 Components — Alphabetical List
to generate the report. For more information about template styles, see “Report
Conversion Templates”.
Paragraph Text
Enter paragraph text into this field. If the Paragraph component has child components,
the paragraph content is taken from the paragraph text and the child components;
otherwise, the Paragraph component inserts text from this field. If the Paragraph
component does not have any child components and you do not enter any text into this
field, nothing appears in the report.
Use the %<VariableName> notation in this field if you want to insert the value of
a variable from the MATLAB workspace. For more details about this notation, see
“%<VariableName> Notation” on page 10-98 on the Text component reference page.
Style Name
Specifies the style to use with the paragraph text. To specify a style, perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a paragraph style (or a linked
paragraph/character style for Word reports) defined in the template that you use to
generate the report. For example, if you use a Word template that defines a Normal
style, you can enter Normal as the style name. For more information about template
styles, see “Report Conversion Templates”.
10-76
Paragraph
Style
Note: If you use the Style Name field to specify a style for the paragraph text, the style
formats below override the corresponding formats specified in the style. For example,
selecting Bold makes the text bold, even if the specified style specifies regular weight
text.
Class
rptgen.cfr_paragraph
10-77
10 Components — Alphabetical List
See Also
Chapter/Subsection, Empty Component, Image, Link, List, Table, Text, Title
Page
10-78
Stop Report Generation
Description
This component acts like Stop during report generation. You can use this component
inside an if/then statement by using Logical and Flow Control components to halt the
report-generation process when the specified condition is true. When report generation
halts, an XML source file is created, but not converted.
Confirmation Properties
• Confirm before stopping generation: Generates a confirmation dialog box before
stopping report generation.
• Confirmation question: Specifies a confirmation question for the prompt. The
default is “Stop generating the report?”
• Halt button name: Specifies a name for the button that stops report generation. The
default is “Halt Generation”.
• Continue button name: Specifies a name for the button that continues report
generation. The default is “Continue Generation”.
Example
This example creates a simple report that takes a snapshot of the current figure. If there
is no current figure, the report generation automatically halts:
10-79
10 Components — Alphabetical List
Class
rptgen.crg_halt_gen
See Also
Comment, Import File, Nest Setup File, Time/Date Stamp
10-80
Table
Table
Insert parent of table
Description
This component is a parent of a component hierarchy that you specify to insert a table
into a report. Adding this component creates a hierarchy that defines a 2x2 table that
you modify to define your specific table.
Properties
• Title: Specifies a title for the table. Enter text or %<expr>. If you specify a table title,
text in the form Table #: precedes the table title.
• Title style name: Specifies the style to use with the table title. To specify a style,
perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be defined in a table style in the
template that you use to generate the report. For more information about
template styles, see “Report Conversion Templates”.
• Number of columns: Specifies the number of columns in the table. Enter a number
or %<expr>. A table must have at least one column.
• Table style name: Specifies the style to use with the table. To specify a style,
perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
10-81
10 Components — Alphabetical List
To take effect, the style you specify must be a table style in the template that
you use to generate the report. For more information about template styles, see
“Report Conversion Templates”.
• Table width options: Determines the width of the table.
• Auto: Automatically sets the table width based on the table contents.
• Specify: Enter the table width as either a percentage of the page width (for
example, 75%), or provide an absolute width for the table. You can specify a table
width in inches (in), picas (pi), or points (pt).
• Table spans page width: Spreads the table across the width of the page. If you clear
this property, the table uses the Table width options setting.
• Border: Specifies whether to draw border lines around the outside edges of the table.
For example, to draw a border line only at the top of the table, select Top.
• Between columns: Draw a vertical line on the right side of each column (except for
the last column) in the table.
To override this setting for a specific column or table entry, use the Column
separator property of the Table Column Specification or Table Entry components,
respectively.
• Between rows: Draw a horizontal line at the bottom of each row (except for the last
row) in the table.
To override this setting for a specific table column, row, or entry, use the Row
separator property of the appropriate component: Table Column Specification, Table
Row, or Table Entry.
• Horizontal entry alignment: Aligns the position of Table Entry component content
relative to the left and right sides of a table column.
10-82
Table
• For a specific table column, use the Table Column Specification Entry horizontal
alignment property.
• For a specific table entry, use the Table Entry Horizontal alignment property.
• Indent: Specifies the amount by which to indent the table from the left edge of an
HTML page or from the left margin of a Word page. The specified indent must be
positive and may include an optional unit specifier. For example, you can specify
0.67in. If you do not specify a unit, pixels is the assumed unit. Here are the unit
abbreviations.
• in
• cm
• mm
• pt
Note: To use this option, in the Report Options dialog box, set the File format field to
HTML (from template), Word (from template), or PDf(from template).
• Rotate table 90 degrees: For PDF and HTML output file formats, rotates the table
90 degrees counterclockwise to the direction of the text flow on the page.
Class
rptgen.cfr_ext_table
10-83
10 Components — Alphabetical List
See Also
Table Body, Table Column Specification, Table Entry, Table Footer,
Table Header, Table Row, Array-Based Table, Chapter/Subsection, Empty
Component, Image, Link, List, Paragraph, Text, Title Page
10-84
Table Body
Table Body
Insert parent of table body
Description
This component is a parent of the rows that define the body of a table.
This component must be a child of a Table component. Add Table Row components as
children to define the content of the table body.
Properties
• Style Name: Specifies the style to use with the table body. To specify a style, perform
these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a table style defined in the template
that you use to generate the report. For more information about template styles,
see “Report Conversion Templates”.
• Entry vertical alignment: Positions table entry content relative to the top and
bottom of the row in which the table entry appears.
To override this setting for a table header or footer, or for a table row within one
of those table elements, use the Entry vertical alignment property for the Table
Header, Table Footer, or Table Row component.
To override this setting for a specific table entry, use the Table Entry Vertical
alignment property.
10-85
10 Components — Alphabetical List
Class
rptgen.cfr_ext_table_body
See Also
Table, Table Column Specification, Table Entry, Table Footer, Table
Header, Table Row, Array-Based Table, Chapter/Subsection, Empty
Component, Image, Link, List, Paragraph, Text, Title Page
10-86
Table Column Specification
Description
Specifies the format of a table column. Add a Table Column Specification component for
only those columns that you do not want the default settings for the table.
Properties
• Column number: Specifies a column number for the column to which this column
specification applies. Enter a number or %<expr>. Avoid using the same column
number for two column specifications in the same table.
• Column name: Specifies the name of this column. The name appears in the Outline
pane of the Report Explorer. Enter text or a %<expr>.
A Table Entry component can use this name to specify that it starts or ends on this
column.
• Column width: Specifies the width of the column.
To specify an absolute column width, specify a number or %<expr>. Use one of these
units of measure: inches (in), picas (pi), or points (pt).
You can use relative widths for columns. If you use relative widths for one column
in a table, you must use relative widths for the other columns in the table. Specify
1* for one column, as a baseline. For other columns, specify the width as a factor of
the baseline column. The width of each column reflects its relative size. For example,
suppose a two column table is 6 inches wide. The width of the first column is set to
1*, and the width of the second column is set to 2*. The width of the first column is 2
inches, and the width of the second column is 4 inches.
• Entry horizontal alignment: Justifies the position of table entries in the column,
relative to the left and right sides of the column.
Use the Horizontal entry alignment setting of the Table component, or explicitly
set this property:
10-87
10 Components — Alphabetical List
To override this setting for a specific table entry, use the Table Entry Horizontal
alignment property for that table entry.
• Column separator: Use the Between columns setting of the Table component, or
explicitly set the Column separator property.
• True: Draws a vertical line at the right edge of the column (except for the last
column).
• False: Draws no vertical line at the right edge of the column.
• Row separator: Use the Between rows setting of the Table component, or explicitly
set the Row separator property.
• True: Draws a horizontal line at the bottom of each row in the column (except for
the bottom row).
• False: Does not draw a horizontal line at the bottom of each row in the column.
Class
rptgen.cfr_ext_table_colspec
See Also
Table, Table Body, Table Entry, Table Footer, Table Header, Table Row,
Array-Based Table, Chapter/Subsection, Empty Component, Image, Link, List,
Paragraph, Text, Title Page
10-88
Table Entry
Table Entry
Insert table entry
Description
Specifies the format of a table entry.
Note: Spanning columns and rows is not supported when the File format for generating
the report is set to Word Document(RTF)
Properties
• Horizontal alignment: Use the Entry horizontal alignment setting of the Table
Column Specification component for the column in which the table entry appears, or
explicitly set the Horizontal alignment property.
Use this property to override the Entry vertical alignment setting of the Table Row
component in which this table entry appears.
• Column separator: Use this property to override the Column separator setting
of the Table Column Specification component for the column in which the table entry
appears.
• True: Draws a vertical line at the right edge of the column for this table entry.
• False: Draws no vertical line at the right edge of the column for this table entry.
10-89
10 Components — Alphabetical List
• Row separator: Use this property to override the Row separator setting of the
Table Row component for the row in which the table entry appears.
• True: Draws a horizontal line at the bottom of the row, below the table entry.
• False: Does not draw a horizontal line at the bottom of the row, below the table
entry.
• Background color: Specifies the background color of the table entry. You can:
• Use Auto to apply the Background Color setting of the Table Row component in
which the table entry appears.
• Select a color from a list of colors.
• Enter %<expr>.
• Enter an RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade of
blue.
• Span start column name: Specifies the name of the column (as defined by the Table
Column Specification component) to use as the first (left side) of a set of spanned
columns for displaying the table entry content.
• Span end column name: Specifies the name of the column (as defined by the Table
Column Specification component) to use as the last (right side) of a set of spanned
columns for displaying the table entry.
• Rows spanned: Specifies the number of rows to span for the table entry. The
spanning starts with the table row in which you define the table entry and extends
below that row for the number of rows that you specify.
• Text orientation: Rotates table entry text in 90 degree increments, relative to the
page text flow.
To use the text orientation of the table row in which this table entry appears, select
Auto.
To override the Text orientation setting for the Table Row component in which this
table entry appears, select a rotation value.
• Rotated text width: Specifies the width of table entry text that you rotate (with the
Text orientation property).
Specify the text width in inches (in), picas (pi), or points (pt).
To avoid truncating the rotated text, set the Rotated text width to a value that
allows the display of the longest string in the table row.
10-90
Table Entry
Class
rptgen.cfr_ext_table_entry
See Also
Table, Table Body, Table Column Specification, Table Footer, Table
Header, Table Row, Array-Based Table, Chapter/Subsection, Empty
Component, Image, Link, List, Paragraph, Text, Title Page
10-91
10 Components — Alphabetical List
Table Footer
Insert parent of table footer
Description
This component is a parent of the Table Row components that define a table footer.
Properties
• Style Name: Specifies the style to use with the table footer. To specify a style,
perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a table style defined in the template
that you use to generate the report. For more information about template styles,
see “Report Conversion Templates”.
• Entry vertical alignment: Positions the table entry content relative to the top and
bottom of the table footer rows in which the table entries appear.
To override this setting for a specific row in the table footer, use the Entry vertical
alignment property of the Table Row component for that row.
10-92
Table Footer
Class
rptgen.cfr_ext_table_foot
See Also
Table, Table Body, Table Column Specification, Table Entry, Table Header,
Table Row, Array-Based Table, Chapter/Subsection, Empty Component, Image,
Link, List, Paragraph, Text, Title Page
10-93
10 Components — Alphabetical List
Table Header
Insert parent of table header
Description
This component is a parent of the Table Row components that define a table header.
Properties
• Style Name: Specifies the style to use with the table header. To specify a style,
perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a table style defined in the template
that you use to generate the report. For more information about template styles,
see “Report Conversion Templates”.
• Entry vertical alignment: Positions the table entry content relative to the top and
bottom of the table header rows in which the table entries appear.
To override this setting for a specific row in the table header, use the Entry vertical
alignment property of the Table Row component for that row.
10-94
Table Header
Class
rptgen.cfr_ext_table_head
See Also
Table, Table Body, Table Column Specification, Table Entry, Table Footer,
Table Row, Array-Based Table, Chapter/Subsection, Empty Component, Image,
Link, List, Paragraph, Text, Title Page
10-95
10 Components — Alphabetical List
Table Row
Insert parent of table row entries
Description
This component is a parent of Table Entry components that define a table row.
Properties
• Entry vertical alignment: Positions the table entry content relative to the top and
bottom of the table row in which the table entries appear.
Use this property to override the Entry vertical alignment setting of the Table
Header, Table Footer, or Table Body component in which the table row appears.
• Row separator: Use this property to override the Row separator setting of the
Table component.
• True: Draws a horizontal line at the bottom of the row (except for the last row).
• False: Does not draw a horizontal line at the bottom of the row.
• Background color: Specifies the background color of the table row. You can:
• Use Auto for the background color that the report stylesheet specifies, which for
stylesheets provided with MATLAB Report Generator is white by default.
• Select a color from a list of colors.
• Enter %<expr>.
• Enter an RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade of
blue.
• Row height: Specifies the height of the table row.
To let the table contents automatically set the row height, use Auto.
To specify an absolute height for this table row, select Specify and enter the height
in inches (in), picas (pi), or points (pt).
• Text orientation: Rotates text in the table entries in this table row, relative to the
page text flow.
10-96
Table Row
To override the text rotation for a specific table entry, use the Table Entry Text
orientation property for that table entry.
• Rotated text width: Specifies the width of table entry text that you rotate with the
Text orientation property.
Specify the text width in inches (in), picas (pi), or points (pt).
To avoid truncating the rotated text, set the Rotated text width to a value that
allows the display of the longest string in the table row.
To override the rotated text width for a specific table entry in the table row, use the
Table Entry Rotated text width property.
Class
rptgen.cfr_ext_table_row
See Also
Table, Table Body, Table Column Specification, Table Entry, Table Footer,
Table Header, Array-Based Table, Chapter/Subsection, Empty Component,
Image, Link, List, Paragraph, Text, Title Page
10-97
10 Components — Alphabetical List
Text
Format and insert text into report
Description
This component formats and inserts text into the report. It must have the Paragraph
component as its parent.
Properties
• Text to include in report: Specifies text to include in the report.
• Style Name: Specifies the style to use with the text. To specify a style, perform these
steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a paragraph (or a linked paragraph/
character style for Word reports) defined in the template that you use to generate
the report. For more information about template styles, see “Report Conversion
Templates”.
%<VariableName> Notation
You can enter %<VariableName> in this field (and in any field where the text appears
blue) to include the value of a variable from the base MATLAB workspace. You cannot
enter more than one variable in %<>. If you enter an invalid variable name, the report
includes the text %<VariableName> instead of the value of the variable.
10-98
Text
Example
1 Enter the following text:
I have a %<ObjName> and it has %<NumLeaves> leaves.
The word '%<ObjName>' has %<size(ObjName)> letters.
2 Set ObjName = "plant" and NumLeaves = 3.
3 Generate the report. It looks as follows:
I have a plant and it has 3 leaves.
The word 'plant' has 5 letters.
Style
Note: If you use the Style Name field to specify a style for this text component, the style
formats below override the corresponding formats specified in the style. For example,
selecting Bold makes the text bold, even if the specified style specifies regular weight
text.
10-99
10 Components — Alphabetical List
Class
rptgen.cfr_text
See Also
Chapter/Subsection, Empty Component, Image, Link, List, Paragraph, Table,
Title Page
10-100
Time/Date Stamp
Time/Date Stamp
Insert time and date of report generation into report
Description
This component inserts the time and date of the report generation into your report as
text. It must have the Paragraph or Chapter/Subsection component as its parent.
Prefix
Include text before stamp : Includes text before the time/date stamp. Specify the text
in the corresponding field.
• 12-hour
• 24-hour
• Time Separator: Specifies a separation marker between hours, minutes, and
seconds. Options include:
10-101
10 Components — Alphabetical List
• Date order: Specifies the order in which the day, month, and year appear. Options
include:
• Long (December)
• Short (Dec)
• Numeric (12)
• Year display: Specifies how the month displays. Options include:
• Long (2007)
• Short (07)
Preview
This pane displays the time/date stamp to appear in the report.
10-102
Time/Date Stamp
Class
rptgen.crg_tds
See Also
Comment, Import File, Nest Setup File, Stop Report Generation
10-103
10 Components — Alphabetical List
Title Page
Insert title page at beginning of report
Description
This component inserts a title page at the beginning of the report. You can use it in a
report setup file as a child of a Chapter/Subsection component or by itself.
To use the Title Page component, you need to have a Chapter component in your report.
For PDF and HTML reports, you can use the Stylesheet Editor to position title page
elements (for example, title, copyright, and images) anywhere on the front or reverse side
of the title page in any order. You can specify the size, color, weight, and slant of text
elements. For details, see “Modify Title Page Properties”.
Properties
The text fields on this property pane support the %<VariableName> notation. For
more details, see “%<VariableName> Notation” on page 10-98 on the Text component
reference page.
Main Tab
Title
• Title: Specifies the title of the report. The title is in a large font.
• Subtitle: Specifies the subtitle of the report. The subtitle is in a smaller font under
the title.
Options
• Author:
10-104
Title Page
The author name appears under the subtitle, in a smaller font than the subtitle.
• Include report creation date: Includes the date that the report is created. Choose
the date format in the corresponding list.
• Include copyright holder and year: Includes copyright holder and year
information.
• Display legal notice on title page: Includes the legal notice, report creation date,
and copyright information on the title page of PDF and Microsoft Word reports.
Image Tab
File
• File name: Specifies the file name of an image to appear under the subtitle, on the
title page.
• Copy to local report files directory: Copies the image file into the folder in which
the report file is located.
Display Options
• Scaling: Controls size of the image, as displayed in a browser. Making an image
larger using this option does not affect the storage size of the image, but the quality
of the displayed image may decrease as you increase or decrease the size of the
displayed image.
Generally, to achieve the best and most predictable display results, use the default
setting of Use image size.
• Use image size: Causes the image to appear the same size in the report as on
screen (default).
• Fixed size: Specifies the number and type of units.
• Zoom: Specifies the percentage, maximum size, and units of measure.
• Size: Specifies the size of the snapshot in the form w h (width, height). This field is
active only if you choose Fixed size in the Scaling list
10-105
10 Components — Alphabetical List
• Alignment: Only reports in PDF or RTF format support this property. Options
include:
• Auto
• Right
• Left
• Center
Abstract Tab
• Abstract Text: Specifies an optional abstract for the report.
• Style Name: Specifies the style to use with the abstract text. To specify a style,
perform these steps.
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a paragraph (or a linked paragraph/
character style for Word reports) defined in the template that you use to generate
the report. For example, if you use a Word template that defines a Normal style,
you can enter Normal as the style name. For more information about template
styles, see “Report Conversion Templates”.
Style
Note: If you use the Style Name field to specify a style for this text, the style formats
below override the corresponding formats specified in the style. For example, selecting
Bold makes the text bold, even if the specified style specifies regular weight text.
10-106
Title Page
1 In the Report Options dialog box, set File format to one of these values:
To take effect, the style you specify must be a paragraph (or a linked paragraph/
character style for Word reports) defined in the template that you use to generate
the report. For example, if you use a Word template that defines a Normal style,
you can enter Normal as the style name. For more information about template
styles, see “Report Conversion Templates”.
Style
Note: If you use the Style Name field to specify a style for this text, the style formats
below override the corresponding formats specified in the style. For example, selecting
Bold makes the text bold, even if the specified style specifies regular weight text.
10-107
10 Components — Alphabetical List
Class
rptgen.cfr_titlepage
See Also
Chapter/Subsection, Empty Component, Image, Link, List, Paragraph, Table,
Text
10-108
Variable Table
Variable Table
Insert table that displays all the variables in the MATLAB workspace
Description
This component inserts a table that displays all the variables in the MATLAB workspace.
Tip Find all the variables in the MATLAB workspace by typing whos at the command
line.
Source Workspace
Read variables from:
Table Title
• Table title:
• Automatic (Variables from MATLAB workspace): Sets the table title to the
name of a MATLAB variable.
• Custom: Specifies a custom title.
• Table Columns:
10-109
10 Components — Alphabetical List
Note: Large variable arrays collapse to [MxN CLASS]. For example, if you have a
300-by-200 double array, it appears in the report as [300x200 DOUBLE].
Example
The following is an example of a variable table that includes size, memory bytes, and
value information in the table columns.
Class
rptgen.cml_whos
See Also
Evaluate MATLAB Expression, Insert Variable, MATLAB Property Table,
MATLAB/Toolbox Version Number
10-110
While Loop
While Loop
Iteratively execute child components while a specified condition is true
Description
This component iteratively executes its child components while a specified condition is
true. The While Loop component must have at least one child component; the purpose
of this component is to run its children several times. If it does not have any children,
this component does not add anything to the report.
Logic Properties
• Continue looping if this expression is true: Specifies a string to evaluate. This
string must be a valid MATLAB expression that evaluates to 1 or 0 (true or false).
d=(a>b/c)
returns:
d = 1
Because 1 is greater than b/c (2/3), this expression is true and evaluates to 1.
• Limit number of loops to: Allows you to prevent infinite loops. Use the left and
right arrows to increase or decrease the number of loops.
• Initialize with this expression: Initializes the loop with a valid MATLAB
expression.
10-111
10 Components — Alphabetical List
Class
rptgen_lo.clo_while
See Also
For Loop, Logical Else, Logical Elseif, Logical If, Logical Then
10-112
11
compwiz
Create custom MATLAB Report Generator components
Syntax
compwiz
compwiz ('–browse')
compwiz ('–v1browse')
compwiz (rptgen.cfr_list)
Description
The Create Component dialog box creates a framework for custom report components.
For more information, see “Create Custom Components”.
• compwiz with no arguments displays the Component Editor in the Report Explorer.
• compwiz ('–browse') displays a list of components from which to derive a new
component.
• compwiz ('–v1browse') displays a list of legacy (v1.x) components from which to
derive a new component.
• compwiz (rptgen.cfr_list) initializes the Component Editor with the settings of
the referenced components.
More About
• “Create Custom Components”
See Also
setedit | report | rptconvert | rptlist
11-2
append
append
Class: mlreportgen.dom.Container
Package: mlreportgen.dom
Syntax
domObjOut = append(containerObj,domObj)
Description
domObjOut = append(containerObj,domObj) appends the DOM object to the
specified container object.
Input Arguments
containerObj — Container object to append DOM object to
mlreportgen.dom.Container object
• mlreportgen.dom.CustomElement
• mlreportgen.dom.Container
• mlreportgen.dom.DocumentPart
• mlreportgen.dom.FormalTable
• mlreportgen.dom.Group
• mlreportgen.dom.ExternalLink
11-3
11 Functions – Alphabetical List
• mlreportgen.dom.HTML
• mlreportgen.dom.HTMLFile
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.OrderedList
• mlreportgen.dom.Paragraph
• mlreportgen.dom.RawText
• mlreportgen.dom.Table
• mlreportgen.dom.Text
• mlreportgen.dom.TemplateHole
• mlreportgen.dom.UnorderedList
Output Arguments
domObjOut — Appended document element
document element object
• mlreportgen.dom.CustomElement
• mlreportgen.dom.Container
• mlreportgen.dom.DocumentPart
• mlreportgen.dom.FormalTable
• mlreportgen.dom.Group
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.HTML
• mlreportgen.dom.HTMLFile
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.OrderedList
11-4
append
• mlreportgen.dom.Paragraph
• mlreportgen.dom.RawText
• mlreportgen.dom.Table
• mlreportgen.dom.Text
• mlreportgen.dom.TemplateHole
• mlreportgen.dom.UnorderedList
Examples
Append Content to Container
c = Container();
Append content to the container and append the container to the report.
append(c,Paragraph('Hello'));
append(c,Table(magic(5)));
append(rpt,c);
See Also
mlreportgen.dom.Container | mlreportgen.dom.Group
Introduced in R2015a
11-5
11 Functions – Alphabetical List
clone
Class: mlreportgen.dom.Container
Package: mlreportgen.dom
Syntax
clonedContainer = clone(sourceContainer)
Description
clonedContainer = clone(sourceContainer) copies (clones) the specified
container.
Input Arguments
sourceContainer — Container object to copy
mlreportgen.dom.Container object
Output Arguments
clonedContainer — Copied container object
mlreportgen.dom.Container object
Examples
Copy Container Object
Create a container object. Microsoft Word output ignores the HTML container element
tag (in this example, the div tag).
11-6
clone
import mlreportgen.dom.*;
rpt = Document('MyReport','docx');
c = Container();
Append content to the container and append the container to the report.
append(c,Paragraph('Hello'));
append(c,Table(magic(5)));
append(rpt,c);
See Also
mlreportgen.dom.Container | mlreportgen.dom.Group
Introduced in R2015a
11-7
11 Functions – Alphabetical List
mlreportgen.dom.CustomElement.append
Package: mlreportgen.dom
Syntax
customElementOut = append(customElementObj,domObj)
Description
customElementOut = append(customElementObj,domObj) appends an element to
a custom element.
Examples
Append Text to a Custom Element
This example shows how to add a custom element that provides a check box in an HTML
report.
input1 = CustomElement('input');
input1.CustomAttributes = {
CustomAttribute('type', 'checkbox'), ...
CustomAttribute('name', 'vehicle'), ...
CustomAttribute('value', 'Bike'), ...
};
append(input1, Text('I have a bike'));
Append the custom element to an ordered list and display the report.
ol = OrderedList({input1});
11-8
mlreportgen.dom.CustomElement.append
append(d,ol);
close(d);
rptview('test','html');
Input Arguments
customElementObj — Custom element to append content to
mlreportgen.dom.CustomElement object
Output Arguments
customElementOut — Appended custom element
mlreportgen.dom.CustomElement object
See Also
mlreportgen.dom.CustomAttribute | mlreportgen.dom.CustomElement
11-9
11 Functions – Alphabetical List
addHTML
Class: mlreportgen.dom.Document
Package: mlreportgen.dom
Syntax
htmlObjOut = addHTML(documentObj,htmlText)
Description
htmlObjOut = addHTML(documentObj,htmlText) converts a string of HTML text to
a group of DOM objects and appends the group to the Document object documentObj.
Input Arguments
documentObj — Document to append content to
mlreportgen.dom.Document object
Output Arguments
htmlObjOut — HTML object with appended content
mlreportgen.dom.HTML object
11-10
addHTML
Examples
Append HTML Text to Document
Create an HTML object from HTML text to use for a Microsoft Word report.
import mlreportgen.dom.*;
rpt = Document('HTMLToWordReport','docx');
htmlObj = addHTML(rpt,...
'<p><b>Hello</b> <i style="color:green">World</i></p>');
See Also
mlreportgen.dom.HTML | mlreportgen.dom.HTMLFile
More About
• “Appending HTML to DOM Reports”
Introduced in R2015a
11-11
11 Functions – Alphabetical List
addHTMLFile
Class: mlreportgen.dom.Document
Package: mlreportgen.dom
Syntax
documentObjOut = addHTMLFile(documentObj,htmlFilePath)
Description
documentObjOut = addHTMLFile(documentObj,htmlFilePath) appends HTML
file contents to a document.
Input Arguments
documentObj — Document to append content to
mlreportgen.dom.Document object
Output Arguments
documentObjOut — Document object with HTML file content appended
mlreportgen.dom.Document object
11-12
addHTMLFile
Examples
Append HTML File Contents to a Document
<head>
<title>My First HTML</title>
</head>
<body>
</body>
</html>
See Also
mlreportgen.dom.Document.addHTMLFile | mlreportgen.dom.HTML |
mlreportgen.dom.HTMLFile
11-13
11 Functions – Alphabetical List
More About
• “Appending HTML to DOM Reports”
Introduced in R2015a
11-14
mlreportgen.dom.Document.append
mlreportgen.dom.Document.append
Package: mlreportgen.dom
Syntax
domObjOut = append(docObj,textContent)
domObjOut = append(docObj,listContent)
domObjOut = append(docObj,tableContent)
domObjOut = append( ___ ,styleName)
domObjOut = append(docObj,domObj)
Description
domObjOut = append(docObj,textContent) appends text or numbers to a
document and returns a text element object.
domObjOut = append( ___ ,styleName) appends the specified content, using the
specified style.
Examples
Append an Ordered List Object
11-15
11 Functions – Alphabetical List
import mlreportgen.dom.*;
d = Document('mydoc','html');
close(d);
rptview('mydoc','html');
import mlreportgen.dom.*;
d = Document('mydoc','docx');
append(d,'This Is a Title','Title');
close(d);
rptview('mydoc','docx');
import mlreportgen.dom.*;
d = Document('mydoc');
table = append(d,{'row 1 - col 1' 'row 1 - col 2';...
'row 2 - col 1' 'row 2 - col 2'});
table.Style = {Border('double'),ColSep('solid'),RowSep('solid')};
close(d);
rptview('mydoc','html');
Input Arguments
docObj — Document to append content to
mlreportgen.dom.Document object
11-16
mlreportgen.dom.Document.append
• A string
• A number
• A Boolean value
• One of these DOM objects:
• mlreportgen.dom.Text
• mlreportgen.dom.Paragraph
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.HTML
• mlreportgen.dom.InternalLink
• mlreportgen.dom.Table
• mlreportgen.dom.Image
• mlreportgen.dom.CustomElement
• A horizontal one-dimensional array (for a sublist)
11-17
11 Functions – Alphabetical List
• A string
• A number
• A Boolean value
• One of the following DOM objects:
• mlreportgen.dom.Text
• mlreportgen.dom.Paragraph
• mlreportgen.dom.OrderedList
• mlreportgen.dom.UnorderedList
• mlreportgen.dom.Table
• mlreportgen.dom.Image
• mlreportgen.dom.CustomElement
• A horizontal one-dimensional array (for a sublist)
Example: {'row 1 - col 1' 'row 1 - col 2';'row 2 - col 1' 'row 2 - col
2'}
The style to use with the appended content. The style defines the appearance of the
document element in the output document.
Use a style that is defined in the stylesheet of the template of the document you append
content to.
• mlreportgen.dom.CustomElement
• mlreportgen.dom.DocumentPart
• mlreportgen.dom.DOCXSection
• mlreportgen.dom.FormalTable
• mlreportgen.dom.Group
• mlreportgen.dom.ExternalLink
11-18
mlreportgen.dom.Document.append
• mlreportgen.dom.HTML
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.OrderedList
• mlreportgen.dom.Paragraph
• mlreportgen.dom.RawText
• mlreportgen.dom.Table
• mlreportgen.dom.Text
• mlreportgen.dom.UnorderedList
Output Arguments
domObjOut — Appended document element
document element object
Document element created and appended. One of the following DOM objects:
• mlreportgen.dom.CustomElement
• mlreportgen.dom.DocPart
• mlreportgen.dom.DOCXSection
• mlreportgen.dom.FormalTable
• mlreportgen.dom.Group
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.HTML
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.OrderedList
• mlreportgen.dom.Paragraph
• mlreportgen.dom.RawText
• mlreportgen.dom.Table
11-19
11 Functions – Alphabetical List
• mlreportgen.dom.Text
• mlreportgen.dom.UnorderedList
See Also
mlreportgen.dom.Document
11-20
mlreportgen.dom.Document.close
mlreportgen.dom.Document.close
Package: mlreportgen.dom
Close document
Syntax
close(docObj)
Description
close(docObj) closes a document. Once a document is closed, you can no longer append
content to it. Closing the document outputs any remaining content, such as remaining
template text.
Examples
Close a Document
import mlreportgen.dom.*;
myReport = Document('mydoc','html');
append(myReport,Paragraph('This is an introduction'));
close(myReport);
rptview('mydoc','html');
Input Arguments
docObj — Document to close
mlreportgen.dom.Document object
11-21
11 Functions – Alphabetical List
See Also
mlreportgen.dom.Document | mlreportgen.dom.Document.open
11-22
mlreportgen.dom.Document.createAutoNumberStream
mlreportgen.dom.Document.createAutoNumberStream
Package: mlreportgen.dom
Syntax
streamOut = createAutoNumberStream(docObj,streamName)
streamOut = createAutoNumberStream(docObj,streamName,streamType)
streamOut = createAutoNumberStream(docObj,streamName,streamType,
initialValue)
Description
streamOut = createAutoNumberStream(docObj,streamName) creates a
numbering stream using Arabic numbers and an initial value of 0.
streamOut = createAutoNumberStream(docObj,streamName,streamType)
creates a numbering stream using the specified type of characters (Arabic numbers,
alphabetic, or Roman numerals) and an initial value corresponding to 0 (for example, a or
i).
streamOut = createAutoNumberStream(docObj,streamName,streamType,
initialValue) creates a numbering stream using the specified type of characters
(Arabic numbers, alphabetic, or Roman numerals) and specified initial value.
Examples
Create a Numbering Stream for Chapter Heading
import mlreportgen.dom.*;
myReport = Document('mydoc','html');
chapStream = createAutoNumberStream(myReport,'chapter','I');
for i=1:5
11-23
11 Functions – Alphabetical List
p = Paragraph('Chapter ');
p.Style = {CounterInc('chapter')};
p.WhiteSpace = 'pre';
append(p,AutoNumber('chapter'));
append(myReport, p);
end
close(myReport);
rptview(myReport.OutputPath,myReport.Type);
Input Arguments
docObj — Document to apply numbering stream to
mlreportgen.dom.Document object
Consider using a name that indicates the kinds of document element (for example, a
chapter heading) that you expect to apply the stream to.
Use one of these letters to specify the type of characters to use for the numbering values.
11-24
mlreportgen.dom.Document.createAutoNumberStream
Use a number, regardless of the type of stream. The initial value used by the stream
depends on the type of stream. For example, if you set initialValue to 0:
Output Arguments
streamOut — Numbering stream
mlreportgen.dom.AutoNumberStream object
More About
Tips
See Also
mlreportgen.dom.Document |
mlreportgen.dom.Document.createAutoNumberStream |
mlreportgen.dom.Document.getAutoNumberStream
11-25
11 Functions – Alphabetical List
mlreportgen.dom.Document.createTemplate
Package: mlreportgen.dom
Syntax
createTemplate(path)
createTemplate(path,type)
Description
createTemplate(path) creates a DOM template in the specified location. The file
extension indicates whether to create a Microsoft Word template (.dotx) or an HTML
template (.htmx).
Examples
Create a Word Template
import mlreportgen.dom.*
Document.createTemplate('MyWordTemplate.dotx','docx');
11-26
mlreportgen.dom.Document.createTemplate
Input Arguments
path — Path for new template
string
If you use the path argument without the type argument, for a Word template, include
the .dotx extension and for an HTML template, include the .htmx extension.
If you use both the path and type arguments, and path does not have an extension, the
createTemplate method appends the appropriate extension (.dotx or .htmx).
• 'html'— HTML output HTML output as a zipped or unzipped folder containing the
HTML document text, image, style sheet, and JavaScript files
• 'docx'— Word output
• 'html-file'— HTML output consisting of a single file that contains the text, style
sheets, JavaScript®, and images for the report
If you specify a template using the path argument, the template must be consistent with
the type argument. You must specify a Word template (.dotx) for Word output, an
HTML template package (.htmtx) for HTML output, and a single-file HTML template
(.html) for html-file output.
More About
Tips
See Also
mlreportgen.dom.Document | mlreportgen.dom.Template | unzipTemplate |
zipTemplate
11-27
11 Functions – Alphabetical List
mlreportgen.dom.Document.fill
Package: mlreportgen.dom
Syntax
fill()
Description
fill() fills the holes in a document with generated content. Use this method with a
class derived from the mlreportgen.dom.Document class.
Examples
Add a fill Method to Invoke Hole-Specific fill Methods
This example shows how to define a report that fills a CustomerName hole in a Word
template.
Create a Word or HTML template that has a CustomerName hole. This example assumes
that there is a Word template called CustomerLetter.dotx.
properties
CustomerName;
11-28
mlreportgen.dom.Document.fill
end
methods
function rpt = MyReport(filename,type,template)
rpt = rpt@mlreportgen.dom.Document(filename,type,template);
end
function fillCustomerName(rpt)
append(rpt,rpt.CustomerName);
end
end
end
More About
Tips
In the derived class, define fill methods to insert content for each hole in the template.
Use this signature:
fillHOLE_ID(docObj);
HOLE_ID is the ID of a hole defined by the template that the document uses, and docObj
is an instance of the derived class. When invoked on a derived Document object, the fill
method moves from the first hole in the document to the last, invoking the corresponding
fillHOLE_ID method at each hole. This approach eliminates the need for additional
code to loop through the holes in a template.
See Also
mlreportgen.dom.Document | mlreportgen.dom.Document.moveToNextHole
11-29
11 Functions – Alphabetical List
mlreportgen.dom.Document.getAutoNumberStream
Package: mlreportgen.dom
Syntax
autoNumStreamOut = getAutoNumberStream(docObj,streamName)
Description
autoNumStreamOut = getAutoNumberStream(docObj,streamName) returns the
specified numbering stream used by the document.
Examples
Return a Numbering Stream
import mlreportgen.dom.*;
myReport = Document('mydoc','html');
createAutoNumberStream(myReport,'chapterNum','I',1);
streamOut = getAutoNumberStream(myReport,'chapterNum')
streamOut =
StreamName: 'chapterNum'
CharacterType: 'roman'
CharacterCase: 'upper'
InitialValue: 1
Tag: 'dom.AutoNumberStream:500'
Id: '500'
11-30
mlreportgen.dom.Document.getAutoNumberStream
Input Arguments
docObj — Document that uses numbering stream
mlreportgen.dom.Document object
Output Arguments
autoNumStreamOut — Numbering stream used by document
mlreportgen.dom.AutoNumberStream object
See Also
mlreportgen.dom.AutoNumber | mlreportgen.dom.AutoNumberStream |
mlreportgen.dom.Document.createAutoNumberStream
11-31
11 Functions – Alphabetical List
mlreportgen.dom.Document.getCoreProperties
Package: mlreportgen.dom
Syntax
corePropertiesOut = getCoreProperties(path)
Description
corePropertiesOut = getCoreProperties(path) specifies the core OPC
properties for the document or template having the specified path.
Examples
Return Core Properties of a Document
import mlreportgen.dom.*;
myReport = Document('mydoc','docx');
append(myReport,'Hello world');
close(myReport);
coreProps = Document.getCoreProperties('mydoc.docx')
coreProps =
Category: []
ContentStatus: []
Creator: 'MathWorks'
Description: []
Identifier: []
Keywords: []
Language: []
11-32
mlreportgen.dom.Document.getCoreProperties
LastModifiedBy: ''
Revision: '2'
Subject: []
Title: ''
Version: []
Tag: 'dom.CoreProperties:203'
Id: '203'
Input Arguments
path — Path to document or template
string
Output Arguments
corePropertiesOut — Core properties of document or template
mlreportgen.dom.CoreProperties object
More About
• “Report Packages”
See Also
mlreportgen.dom.Document.getOPCMainPart |
mlreportgen.dom.Document.setCoreProperties | mlreportgen.dom.OPCPart
11-33
11 Functions – Alphabetical List
mlreportgen.dom.Document.getImageDirectory
Package: mlreportgen.dom
Syntax
imageDirectory = getImageDirectory(path,type)
Description
imageDirectory = getImageDirectory(path,type) gets the image folder of a
document or template package located at the specified path and of the specified type
(Microsoft Word or HTML). This is a static method. Invoke it on the Document class.
Examples
Get the Image Folder
Suppose that the main image folder of an HTML document named MyDoc.htmx resides
in images under the root of the package. To get the path, enter:
mlreportgen.dom.Document.getImageDirectory('MyDoc','html');
ans =
/images
Input Arguments
path — Path of document or template package
string
11-34
mlreportgen.dom.Document.getImageDirectory
Type document or template. For a Word document or template, specify 'docx'. For an
HTML document or template, specify 'html'.
Output Arguments
imageDirectory — Image folder of document
string
More About
• “Report Packages”
See Also
mlreportgen.dom.Document.getImagePrefix |
mlreportgen.dom.Document.getOPCMainPart |
mlreportgen.dom.Document.setCoreProperties | mlreportgen.dom.OPCPart
11-35
11 Functions – Alphabetical List
mlreportgen.dom.Document.getImagePrefix
Package: mlreportgen.dom
Syntax
imagePrefix = getImagePrefix(path,type)
Description
imagePrefix = getImagePrefix(path,type) gets the image name prefix of a
document or template package located at the specified path and of the specified type
(Microsoft Word or HTML). The DOM interface uses the prefix when generating internal
names of images appended to the document. This is a static method. Invoke it on the
Document class.
Examples
Get the Image Name Prefix
Suppose that the image name prefix of an HTML document named MyDoc.htmx is
image. To get the image name prefix, enter:
mlreportgen.dom.Document.getImagePrefix('MyDoc','html');
ans =
image
Input Arguments
path — Path of document or template package
string
11-36
mlreportgen.dom.Document.getImagePrefix
Type document or template. For a Word document or template, specify 'docx'. For an
HTML document or template, specify 'html'.
Output Arguments
imagePrefix — Image name prefix
string
More About
• “Report Packages”
See Also
mlreportgen.dom.Document.getImageDirectory
| mlreportgen.dom.Document.getOPCMainPart |
mlreportgen.dom.Document.setCoreProperties | mlreportgen.dom.OPCPart
11-37
11 Functions – Alphabetical List
mlreportgen.dom.Document.getMainPartPath
Package: mlreportgen.dom
Syntax
pathOut = getMainPartPath(docObj)
Description
pathOut = getMainPartPath(docObj) returns the full path of the main part of the
output package of the specified document. The main part is the file that contains the
XML or HTML markup for a document.
Examples
Get Path to Main Part of Output Package
This code returns the path to the main part of an HTML document named MyReport.
The main part is named index.html and it is in the root of the MyReport package. This
example assumes that there is a reports folder on the S: drive.
d = mlreportgen.dom.Document('S:\reports\MyReport','html');
d.PackageType='unzipped';
getMainPartPath(d)
's:\reports\MyReport\index.hml'
Input Arguments
docObj — Document that contains main part
mlreportgen.dom.Document object
11-38
mlreportgen.dom.Document.getMainPartPath
Output Arguments
pathOut — Path of main part of document output package
string
More About
• “Report Packages”
See Also
mlreportgen.dom.Document.getOPCMainPart |
mlreportgen.dom.Document.setCoreProperties | mlreportgen.dom.OPCPart
11-39
11 Functions – Alphabetical List
mlreportgen.dom.Document.getOPCMainPart
Package: mlreportgen.dom
Syntax
partOut = getOPCMainPart(path)
partOut = getOPCMainPart(path,docType)
Description
partOut = getOPCMainPart(path) returns the path of the main part (file) of a
package for a document, document part, or template, based on the specified path. The
returned path is relative to the root directory of the package, which is symbolized by a
forward slash (/). The main part is the file that contains the document or template XML
or HTML markup.
Examples
Get Path to Main Part of a Document Package
The example returns the path to the main part of an HTML document named
myDoc.htmx. The main part is named root.html, which is in the top-level folder of the
package.
import mlreportgen.dom.*;
myDocument = Document('myDoc','html');
append(myDocument,'Hello world');
close(myDocument);
11-40
mlreportgen.dom.Document.getOPCMainPart
mlreportgen.dom.Document.getOPCMainPart('MyDoc.htmx','html')
ans =
/root.html
Input Arguments
path — Path of document
string
If you use the path argument without the docType argument, include the .docx or
.htmx extension.
If you use both the path and docType arguments, getOPCMainPart appends an
extension of the appropriate type (.docx or .htmx).
Output Arguments
partOut — Path of main part of a package
string
The path to the main part of the document, document part, or template. The returned
path is relative to the root directory of the package, which is symbolized by a forward
slash (/).
More About
Tips
11-41
11 Functions – Alphabetical List
• “Report Packages”
See Also
mlreportgen.dom.Document.getMainPartPath |
mlreportgen.dom.Document.setCoreProperties | mlreportgen.dom.OPCPart
11-42
mlreportgen.dom.Document.moveToNextHole
mlreportgen.dom.Document.moveToNextHole
Package: mlreportgen.dom
Syntax
holeID = moveToNextHole(docObj)
Description
holeID = moveToNextHole(docObj) copies to the output document any text
between the current hole and the next hole in the document template. DOM creates an
mlreportgen.dom.RawText object for the text. This method makes the next hole the
current hole and returns the ID of that hole.
Examples
Move to Next Hole
import mlreportgen.dom.*;
myReport = Document('myDoc','docx');
moveToNextHole(myReport);
Input Arguments
docObj — Document
mlreportgen.dom.Document object
11-43
11 Functions – Alphabetical List
Output Arguments
holeID — Template hole ID
hole ID
The ID of the template hole that the method moves to (the new current hole).
Data Types: char
More About
Tips
The first time you invoke the moveToNextHole method, the DOM copies to the output
document all of the text up to the first hole in the template. Use Document.append
methods to add content to the output document to fill the first hole. The next time you
invoke moveToNextHole, the DOM copies to the output document all the text between
the first and second hole in the template. Then use Document.append methods to fill in
the second hole. In this way, you can successively fill all of the holes in a document.
See Also
mlreportgen.dom.Document | mlreportgen.dom.Document.fill
11-44
mlreportgen.dom.Document.open
mlreportgen.dom.Document.open
Package: mlreportgen.dom
Open document
Syntax
open(docObj)
Description
open(docObj) opens a document for appending content.
Examples
Open a Document
import mlreportgen.dom.*;
myReport = Document('myDoc','html');
open(myReport);
Input Arguments
docObj — Document to open
mlreportgen.dom.Document object
11-45
11 Functions – Alphabetical List
More About
Tips
• After you open a document, you can no longer change its generated document type or
the template.
• The append method for a document opens a document if the document is not already
opened. Therefore, you rarely need to use the open method.
See Also
mlreportgen.dom.Document | mlreportgen.dom.Document.close
11-46
mlreportgen.dom.Document.package
mlreportgen.dom.Document.package
Package: mlreportgen.dom
Syntax
partOut = package(docObj,opcPart)
Description
partOut = package(docObj,opcPart) adds a file specified by an OPC part object to
the OPC package of a document.
Examples
Add Files to a Document Package
This example shows how to use the package method to add special browser processing
code. In this example, the processData.js file operates on the data.json file. This
example assumes that there are data.json and processData.js files in the current
folder.
import mlreportgen.dom.*;
myReport = Document('myDoc','html');
package(myReport,OPCPart('/data/data.json','data.json'));
package(myReport,OPCPart('/js/processData.js','processData.js'))
close(myReport);
Input Arguments
docObj — Document OPC package to add files to
mlreportgen.dom.Document object
11-47
11 Functions – Alphabetical List
Output Arguments
partOut — Added OPC part file
mlreportgen.dom.OPCPart object
More About
• “Report Packages”
See Also
mlreportgen.dom.Document.getCoreProperties |
mlreportgen.dom.Document.getOPCMainPart | mlreportgen.dom.OPCPart |
unzipTemplate | zipTemplate
11-48
mlreportgen.dom.Document.setCoreProperties
mlreportgen.dom.Document.setCoreProperties
Package: mlreportgen.dom
Syntax
corePropertiesOut = setCoreProperties(path,corePropertiesObj)
Description
corePropertiesOut = setCoreProperties(path,corePropertiesObj) sets the
core OPC property values of the document or template having the specified path.
Examples
Set OPC Core Properties for a Document Package
This example shows how to use setCoreProperties to apply core property settings to a
report.
import mlreportgen.dom.*;
myReport = Document('mydoc','docx');
append(myReport,'Hello world');
close(myReport);
coreProps = Document.getCoreProperties('mydoc.docx');
coreProps.Title = 'MATLAB Example';
Document.setCoreProperties('mydoc.docx',coreProps)
In Windows Explorer, if you navigate to the mydoc.docx file, you can see that the Title
field says MATLAB Example.
Input Arguments
path — Path of document, document part, or template
string
11-49
11 Functions – Alphabetical List
Output Arguments
corePropertiesOut — OPC core properties
mlreportgen.dom.CoreProperties object
More About
• “Report Packages”
See Also
mlreportgen.dom.CoreProperties |
mlreportgen.dom.Document.getCoreProperties |
mlreportgen.dom.Document.getOPCMainPart
11-50
mlreportgen.dom.ExternalLink.append
mlreportgen.dom.ExternalLink.append
Package: mlreportgen.dom
Syntax
externalLinkObjOut = append(externalLinkObj,text)
externalLinkObjOut = append(externalLinkObj,text,styleName)
externalLinkObjOut = append(externalLinkObj,domObj)
Description
externalLinkObjOut = append(externalLinkObj,text) appends a Text object
constructed from the specified text string to the link.
Examples
• “Create Links”
Input Arguments
externalLinkObj — External link object to append custom element to
mlreportgen.dom.ExtermalLink object
11-51
11 Functions – Alphabetical List
The style to use with the appended text. The style defines the appearance of the
document element in the output document.
Use a style that is defined in the stylesheet of the template of the document you append
content to.
Output Arguments
externalLinkObjOut — External link with appended content
mlreportgen.dom.ExternalLink object
See Also
mlreportgen.dom.ExternalLink | mlreportgen.dom.InternalTarget |
mlreportgen.dom.LinkTarget
11-52
mlreportgen.dom.FormalTable.appendFooterRow
mlreportgen.dom.FormalTable.appendFooterRow
Package: mlreportgen.dom
Syntax
rowObjOut = appendFooterRow(tableObj,rowObj)
Description
rowObjOut = appendFooterRow(tableObj,rowObj) appends a row of table entries
to the footer of a table.
Examples
Append a Table Footer
Create a row (and its entries) for the footer. Use bold text for the text in the row.
rowForFooter = TableRow();
rowForFooter.Style = {Bold(true)};
col1Title = TableEntry('Column 1 footer');
col2Title = TableEntry('Column 2 footer');
append(rowForFooter,col1Title);
append(rowForFooter,col2Title);
11-53
11 Functions – Alphabetical List
footerRow = appendFooterRow(table,rowForFooter);
close(myReport);
rptview('myDoc','html');
Input Arguments
tableObj — Table
mlreportgen.dom.FormalTable object
Output Arguments
rowObjOut — Row appended to table footer
mlreportgen.dom.TableRow object
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.Table
11-54
mlreportgen.dom.FormalTable.appendHeaderRow
mlreportgen.dom.FormalTable.appendHeaderRow
Package: mlreportgen.dom
Syntax
rowObjOut = appendHeaderRow(tableObj,rowObj)
Description
rowObjOut = appendHeaderRow(tableObj,rowObj) appends a row of table entries
to the header of this table.
Examples
Append a Table Header
11-55
11 Functions – Alphabetical List
headerRow = appendHeaderRow(table,rowForHeader);
close(myReport);
rptview('myDoc','html');
Input Arguments
tableObj — Table
mlreportgen.dom.FormalTable object
Output Arguments
rowObjOut — Row appended to table header
mlreportgen.dom.TableRow object
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.Table
11-56
mlreportgen.dom.Group.append
mlreportgen.dom.Group.append
Package: mlreportgen.dom
Syntax
domObjOut = append(groupObj,domObj)
Description
domObjOut = append(groupObj,domObj) appends a DOM object to a group. Use
groups to append a set of document elements together.
Examples
Append a Paragraph to a Group
import mlreportgen.dom.*;
myReport = Document('myDoc','html');
x = 0:pi/100:2*pi;
y = sin(x);
plot1 = plot(x,y);
saveas(plot1,'plot1.png')
plotimage = Image('plot1.png');
para = Paragraph('Value of the sine function from 0 to 2pi');
groupForPlot = Group();
append(groupForPlot,para);
append(groupForPlot,plotimage);
append(myReport,groupForPlot);
close(myReport);
rptview('myDoc','html');
11-57
11 Functions – Alphabetical List
Input Arguments
groupObj — Group object to append DOM object to
mlreportgen.dom.Group object
• mlreportgen.dom.CustomElement
• mlreportgen.dom.DocumentPart
• mlreportgen.dom.FormalTable
• mlreportgen.dom.Group
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.HTML
• mlreportgen.dom.HTMLFile
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.OrderedList
• mlreportgen.dom.Paragraph
• mlreportgen.dom.RawText
• mlreportgen.dom.Table
• mlreportgen.dom.TemplateHole
• mlreportgen.dom.Text
• mlreportgen.dom.UnorderedList
Output Arguments
domObjOut — Appended document object
DOM object
11-58
mlreportgen.dom.Group.append
• mlreportgen.dom.CustomElement
• mlreportgen.dom.DocumentPart
• mlreportgen.dom.FormalTable
• mlreportgen.dom.Group
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.HTML
• mlreportgen.dom.HTMLFile
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.OrderedList
• mlreportgen.dom.Paragraph
• mlreportgen.dom.RawText
• mlreportgen.dom.Table
• mlreportgen.dom.TemplateHole
• mlreportgen.dom.Text
• mlreportgen.dom.UnorderedList
See Also
mlreportgen.dom.Document | mlreportgen.dom.DocumentPart |
mlreportgen.dom.DOCXSection | mlreportgen.dom.Group
11-59
11 Functions – Alphabetical List
append
Class: mlreportgen.dom.HTML
Package: mlreportgen.dom
Syntax
htmlObjOut = append(htmlObj,htmlText)
htmlObjOut = append(htmlObj,htmlObjToAppend)
Description
htmlObjOut = append(htmlObj,htmlText) converts HTML elements into DOM
objects and appends the objects to htmlObj.
Input Arguments
htmlObj — HTML object to append content to
mlreportgen.dom.HTML object
11-60
append
Output Arguments
htmlObjOut — HTML object with appended content
an mlreportgen.dom.HTML object
Examples
Append HTML text to an HTML Object
Create an HTML object from HTML text, to use for a Microsoft Word report.
import mlreportgen.dom.*;
rpt = Document('HTML2WordReport','docx');
htmlObj = HTML('<p><b>Hello</b> <i style="color:green">World</i></p>');
Append content to the HTML object. Append the HTML object to the document.
See Also
mlreportgen.dom.Document.addHTML | mlreportgen.dom.HTML |
mlreportgen.dom.HTMLFile
More About
• “Appending HTML to DOM Reports”
Introduced in R2015a
11-61
11 Functions – Alphabetical List
clone
Class: mlreportgen.dom.HTML
Package: mlreportgen.dom
Syntax
clonedHTMLObj = clone(sourceHTMLObj)
Description
clonedHTMLObj = clone(sourceHTMLObj) copies (clones) the specified HTML object,
including its children.
Input Arguments
sourceHTMLObj — HTML object to copy
mlreportgen.dom.HTML object
Output Arguments
clonedHTMLObj — HTML object with appended content
an mlreportgen.dom.HTML object
Examples
Copy an HTML Object
Create an HTML object from HTML text, to use for a Microsoft Word report.
11-62
clone
import mlreportgen.dom.*;
rpt = Document('ClonedHTMLReport','docx');
htmlObj1 = HTML('<p><b>Hello</b> <i style="color:green">World</i></p>');
Copy the HTML object and append the copy to the report.
htmlObj2 = clone(htmlObj1);
append(rpt,htmlObj2);
See Also
mlreportgen.dom.HTML | mlreportgen.dom.HTMLFile
More About
• “Appending HTML to DOM Reports”
Introduced in R2015a
11-63
11 Functions – Alphabetical List
append
Class: mlreportgen.dom.HTMLFile
Package: mlreportgen.dom
Syntax
htmlFileObjOut = append(htmlFileObj,htmlText)
htmlFileObjOut = append(htmlFileObj,htmlObjToAppend)
Description
htmlFileObjOut = append(htmlFileObj,htmlText) converts HTML elements into
DOM objects and appends the objects to htmlFileObj.
Input Arguments
htmlFileObj — HTMLFile object to append content to
mlreportgen.dom.HTMLFile object
11-64
append
Output Arguments
htmlFileObjOut — HTMLFile object with appended content
an mlreportgen.dom.HTMLFile object
Examples
Append HTML Text to an HTML Object
This example assumes that there is an HTML file called myHTMLfile.html in the
MATLAB current folder.
Create an HTMLFile object from HTML text to use for a Microsoft Word report.
import mlreportgen.dom.*;
rpt = Document('HTMLToWordReport','docx');
htmlFileObj = HTML('<p><b>Hello</b> <i style="color:green">World</i></p>');
Append content to the HTMLFile object and append the HTMLFile object to the
document.
close(rpt);
rptview(rpt.OutputPath);
11-65
11 Functions – Alphabetical List
See Also
mlreportgen.dom.HTML | mlreportgen.dom.HTMLFile
More About
• “Appending HTML to DOM Reports”
Introduced in R2015a
11-66
mlreportgen.dom.LinkTarget.append
mlreportgen.dom.LinkTarget.append
Package: mlreportgen.dom
Syntax
textObj = append(targetObj,text)
textObj = append(targetObj,text,styleName)
textObj = append(targetObj,textObj)
autoNumberObj = append(targetObj,autoNumberObj)
Description
textObj = append(targetObj,text) converts text to an mlreportgen.dom.Text
object, appends the text to the link target, and returns the text object.
Examples
Append Text to a Link Target
import mlreportgen.dom.*
d = Document('mydoc');
target = LinkTarget('home')
append(target,' - top of page')
11-67
11 Functions – Alphabetical List
append(d,target);
append(d,InternalLink('home','Go to Top');
close(d);
rptview('mydoc', 'html');
import mlreportgen.dom.*
d = Document('mydoc','docx');
number = AutoNumber('paragraph');
target = LinkTarget('para');
append(target,'number');
InternalLink('para','Link to paragraph');
q = Paragraph('This paragraph is not linked to.');
append(d,q);
PageBreakBefore(true);
p = Paragraph('This is the paragraph that is linked to.');
append(p,
p.Style = {CounterInc('paragraph'),PageBreakBefore(true)};
append(d,p);
close(d);
rptview('mydoc','docx');
Input Arguments
targetObj — Link target to append content to
mlreportgen.dom.LinkTarget object
11-68
mlreportgen.dom.LinkTarget.append
Output Arguments
textObj — Text object
mlreportgen.dom.Text object
See Also
mlreportgen.dom.AutoNumber | mlreportgen.dom.Text
11-69
11 Functions – Alphabetical List
mlreportgen.dom.MessageDispatcher.dispatch
Package: mlreportgen.dom
Syntax
dispatch(dispatcher,message)
Description
dispatch(dispatcher,message) dispatches a DOM status message.
Examples
Add and Dispatch a Progress Message
This example shows how to add a progress message to display when generating a report.
open(d);
dispatch(dispatcher,ProgressMessage('starting chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
append(d,p);
11-70
mlreportgen.dom.MessageDispatcher.dispatch
close(d);
rptview('test',doctype);
delete (l);
Check the progress messages in the MATLAB Command Window. The starting
chapter message appears, in addition to the predefined DOM progress messages.
Input Arguments
dispatcher — DOM message dispatcher
mlreportgen.dom.MessageDispatcher object
• mlreportgen.dom.ProgressMessage
• mlreportgen.dom.WarningMessage
• mlreportgen.dom.ErrorMessage
• mlreportgen.dom.DebugMessage
See Also
mlreportgen.dom.MessageDispatcher.getTheDispatcher |
mlreportgen.dom.MessageEventData | mlreportgen.dom.MessageFilter
11-71
11 Functions – Alphabetical List
mlreportgen.dom.MessageDispatcher.getTheDispatcher
Package: mlreportgen.dom
Syntax
getTheDispatcher
Description
getTheDispatcher returns the DOM message dispatcher. There is only one DOM
message dispatcher per MATLAB session.
Examples
Add a Dispatcher and Dispatch a Progress Message
This example shows how to return the DOM message dispatcher and use it to dispatch a
progress message.
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher, ProgressMessage('starting chapter',d));
p = Paragraph('Chapter 1');
p.Tag = 'chapter title';
11-72
mlreportgen.dom.MessageDispatcher.getTheDispatcher
append(d, p);
close(d);
rptview('test',doctype);
delete (l);
Check the progress messages in the MATLAB Command Window. The starting
chapter message appears, in addition to the predefined DOM progress messages.
See Also
mlreportgen.dom.MessageDispatcher.dispatch |
mlreportgen.dom.MessageEventData | mlreportgen.dom.MessageFilter
11-73
11 Functions – Alphabetical List
mlreportgen.dom.OrderedList.append
Package: mlreportgen.dom
Syntax
listOut = append(orderedList,listItemObj)
listOut = append(orderedList,listItems)
listOut = append(orderedList,list)
customElementOut = append(orderedList,customElementObj)
Description
listOut = append(orderedList,listItemObj) appends a list item to an ordered
list.
Examples
Append Three List Items
11-74
mlreportgen.dom.OrderedList.append
close(myReport);
rptview('myDoc','html');
close(myReport);
rptview('myDoc','html');
ol = OrderedList({'a1',{'a2','b2'},'b1'});
append(myReport,ol);
close(myReport);
rptview('myDoc','html');
Input Arguments
orderedList — Ordered list to append content to
mlreportgen.dom.OrderedList object
11-75
11 Functions – Alphabetical List
• A string
• A number
• A Boolean value
• One of the following DOM objects:
• mlreportgen.dom.Text
• mlreportgen.dom.Paragraph
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.InternalLink
• mlreportgen.dom.Table
• mlreportgen.dom.Image
• mlreportgen.dom.CustomElement
• Horizontal one-dimensional array (for a sublist)
To append an ordered list, use an OrderedList DOM object instead of using the
listContent argument.
11-76
mlreportgen.dom.OrderedList.append
The custom element must be a valid HTML or Word child of a list, depending on whether
the output type of the document to which this element is appended is HTML or Word.
Output Arguments
listOut — Ordered list
mlreportgen.dom.OrderedList object
See Also
mlreportgen.dom.ListItem | mlreportgen.dom.OrderedList |
mlreportgen.dom.UnorderedList
11-77
11 Functions – Alphabetical List
mlreportgen.dom.Paragraph.append
Package: mlreportgen.dom
Syntax
paraObjOut = append(paraObj,text)
paraObjOut = append(paraObj,text,styleName)
paraObjOut = append(paraObj,domObj)
Description
paraObjOut = append(paraObj,text) creates a text object containing the specified
text string and appends it to a paragraph.
Examples
Append a Text String
import mlreportgen.dom.*;
d = Document('mydoc','html');
close(d);
11-78
mlreportgen.dom.Paragraph.append
rptview('mydoc','html');
import mlreportgen.dom.*;
doc = Document('mydoc','docx');
close(doc);
rptview('mydoc','docx');
import mlreportgen.dom.*;
docLink = Document('mydocLink','html');
mathWorksLink = ExternalLink...
('http://www.mathworks.com/','MathWorks site');
para = Paragraph('Go to the ');
append(para, mathWorksLink);
append(docLink,para);
close(docLink);
rptview('mydocLink','html');
Input Arguments
paraObj — Paragraph to append content to
mlreportgen.dom.Paragraph object
11-79
11 Functions – Alphabetical List
Name of the style to define the appearance of the text. Use a style that is in the
stylesheet of the document that contains the paragraph.
You can append the following types of document element object to a paragraph:
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.Text
• mlreportgen.dom.CustomElement
If you specify a custom element, it must be a valid HTML or Word child of the
paragraph, based on the document output type.
Output Arguments
paraObjOut — Paragraph with appended content
mlreportgen.dom.Paragraph object
See Also
mlreportgen.dom.Document | mlreportgen.dom.Paragraph |
mlreportgen.dom.Paragraph.clone
11-80
mlreportgen.dom.Paragraph.clone
mlreportgen.dom.Paragraph.clone
Package: mlreportgen.dom
Syntax
clonedPara = clone(sourcePara)
Description
clonedPara = clone(sourcePara) copies (clones) the specified paragraph. The
resulting cloned paragraph includes the children of the source paragraph, but not the
parent.
Examples
Copy a Paragraph Object
import mlreportgen.dom.*;
myReport = Document('myDoc','html');
para1Copy =
OutlineLevel: []
Bold: 1
Italic: []
Color: []
BackgroundColor: []
11-81
11 Functions – Alphabetical List
Underline: []
WhiteSpace: []
FontFamilyName: []
FontSize: []
Strike: []
HAlign: []
OuterLeftMargin: []
FirstLineIndent: []
StyleName: []
Style: {[1x1 mlreportgen.dom.Bold]}
CustomAttributes: []
Children: [1x1 mlreportgen.dom.Text]
Parent: []
Tag: 'dom.Paragraph:15'
Id: '15'
Input Arguments
sourcePara — Paragraph object to copy
mlreportgen.dom.Paragraph object
Output Arguments
clonedPara — Copied paragraph object
mlreportgen.dom.Paragraph object
More About
Tips
• Use the clone method to append the same paragraph content more than once in a
document.
11-82
mlreportgen.dom.Paragraph.clone
• When you clone a paragraph, DOM copies all of the children objects of the source
paragraph, but not the parent of the paragraph.
• The cloned paragraph includes formats that you set in the source paragraph. The
cloned paragraph formats use the same format objects as the source paragraph. If
you change the format setting in the shared format object, the source and cloned
paragraphs reflect that change.
If you change a format setting in the cloned paragraph, then DOM creates a new
format object for the cloned paragraph, using the new format setting. For that format,
the source and cloned paragraph no longer share the same format object.
This example shows the relationship between the formats for the source and cloned
paragraphs.
1 Create a paragraph that uses a style that sets the Bold and Italic formats to
true.
import mlreportgen.dom.*;
myReport = Document('myDoc','html');
p = Paragraph('This is a paragraph');
append(myReport,p);
MyStyle = {Bold,Italic};
p.Style = MyStyle;
p.Bold
ans =
p.Italic
ans =
1
2 Clone the paragraph. The Bold and Italic formats are the same as those of the
source paragraph.
pClone = clone(p);
pClone.Bold
ans =
11-83
11 Functions – Alphabetical List
p.Italic
ans =
1
3 For the cloned paragraph, change turn off bold text. The change to the Bold
format in the cloned paragraph does not affect the text for the source paragraph.
The source paragraph text is still bold.
pClone.Bold = false;
p.Bold
ans =
1
4 In the style object (MyStyle) for the source paragraph, turn off italics. Now the
cloned paragraph does not use italics, because it shares the MyStyle setting for
the Italics format.
MyStyle(2).Value = false
pClone.Italic
ans =
See Also
mlreportgen.dom.Document | mlreportgen.dom.Paragraph |
mlreportgen.dom.Paragraph.append
11-84
mlreportgen.dom.ProgressMessage.formatAsHTML
mlreportgen.dom.ProgressMessage.formatAsHTML
Package: mlreportgen.dom
Syntax
htmlMessageOut = formatAsHTML(message)
Description
htmlMessageOut = formatAsHTML(message) returns the message text formatted
with HTML tags.
Examples
Format a Message as HTML
This example uses formatAsHTML with the Web command to display the progress
messages.
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
d.Tag = 'My report';
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsHTML));
open(d);
dispatch(dispatcher, ProgressMessage('starting chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'),...
CounterReset('table'),WhiteSpace('pre') };
append(p,AutoNumber('chapter'));
11-85
11 Functions – Alphabetical List
append(d,p);
close(d);
rptview('test',doctype);
delete (l);
Input Arguments
message — Progress message
mlreportgen.dom.ProgressMessage object
Output Arguments
htmlMessageOut — Progress message with HTML tagging
mlreportgen.dom.ProgressMessage object
See Also
mlreportgen.dom.MessageFilter | mlreportgen.dom.ProgressMessage |
mlreportgen.dom.ProgressMessage.formatAsText
11-86
mlreportgen.dom.ProgressMessage.formatAsText
mlreportgen.dom.ProgressMessage.formatAsText
Package: mlreportgen.dom
Syntax
textMessageOut = formatAsText(message)
Description
textMessageOut = formatAsText(message) returns the message text formatted as
text.
Examples
Format a Message with White Spaces
This example uses formatAsText with the Web command to display the progress
messages.
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
d.Tag = 'My report';
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher,ProgressMessage('starting chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'),...
CounterReset('table'),WhiteSpace('pre') };
append(p, AutoNumber('chapter'));
11-87
11 Functions – Alphabetical List
append(d,p);
close(d);
rptview('test',doctype);
delete(l);
Input Arguments
message — The DOM progress message
mlreportgen.dom.ProgressMessage object
Output Arguments
textMessageOut — DOM progress message formatted as text
mlreportgen.dom.ProgressMessage object
See Also
mlreportgen.dom.MessageFilter | mlreportgen.dom.ProgressMessage |
mlreportgen.dom.ProgressMessage.formatAsHTML
11-88
mlreportgen.dom.ProgressMessage.passesFilter
mlreportgen.dom.ProgressMessage.passesFilter
Package: mlreportgen.dom
Syntax
tf = passesFilter(message,filter)
Description
tf = passesFilter(message,filter) determines whether the message passes the
filter.
Examples
Determine Whether a Message Passes a Filter
This example shows how to add a progress message to display when generating a report.
Add a dispatcher and listener to the report. Configure the dispatcher to include debug
messages.
import mlreportgen.dom.*;
d = Document('test','html');
dispatcher = MessageDispatcher.getTheDispatcher;
dispatcher.Filter.DebugMessagesPass = true;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher, ProgressMessage('starting chapter',d));
p = Paragraph('Chapter ');
11-89
11 Functions – Alphabetical List
close(d);
rptview('test','html');
delete(l);
Check the progress messages in the MATLAB Command Window. In addition to the
predefined DOM progress messages, the starting chapter message added in this
example appears. The output also includes debug messages.
Input Arguments
message — DOM progress message
mlreportgen.dom.ProgressMessage object
Output Arguments
tf — Indication of whether the message passes the filter
a Boolean
• 1 — Messages passes the specified filter (the dispatcher handles the message)
• 0 — Messages fails the specified filter (the dispatcher ignores the message)
11-90
mlreportgen.dom.ProgressMessage.passesFilter
See Also
mlreportgen.dom.MessageFilter | mlreportgen.dom.ProgressMessage
11-91
11 Functions – Alphabetical List
mlreportgen.dom.Table.entry
Package: mlreportgen.dom
Syntax
tableEntryOut = entry(tableObj,row,column)
Description
tableEntryOut = entry(tableObj,row,column) returns the table entry for the
specified column of the specified row.
Examples
Color a table entry
Input Arguments
tableObj — Table containing the entry
mlreportgen.dom.Table object | mlreportgen.dom.FormalTable object
11-92
mlreportgen.dom.Table.entry
Index number of the column (in a left-to-right text flow table, the left-most column is 1).
Data Types: double
Output Arguments
tableEntryOut — Table entry object
mlreportgen.dom.TableEntry object
See Also
mlreportgen.dom.Table.row | mlreportgen.dom.TableEntry
11-93
11 Functions – Alphabetical List
mlreportgen.dom.Table.row
Package: mlreportgen.dom
Syntax
tableRowOut = row(tableObj,row)
Description
tableRowOut = row(tableObj,row) returns the table row at the specified row
number.
Examples
Color a Table Row
t = Table(magic(5));
te = row(t,2);
te.Style = {Color('red')};
append(myReport,t);
close(myReport);
rptview('myDoc','html');
Input Arguments
tableObj — Table containing entry
mlreportgen.dom.Table object | mlreportgen.dom.FormalTable object
11-94
mlreportgen.dom.Table.row
Output Arguments
tableRowOut — Table row object
mlreportgen.dom.TableRow object
See Also
mlreportgen.dom.TableEntry | mlreportgen.dom.TableRow
11-95
11 Functions – Alphabetical List
mlreportgen.dom.TableRow.append
Package: mlreportgen.dom
Syntax
entryOut = append(rowObj,entryObj)
Description
entryOut = append(rowObj,entryObj) appends an entry to a table row.
Examples
Append a Table Entry to a Row
Create three table rows with entries. Append each entry to a row using
append(row,te).
for i=1:3
row = TableRow();
te = TableEntry();
append(te,Text([num2str(i) ' - 1']));
append(row,te);
te = TableEntry();
append(te,Text([num2str(i) ' - 2']));
append(row,te);
append(table,row);
11-96
mlreportgen.dom.TableRow.append
end
close(myReport);
rptview('myDoc','html');
Input Arguments
rowObj — Row to append the table entry to
mlreportgen.dom.TableRow object
Output Arguments
entryOut — Appended table entry
mlreportgen.dom.TableEntry object
See Also
mlreportgen.dom.TableEntry | mlreportgen.dom.TableRow
11-97
11 Functions – Alphabetical List
report
Generate reports from report setup file
Syntax
report
report (filename,...)
report ( ___ ,-oOPATH)
report ( ___ ,-fFORMAT)
report ( ___ ,-genOption1,...)
[report1, report2, ...] = report (rptfile1, rptfile2, ...)
Description
• report with no arguments opens the Report Explorer. For more information on the
Report Explorer, see “Report Explorer”
• report (filename,...) generates a report from the specified report setup files.
You can specify one or more report setup files. When specifying the name of the report
setup file, omit the .rpt file name extension.
• report ( ___ ,-oOPATH) sets the name of the generated report. You can specify a
path or a single file name for the OPATH path argument.
• report ( ___ ,-fFORMAT) sets the output format and file name extension of the
generated report. Supported formats include:
11-98
report
Note: For reports that use the Word Document format, you must have Microsoft Word
software installed on the machine that you use to generate the report.
Examples
report ('simple-report','-o/tmp/index.html')
11-99
11 Functions – Alphabetical List
More About
• “Generate Reports”
See Also
setedit | rptconvert | rptlist | compwiz
11-100
rptconvert
rptconvert
Convert DocBook XML files into supported document formats
Syntax
rptconvert()
rptname = rptconvert (source)
rptname = rptconvert (source, format)
rptname = rptconvert (source, format, stylesheet)
...=rptconvert(...,'-view')
...=rptconvert(...,'-quiet')
...=rptconvert(...,'-verbose')
sheetlist = rptconvert('-stylesheetlist')
sheetlist = rptconvert('-stylesheetlist',format)
FORMATLIST = rptconvert('-formatlist')
Description
This function converts a DocBook XML source file created by the report-generation
process to a supported document format. For information about supported output
formats, see “Supported Report Formats”.
rptconvert() with no input arguments launches the converter. When input arguments
are passed to this function, rptconvert converts the XML document to the specified
format and displays status messages to the MATLAB Command Window.
source is the name of the DocBook XML file created by the report-generation process.
You can specify this file name with or without its file extension.
11-101
11 Functions – Alphabetical List
format is a unique identifier code for each output format type. If you omit this
argument, the XML file is converted to HTML format by default.
stylesheet is a unique identifier for a given stylesheet. If you omit this argument, the
default stylesheet for the selected format is used.
You can also pass the following flags to the input arguments:
Examples
Retrieve a list of available HTML stylesheets:
rptconvert('-stylesheetlist','html')
More About
• “Convert XML Documents to Different File Formats”
See Also
setedit | report | rptlist | compwiz
11-102
rptlist
rptlist
Retrieve list of all report setup files in MATLAB path
Syntax
rptlist
rptlist ('system_name')
list = rptlist
Description
rptlist with no arguments opens the Report Explorer, which lists available report
setup files in the MATLAB path.
rptlist ('system_name') opens the Report Explorer with the Simulink system's
ReportName property selected.
list = rptlist returns a list of report setup files in the MATLAB path.
See Also
setedit
11-103
11 Functions – Alphabetical List
rptview
Display DOM report
Syntax
rptview(reportPath)
rptview(reportPath,'pdf')
rptview(reportName,format)
Description
rptview(reportPath) displays the report reportPath in an appropriate viewer,
based on the file extension. You can use the Document.OutputPath property to specify
reportPath.
Examples
Display Report in HTML Viewer
Display an HTML report. Include the file extension when you specify the report name in
the rptview function.
import mlreportgen.dom.*;
d = Document('mydoc','html');
p = Paragraph('Hello World');
append(d,p);
close(d);
11-104
rptview
rptview('mydoc.htmx');
Use the rptview function to convert a Word report to PDF and display it in a PDF
viewer.
import mlreportgen.dom.*;
d = Document('mydoc','docx');
p = Paragraph('Hello World');
append(d,p);
close(d);
rptview('mydoc.docx','pdf');
p = Paragraph('Hello World');
append(d,p);
close(d);
rptview(d.OutputPath);
Create two reports with the same name, but with different formats and content. Specify
the format to display the appropriate report.
import mlreportgen.dom.*;
d = Document('mydoc','html');
p = Paragraph('Hello World');
append(d,p);
close(d);
dWord = Document('mydoc','docx');
p = Paragraph('Hello again, World');
append(dWord,p);
11-105
11 Functions – Alphabetical List
close(dWord);
rptview('mydoc','docx');
Input Arguments
reportPath — Report file path including file extension
string
Path to a specific report file, including the file extension, specified as a string.
The report file name extension determines the viewer in which the report displays.
The full path of a report, without the file extension, specified as a string. You can specify
a string with the full path. Alternatively, you can use the value of the OutputPath
property of the mlreportgen.dom.Document object that you create for the report.
• 'html'
• 'docx'
• 'pdf'
See Also
mlreportgen.dom.Document
11-106
setedit
setedit
Start Report Explorer
Syntax
setedit (filename)
Description
setedit (filename) opens the Report Explorer and loads the report setup file named
filename. If a file with the specified name does not exist, Report Explorer opens an
empty report setup file with that name.
More About
• “Report Explorer”
See Also
rptlist | report | rptconvert
11-107
11 Functions – Alphabetical List
unzipTemplate
Unzip zipped DOM template
Syntax
unzipTemplate(zippedTemplatePath)
unzipTemplate(zippedTemplatePath,unzippedTemplatePath)
Description
unzipTemplate(zippedTemplatePath) unzips the DOM template zip file specified by
zippedTemplatePath into a subfolder of the folder that contains the zipped template.
Examples
Unzip DOM Template into Subfolder of Zipped Template Folder
This example assumes that there is a zipped DOM template called myTemplate in the
current folder and a folder called H:\report_templates.
unzipTemplate('myTemplate.htmtx','H:\report_templates\myTemplate');
Input Arguments
zippedTemplatePath — Path of the zipped DOM template
string
11-108
unzipTemplate
If you do not include a file extension in the path, the function assumes the extension is
.htmtx.
The template is unzipped into the folder that you specify in unzippedTemplate path.
More About
• “Report Packages”
See Also
mlreportgen.dom.Document.createTemplate | zipTemplate
11-109
11 Functions – Alphabetical List
zipTemplate
Package DOM HTML template in zip file
Syntax
zipTemplate(unzippedTemplateFolder)
zipTemplate(zippedTemplate,unzippedTemplateFolder)
zipTemplate(zippedTemplate,unzippedTemplateFolder,mainDocument)
zipTemplate(zippedTemplate,unzippedTemplateFolder,mainDocument,
partTemplates)
Description
zipTemplate(unzippedTemplateFolder) zips (compresses and puts in a zip file) the
unzipped DOM template in unzippedTemplateFolder. The resulting zipped template
file name is the name specified in unzippedTemplateFolder, plus the file extension
htmtx. The zipTemplate function zips all of the files in the unzipped template folder,
including files in subfolders. The zipped template folder structure duplicates the folder
structure of the unzipped template.
Use this syntax if you created the unzipped template by unzipping a template created in
any of these ways:
• Used mlreportgen.dom.Document.createTemplate
• Copied the template from a default DOM template
• Created the template without using the DOM API or DOM templates and the zipped
file complies with the conditions listed in “Tips”.
zipTemplate(zippedTemplate,unzippedTemplateFolder,mainDocument)
zips the unzipped DOM template into the file specified by zippedTemplate. Use
the mainDocument argument to specify the name of main document in the unzipped
template if the main document name in the unzipped template is not report.html or
11-110
zipTemplate
root.html and your document part template library file, if it exists, is in a file called
docpart_templates.html.
zipTemplate(zippedTemplate,unzippedTemplateFolder,mainDocument,
partTemplates) zips the unzipped DOM template into the file specified by
zippedTemplate. Use this syntax when the unzipped template includes a document
part template library file whose file name is not docpart_templates.html. You must
specify mainDocument as the third argument, even if the main document file is called
report.html or root.html.
Examples
Zip to a File Whose Base Name is the Unzipped Template Folder
Zip When Main Document and Part Template File Use Custom Names
Zip a template whose main part is mainpart.html and whose part template library file
is documentpart_templates.html.
zipTemplate('myTemplate.htmx','myTemplate',...
'mainpart.html','documentpart_templates.html');
Input Arguments
unzippedTemplateFolder — Path to folder containing unzipped template
string
11-111
11 Functions – Alphabetical List
Full path for the zipped DOM template, including the file extension .htmtx, specified as
a string.
Main document file name, including the file extension, specified as a string.
Document part library file name, including the file extension, specified as a string.
More About
Tips
zipTemplate(unzippedTemplateFolder)
zipTemplate(zippedTemplate,unzippedTemplateFolder)
You can also use either of those two syntaxes if the unzipped template was created
without using the DOM interface and the template complies with the following
requirements.
If the unzipped template main document file is not named either report.html or
root.html, use the mainDocument input argument.
If the unzipped template includes a document part template library file with a name
other than docpart_templates.html, use the partTemplates input argument.
11-112
zipTemplate
If the unzipped template stores images in a folder other than one named images in
the root folder of the template, include a text file called _imgprefix in the folder
that contains images for the unzipped template. In the _imgprefix file, you can
include a prefix for the DOM interface to use to generate names images appended to
documents. For example, if the _imgprefix file contains the prefix graphic, the
generated image names are graphic1.png, graphic2.png, and so on. If you leave
the _imgprefix file empty, then the generated images use the prefix image.
• “Report Packages”
See Also
mlreportgen.dom.Document.createTemplate | unzipTemplate
11-113
12
mlreportgen.dom.AllowBreakAcrossPages class
Package: mlreportgen.dom
Description
Specifies whether to allow row to straddle page break. This format applies only to Word
documents.
Construction
breakAcrossPagesObj = AllowBreakAcrossPages() allows a row to flow onto the
next page when it cannot fit entirely on the current page.
Input Arguments
tf — Allow row to flow onto next page
true (default) | logical value
A setting of false (or 0) forces a row to start on the next page when it cannot fit on the
current page. A setting of true (or 1) allows a row to flow onto the next page when it
cannot fit entirely on the current page.
Data Types: logical
Output Arguments
breakAcrossPagesObj — Control table row page break
mlreportgen.dom.AllowBreakAcrossPages object
12-2
mlreportgen.dom.AllowBreakAcrossPages class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• 0— forces a row to start on the next page when it cannot fit on the current page
• 1— allows a row to flow onto the next page when it cannot fit entirely on the current
page
See Also
mlreportgen.dom.RepeatAsHeaderRow | mlreportgen.dom.TableRow
More About
• “Report Formatting Approaches”
12-3
12 Classes – Alphabetical List
mlreportgen.dom.AutoNumber class
Package: mlreportgen.dom
Description
Automatically generated number for a DOM document element object.
Construction
autoObj = AutoNumber() creates an automatically generated number without a
specified number stream.
Input Arguments
stream — Numbering stream for generating the number
string
If the specified stream does not exist, the DOM interface creates an Arabic
number stream having the specified name with an initial value of 0. To use a
stream with other properties, such as Roman numerals, create a stream using
mlreportgen.dom.Document.createAutoNumberStream.
12-4
mlreportgen.dom.AutoNumber class
Name of number style defined in the template, specified as a string. The style specified
by styleName must be defined in the template used to create the document to which the
number is appended.
Output Arguments
autoObj — Automatically created number object
mlreportgen.dom.AutoNumber object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
To make text bold, set this property to true or 1. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the weight of
the number is determined by that style. Setting the Bold property adds a corresponding
mlreportGen.dom.Bold format object to the Style property of this document element.
Removing the Bold property setting removes the object.
Data Types: logical
12-5
12 Classes – Alphabetical List
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
HTML or Microsoft Word must support the custom attributes of this document element.
To specify substitutions for this font, do not set this property. Instead create and add a
mlreportgen.dom.FontFamily object to the Style property of this document element.
If you need to specify substitutions for this font, do not set this property. Instead
create and add a mlreportgen.dom.FontFamily object to the Style property of this
document element.
String having the format valueUnits, where Units is an abbreviation for the units in
which the font size is expressed. Use one of these abbreviations for the units for the font
size.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
12-6
mlreportgen.dom.AutoNumber class
• pt — points
• px — pixel
To use italics for a number, set this property to true. If this property is empty and
the StyleName property for this document element specifies a style sheet style, the
slant of the number is determined by that style. Setting the Italic property adds a
corresponding mlreportGen.dom.Italic format object to the Style property of this
document element. Removing the Italic property setting removes the object.
Data Types: logical
The default for this property is []. You can set it to one of these values:
The formats specified by this property override corresponding formats defined by the
stylesheet style specified by the StyleName property of this element. Formats that do
not apply to this element are ignored.
12-7
12 Classes – Alphabetical List
The style specified by styleName must be defined in the template used to create the
document element to which this number is appended.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-8
mlreportgen.dom.AutoNumber class
If this property is empty and StyleName property of this document element specifies a
style sheet style, the type of underline is determined by that style.
To specify the color as well as the type of the underline, do not set the Underline
property. Instead, set the Style property of this document element to include an
mlreportgen.dom.Underline format object that specifies the desired underline type
and color.
To specify how to handle white space, use one of the following strings.
12-9
12 Classes – Alphabetical List
If you want to view HTML output in the MATLAB browser and you want to preserve
white space and wrap text only on line breaks, use the preserve setting rather than the
pre setting.
Methods
Method Purpose
append Append a custom element to this number.
Examples
Use Automatically Generated Numbers for Chapters and Tables
import mlreportgen.dom.*;
12-10
mlreportgen.dom.AutoNumber class
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Chapter ');
p.Style = {CounterInc('chapter'),CounterReset('table'),WhiteSpace('preserve')};
append(p,AutoNumber('chapter'));
append(d,p);
p = Paragraph('Table ');
append(p,AutoNumber('chapter'));
append(p,'.');
append(p,AutoNumber('table'));
p.Style = {CounterInc('table'),WhiteSpace('preserve')};
append(d,p);
p = Paragraph('Chapter ');
p.Style = {CounterInc('chapter'),CounterReset('table'),WhiteSpace('preserve')};
append(p, AutoNumber('chapter'));
append(d,p);
p = Paragraph('Table ');
append(p, AutoNumber('chapter'));
append(p,'.');
append(p,AutoNumber('table'));
p.Style = {CounterInc('table'),WhiteSpace('preserve')};
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.CounterInc | mlreportgen.dom.CounterReset
| mlreportgen.dom.Document.createAutoNumberStream |
mlreportgen.dom.Document.getAutoNumberStream
12-11
12 Classes – Alphabetical List
mlreportgen.dom.AutoNumberStream class
Package: mlreportgen.dom
Numbering stream
Description
A numbering stream generates a sequence of numbers for numbering chapters, tables,
figures, and other document objects. To create a numbering stream object, use the
mlreportgen.dom.Document.createAutoNumberStream method.
Properties
CharacterCase — Character case of generated numbers
string
12-12
mlreportgen.dom.AutoNumberStream class
The value of this property should be one less than the number that you want to be
generated first. For example, if you want the number of the first item to be numbered by
this stream to be 2, set the value of this property to 1.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.CounterInc | mlreportgen.dom.CounterReset
| mlreportgen.dom.Document.createAutoNumberStream |
mlreportgen.dom.Document.getAutoNumberStream
Related Examples
• “Automatically Number Document Content”
12-13
12 Classes – Alphabetical List
mlreportgen.dom.BackgroundColor class
Package: mlreportgen.dom
Description
Specifies the background color of a document element
Construction
backgroundColorObj = BackgroundColor() creates a white background.
Input Arguments
colorName — Name of a color to use
string
The name of a color, specified as a string. The name must be a CSS color name. See
http://www.crockford.com/wrrrld/color.html.
A string using the following RGB format: #RRGGBB. Use # as the first character and two-
digit hexidecimal numbers for each for the red, green, and blue values. For example,
'#0000ff' specifies blue.
Output Arguments
backgroundColorObj — Background color
mlreportgen.dom.BackgroundColor object
12-14
mlreportgen.dom.BackgroundColor class
Properties
HexValue — Hexadecimal color value (read-only)
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Value — CSS color name or hexadecimal RGB value for this color
string
12-15
12 Classes – Alphabetical List
Examples
Create and Apply a Background Color
Create a deep sky blue background color object and apply it to a paragraph. Instead of
specifying the CSS color name 'DeepSkyBlue', you could use the hexadecimal value
'#00bfff'.
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test', doctype);
blue = 'DeepSkyBlue';
% blue = '#00BFFF';
colorfulStyle = {Bold, Color(blue), BackgroundColor('Yellow')};
p = Paragraph('deep sky blue paragraph with yellow background');
p.Style = colorfulStyle;
append(d, p);
close(d);
rptview('test', doctype);
See Also
mlreportgen.dom.Color
More About
• “Report Formatting Approaches”
12-16
mlreportgen.dom.Bold class
mlreportgen.dom.Bold class
Package: mlreportgen.dom
Description
Specifies whether to use bold for a text object
Construction
boldObj = Bold() creates a bold object that specifies to use bold for a text object.
boldObj = Bold(value) creates a bold object that specifies to use bold for a text object
if value is true. Otherwise, creates a bold object that specifies to use regular weight text.
Input Arguments
value — Option to use bold or regular weight for text object
[] (default) | logical value
A setting of false (or 0) uses regular weight text. A setting of true (or 1) renders text in
bold.
Data Types: logical
Output Arguments
boldObj — Bold text
mlreportgen.dom.Bold object
Properties
Id — ID for document element
string
12-17
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Create Paragraph With Bold and Regular-Weight Text
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('bold text ');
p.Style = {Bold};
append(d,p);
12-18
mlreportgen.dom.Bold class
rptview('test',doctype);
See Also
mlreportgen.dom.Italic
More About
• “Report Formatting Approaches”
12-19
12 Classes – Alphabetical List
mlreportgen.dom.Border class
Package: mlreportgen.dom
Description
Specifies the border properties of an object.
Construction
borderObj = Border() creates an unspecified border.
Input Arguments
style — Default style of border segments
string
String Applies To
DOCX HTML
'dashed' X X
'dashdotstroked' X
12-20
mlreportgen.dom.Border class
String Applies To
DOCX HTML
'dashsmallgap' X
'dotted' X X
'dotdash' X
'dotdotdash' X
'double' X X
'doublewave' X
'inset' X X
'none' X X
'outset' X X
'single' X
'solid' X
'thick' X
'thickthinlargegap' X
'thickthinmediumgap' X
'thickthinsmallgap' X
'thinthicklargegap' X
'thinthickmediumgap' X
'thinthicksmallgap' X
'thinthickthinlargegap' X
'thinthickthinmediumgap' X
'thinthickthinsmallgap' X
'threedemboss' X
'threedengrave' X
'triple' X
'wave' X
12-21
12 Classes – Alphabetical List
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String specifying the width of the border. String must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixel
Output Arguments
borderObj — Table border
mlreportgen.dom.Border object
Properties
Color — Default color of border segments
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
12-22
mlreportgen.dom.Border class
For details, see the description of the style input argument for the
mlreportgen.dom.Border constructor.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String specifying the width of the border. String must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
12-23
12 Classes – Alphabetical List
• px — pixel
12-24
mlreportgen.dom.Border class
Examples
Format Table Borders
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test', doctype);
t = Table(magic(5));
t.Style = {Border('inset', 'crimson', '6pt'), Width('50%')};
t.TableEntriesInnerMargin = '6pt';
append(d, t);
close(d);
rptview('test', doctype);
See Also
mlreportgen.dom.ColSep | mlreportgen.dom.RowSep |
mlreportgen.dom.Table
12-25
12 Classes – Alphabetical List
mlreportgen.dom.BorderCollapse class
Package: mlreportgen.dom
Description
Specifies whether to collapse table borders. This applies only to HTML tables.
Construction
borderCollapseObj = BorderCollapse() creates an unspecified format. Nothing is
inserted in the generated table markup.
Input Arguments
value — Specify whether to collapse border
string
String specifying to collapse table borders ('on') or to leave table and adjacent cell
borders separate ('off').
Output Arguments
borderCollapseObj — Specify whether to collapse table borders
mlreportgen.dom.BorderCollapse object
Properties
Id — ID for document element
string
12-26
mlreportgen.dom.BorderCollapse class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String specifying to collapse table borders ('on') or to leave table and adjacent cell
borders separate ('off').
Examples
Collapse and Separate Table Borders
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
magicArray = magic(5);
p = Paragraph('Collapsed Borders');
append(d,p);
table = Table(magicArray);
table.Style = {Border('solid'),BorderCollapse('on')};
for r = 1:5
for c = 1:5
table.entry(r,c).Style = {Border('solid')};
end
end
append(d,table);
12-27
12 Classes – Alphabetical List
p = Paragraph('Separate Borders');
append(d,p);
table = Table(magicArray);
table.Style = {Border('solid'),BorderCollapse('off')};
for r = 1:5
for c = 1:5
table.entry(r,c).Style = {Border('solid')};
end
end
append(d,table);
close(d);
rptview(d.OutputPath,doctype);
See Also
mlreportgen.dom.Border | mlreportgen.dom.TableColSpec |
mlreportgen.dom.TableEntry | mlreportgen.dom.TableRow
12-28
mlreportgen.dom.CharEntity class
mlreportgen.dom.CharEntity class
Package: mlreportgen.dom
Description
Create a reference to a character entity reference.
Construction
charEntityObj = CharEntity() creates a reference to a non-breaking space ( )
entity. Appending this reference to a document causes a nonbreaking space to be
inserted.
Input Arguments
name — Specify character entity name
string
12-29
12 Classes – Alphabetical List
Output Arguments
charEntityObj — Reference to a character entity
mlreportgen.dom.CharEntity object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
To make text bold, set this property to true or 1. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the weight of
the number is determined by that style. Setting the Bold property adds a corresponding
mlreportGen.dom.Bold format object to the Style property of this document element.
Removing the Bold property setting removes the object.
Data Types: logical
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
12-30
mlreportgen.dom.CharEntity class
HTML or Microsoft Word must support the custom attributes of this document element.
To specify substitutions for this font, do not set this property. Instead create and add a
mlreportgen.dom.FontFamily object to the Style property of this document element.
If you need to specify substitutions for this font, do not set this property. Instead
create and add a mlreportgen.dom.FontFamily object to the Style property of this
document element.
String having the format valueUnits, where Units is an abbreviation for the units in
which the font size is expressed. Use one of these abbreviations for the units for the font
size.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
12-31
12 Classes – Alphabetical List
• pi — picas
• pt — points
• px — pixel
To use italics for a number, set this property to true. If this property is empty and
the StyleName property for this document element specifies a style sheet style, the
slant of the number is determined by that style. Setting the Italic property adds a
corresponding mlreportGen.dom.Italic format object to the Style property of this
document element. Removing the Italic property setting removes the object.
Data Types: logical
The default for this property is []. You can set it to one of these values:
12-32
mlreportgen.dom.CharEntity class
The style specified by styleName must be defined in the template used to create the
document element to which this number is appended.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-33
12 Classes – Alphabetical List
If this property is empty and StyleName property of this document element specifies a
style sheet style, the type of underline is determined by that style.
To specify the color as well as the type of the underline, do not set the Underline
property. Instead, set the Style property of this document element to include an
mlreportgen.dom.Underline format object that specifies the desired underline type
and color.
12-34
mlreportgen.dom.CharEntity class
To specify how to handle white space, use one of the following strings.
If you want to view HTML output in the MATLAB browser and you want to preserve
white space and wrap text only on line breaks, use the preserve setting rather than the
pre setting.
Methods
Method Purpose
append Append a custom element to this character
entity.
12-35
12 Classes – Alphabetical List
Method Purpose
Use CharEntity.append in a similar way
to how you use ExternalLink.append.
clone Clone this character entity.
Examples
Append a British Pound Sign
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph(CharEntity('pound'));
append(d,p);
append(p,'3');
close(d);
rptview('test',doctype);
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Some text');
append(d,p);
ce = CharEntity('nbsp',5);
append(p,ce);
append(p,'more text after five blank spaces');
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.Paragraph | mlreportgen.dom.Text
12-36
mlreportgen.dom.CharEntity class
More About
• “Report Formatting Approaches”
12-37
12 Classes – Alphabetical List
mlreportgen.dom.Color class
Package: mlreportgen.dom
Description
Specifies the color of a document element.
Construction
colorObj = Color() creates a black color object.
colorObj = Color(colorName) creates a color object based on the specified CSS color
name.
colorObj = Color(rgbValue) creates a color object using the hexidecimal RGB color
value.
Input Arguments
colorName — Name of color
string
Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
A string using the following RGB format: #RRGGBB. Use # as the first character and two-
digit hexidecimal numbers for each for the red, green, and blue values. For example,
'#0000ff' specifies blue.
Output Arguments
colorObj — Color for document element
mlreportgen.dom.Color object
12-38
mlreportgen.dom.Color class
Properties
HexValue — hexidecimal color value (read-only)
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Value — CSS color name or hexidecimal RGB value for this color
string
Examples
Create and Apply a Color Object
Create a blue color object and apply it to a paragraph. Instead of specifying the CSS color
name 'blue', you could use the hexadecimal value '#0000ff'.
12-39
12 Classes – Alphabetical List
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
colorfulStyle = {Bold,Color('blue')};
p = Paragraph('deep sky blue paragraph');
p.Style = colorfulStyle;
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.BackgroundColor
More About
• “Report Formatting Approaches”
12-40
mlreportgen.dom.ColSep class
mlreportgen.dom.ColSep class
Package: mlreportgen.dom
Description
Draw lines between table columns.
Construction
colSepObj = ColSep() creates unspecified column separators.
Input Arguments
style — Style of column separator in table
string
String Applies To
DOCX HTML
'dashed' X X
'dashdotstroked' X
12-41
12 Classes – Alphabetical List
String Applies To
DOCX HTML
'dashsmallgap' X
'dotted' X X
'dotdash' X
'dotdotdash' X
'double' X X
'doublewave' X
'inset' X X
'none' X X
'outset' X X
'single' X
'solid' X
'thick' X
'thickthinlargegap' X
'thickthinmediumgap' X
'thickthinsmallgap' X
'thinthicklargegap' X
'thinthickmediumgap' X
'thinthicksmallgap' X
'thinthickthinlargegap' X
'thinthickthinmediumgap' X
'thinthickthinsmallgap' X
'threedemboss' X
'threedengrave' X
'triple' X
'wave' X
12-42
mlreportgen.dom.ColSep class
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String specifying the color of the table column separator. String must have the format
valueUnits where Units is an abbreviation for the units in which the width size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixel
Output Arguments
colSepObj — Column separator definition
mlreportgen.dom.ColSpec object
Properties
Color — Separator color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
12-43
12 Classes – Alphabetical List
Array of format objects (such as Bold objects) that specify the format for the separator.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
The string has the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
12-44
mlreportgen.dom.ColSep class
• mm — millimeters
• pi — picas
• pt — points
• px — pixel
Examples
Specify Table Column Formatting
grps(1) = TableColSpecGroup;
grps(1).Span = 1;
grps(1).Style = {Color('red'),Width('1in')};
table = Table(magic(5));
table.ColSpecGroups = grps;
append(doc,table);
close(doc);
rptview('myTableColReport','docx');
See Also
mlreportgen.dom.RowSep
12-45
12 Classes – Alphabetical List
mlreportgen.dom.Container class
Package: mlreportgen.dom
Description
Creates a container element. Use the mlreportgen.dom.Container.append method
to append document elements to the container. Use an mlreportgen.dom.Container
object in an HTML or Microsoft Word report to apply formats to all of the children of the
container.
In HTML output, a Container object generates an HTML element of the type specified
by its HTMLTag property and containing HTML elements corresponding to its DOM
contents. For example, a Container object with the HTMLTag property div and that
contains the text Hello World generates this markup:
<div><p><span>Hello World</span></p></div>
The generated HTML container element has the class and style properties specified
by the Container object StyleName and Style properties, respectively. The rules of
HTML CSS format inheritance assure that the generated children of the Container
object inherit the formats specified by the Container object Style and StyleName
properties. For example, if the Container object specifies red as its text color and none
of its text children specify a color, the text children are colored red.
For Microsoft Word report output, a Container object simulates container format
inheritance, applying the formats specified by the Container object Style attribute
to each child, unless overridden by the child, and then appending the child to the
Word output. The Word output ignores the HTMLTag and StyleName properties of the
Container object.
• Use a container object to apply format inheritance to a set of objects and to create
HTML container elements not otherwise supported by the DOM, such as div, section,
and article.
12-46
mlreportgen.dom.Container class
• Use a group object to append the same content in multiple places in a document
without cloning the group.
Construction
containerObj = Container() creates a container with an HTML tag name div.
Input Arguments
HTMLtag — HTML container tag name
string
HTML container tag name, specified as a string. The name must be an HTML element,
such as 'div', 'section', or 'article'.
Output Arguments
containerObj — Container of document objects
mlreportgen.dom.Container object
Properties
Id — ID for document element
string
12-47
12 Classes – Alphabetical List
This read-only property lists child elements that the container contains.
HTML container tag name, specified as a string. The name must be an HTML element,
such as 'div', 'section', or 'article'.
Style name, specified as a string. The style name is the name of a style specified in the
stylesheet of the document or document part to which this element is appended. The
specified style defines the appearance of this element in the output document where not
overridden by the formats specified by the Style property of this element.
12-48
mlreportgen.dom.Container class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Examples
Create Container for Word Report Formatting
Create a container object. Word output ignores the HTML container element tag (in this
example, the div tag).
import mlreportgen.dom.*;
rpt = Document('MyReport','docx');
c = Container();
c.Style = {Color('red')};
Append content to the container and append the container to the report.
append(c,Paragraph('Hello'));
append(c,Table(magic(5)));
append(rpt,c);
close(rpt);
rptview(rpt.OutputPath);
12-49
12 Classes – Alphabetical List
See Also
mlreportgen.dom.Group
Introduced in R2015a
12-50
mlreportgen.dom.CoreProperties class
mlreportgen.dom.CoreProperties class
Package: mlreportgen.dom
Description
OPC core properties of a document or template.
Construction
corePropsObj = CoreProperties() creates an empty core properties object. Core
properties are metadata stored in a document OPC package that describe various
properties of the document. Windows Explorer displays some of the core properties when
you select a document.
Output Arguments
corePropsObj — OPC core properties
mlreportgen.dom.CoreProperties object
Properties
Category — Category of document
string
12-51
12 Classes – Alphabetical List
12-52
mlreportgen.dom.CoreProperties class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.Document.getCoreProperties |
mlreportgen.dom.Document.setCoreProperties
More About
• “Report Packages”
12-53
12 Classes – Alphabetical List
mlreportgen.dom.CounterInc class
Package: mlreportgen.dom
Description
Creates a numbering stream counter incrementer.
Construction
counterIncObj = CounterInc() creates an empty counter incrementer.
Input Arguments
streamName — Numbering stream name
string
Output Arguments
counterIncObj — Numbering stream counter incrementer
mlreportgen.dom.CounterInc object
Properties
Id — ID for document element
string
12-54
mlreportgen.dom.CounterInc class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Increment Chapter Numbering
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Chapter ');
p.Style = {CounterInc('chapter'),WhiteSpace('preserve')};
append(p,AutoNumber('chapter'));
append(d,p);
p = Paragraph('Chapter ');
p.Style = {CounterInc('chapter'), WhiteSpace('preserve')};
append(p,AutoNumber('chapter'));
append(d,p);
close(d);
rptview('test',doctype);
12-55
12 Classes – Alphabetical List
See Also
mlreportgen.dom.AutoNumber | mlreportgen.dom.AutoNumberStream |
mlreportgen.dom.CounterReset
12-56
mlreportgen.dom.CounterReset class
mlreportgen.dom.CounterReset class
Package: mlreportgen.dom
Description
Reset a numbering stream counter.
Construction
counterResetObj = CounterReset() creates an empty counter reset object.
Input Arguments
streamName — Numbering stream name
string
Output Arguments
reset — Numbering stream counter reset
mlreportgen.dom.CounterReset object
Properties
Id — ID for document element
string
12-57
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Reset Numbering for Chapters and Tables
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Chapter ');
p.Style = {CounterInc('chapter'),CounterReset('table'),...
WhiteSpace('preserve') };
append(p,AutoNumber('chapter'));
append(d,p);
p = Paragraph('Table ');
append(p,AutoNumber('chapter'));
append(p,'.');
append(p,AutoNumber('table'));
p.Style = {CounterInc('table'),WhiteSpace('preserve') };
append(d,p);
p = Paragraph('Chapter ');
12-58
mlreportgen.dom.CounterReset class
p.Style = {CounterInc('chapter'),CounterReset('table'),...
WhiteSpace('preserve')};
append(p,AutoNumber('chapter'));
append(d,p);
p = Paragraph('Table ');
append(p,AutoNumber('chapter'));
append(p,'.');
append(p, AutoNumber('table'));
p.Style = {CounterInc('table'),WhiteSpace('preserve')};
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.AutoNumber | mlreportgen.dom.AutoNumberStream |
mlreportgen.dom.CounterInc
12-59
12 Classes – Alphabetical List
mlreportgen.dom.CustomAttribute class
Package: mlreportgen.dom
Description
Custom element attribute.
Construction
customAttributeObj = CustomAttribute() creates an empty custom attribute.
Input Arguments
name — Attribute name
string
Output Arguments
customAttributeObj — Custom attribute
mlreportgen.dom.CustomAttribute object
12-60
mlreportgen.dom.CustomAttribute class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Create Custom Attributes for a List
This example shows how to define custom attributes and append them to an unordered
list.
import mlreportgen.dom.*;
d = Document('test');
ul = UnorderedList();
12-61
12 Classes – Alphabetical List
li = ListItem('Owl');
li.CustomAttributes = {CustomAttribute('data-animal-type','bird')};
append(ul,li);
li = ListItem('Salmon');
li.CustomAttributes = {CustomAttribute('data-animal-type','fish')};
append(ul,li);
li = ListItem('Tarantula');
li.CustomAttributes = {CustomAttribute('data-animal-type','spider')};
append(ul,li);
append(d,ul);
close(d);
rptview('test','html');
See Also
mlreportgen.dom.CustomElement | mlreportgen.dom.CustomText
12-62
mlreportgen.dom.CustomElement class
mlreportgen.dom.CustomElement class
Package: mlreportgen.dom
Description
Use a custom element to extend the DOM API. You can create a custom HTML or
Microsoft Word element that provides functionality not yet included in the DOM API.
Construction
customElementObj = CustomElement() creates an empty element.
Input Arguments
name — Custom element name
string
Name of an element supported by the type of document to which this custom element is
appended. For example, specify 'div' for a custom HTML div element or 'w:p' for a
custom Word paragraph element.
Output Arguments
customElementObj — Custom element
mlreportgen.dom.CustomElement object
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
12-63
12 Classes – Alphabetical List
HTML or Microsoft Word must support the custom attributes of this document element.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append a custom element to the document
element
12-64
mlreportgen.dom.CustomElement class
Method Purpose
clone Copy custom element.
Examples
Create a Check Box Custom Element
This example shows how to add a custom element that provides a check box in an HTML
report.
input1 = CustomElement('input');
input1.CustomAttributes = {
CustomAttribute('type', 'checkbox'), ...
CustomAttribute('name', 'vehicle'), ...
CustomAttribute('value', 'Bike'), ...
};
append(input1, Text('I have a bike'));
Append the custom element to an ordered list and display the report.
ol = OrderedList({input1});
append(d,ol);
close(d);
rptview('test','html');
See Also
mlreportgen.dom.CustomAttribute | mlreportgen.dom.CustomText
12-65
12 Classes – Alphabetical List
mlreportgen.dom.CustomText class
Package: mlreportgen.dom
Description
Plain text string to append to a custom element.
Construction
customTextObj = CustomText() creates an empty CustomText object.
Input Arguments
text — Text string to append to custom element
string
Output Arguments
customTextObj — Text string to append to custom element
mlreportgen.dom.CustomText object
Properties
Id — ID for document element
string
12-66
mlreportgen.dom.CustomText class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Create Custom Text for a Script
import mlreportgen.dom.*;
d = Document('test');
script = CustomElement('script');
append(script,CustomText('document.write("Hello World!")'));
append(d,script);
close(d);
rptview('test','html');
See Also
mlreportgen.dom.CustomAttribute | mlreportgen.dom.CustomElement
12-67
12 Classes – Alphabetical List
mlreportgen.dom.DebugMessage class
Package: mlreportgen.dom
Debugging message
Description
Creates debugging message text originating from the specified source object.
Construction
debugMsgObj = DebugMessage(text,sourceObject) creates a debugging message
with the specified text, originating from the specified source object.
Input Arguments
text — Message text
string
Output Arguments
debugMsgObj — Debugging message
mlreportgen.dom.DebugMessage object
Properties
Id — ID for document element
string
12-68
mlreportgen.dom.DebugMessage class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Use DebugMessage methods similar to how you use ProgressMessage methods.
Method Purpose
formatAsHTML Format message as HTML.
formatAsText Format message as text.
passesFilter Determine whether message passes filter.
Examples
Create a Debug Message
12-69
12 Classes – Alphabetical List
import mlreportgen.dom.*;
d = Document('test','html');
delete(l);
See Also
mlreportgen.dom.MessageDispatcher.dispatch
12-70
mlreportgen.dom.Document class
mlreportgen.dom.Document class
Package: mlreportgen.dom
Description
Create mlreportgen.dom.Document object that defines:
To generate a PDF report, create a Word report and use the rptview function with the
'pdf' argument to convert the Word report to PDF.
Construction
documentObj = Document() creates an HTML document named Untitled.htmx in
the current directory, using the default HTML template.
Input Arguments
outputPath — Path for the output file generated by the document
string
12-71
12 Classes – Alphabetical List
Full path of output file or folder for this document. If you do not specify a file extension,
the extension is based on the document type (for example, .docx for Microsoft Word).
When the document is open, you cannot set this property.
What you specify for the path depends on the value of the PackageType property.
If you specify a template using the templatePath input argument, the template must be
consistent with the type argument. You must specify a Word template (.dotx) for Word
output, an HTML template package (.htmtx) for HTML output, and a single-file HTML
template (.html) for html-file output.
To generate a PDF report, create a Word report and use the rptview function with the
'pdf' argument to convert the Word report to PDF.
If you do not want to use the default HTML or Word template, specify a template.
Full path of output file or folder for the template. If you do not specify a file extension,
the extension is based on the document type (for example, .docx for Word). Before
setting this property, close the document.
Data Types: char
12-72
mlreportgen.dom.Document class
Output Arguments
documentObj — Report definition document
mlreportgen.dom.Document object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
This read-only property is the hole ID of the current hole in this document.
This read-only property is the type (inline or block) of the current template hole.
• An inline hole is for document elements that a paragraph element can contain: Text,
Image, LinkTarget, ExternalLink, InternalLink, CharEntity, AutoNumber.
• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList,
DocumentPart, and Group.
Set this property to true to overwrite an existing output file of the same name for a
report from this document. If this property is false, or if the existing output file is read-
12-73
12 Classes – Alphabetical List
only, then generating an output file using the same path as an existing output file causes
an error.
Data Types: logical
You cannot set this property once the document has been opened.
Path of this document's output file. If you do not specify the file extension, the DOM
interface adds an extension based on the output type of the document.
For unzipped output packaging, the path specifies the folder for the output files. The
default is the current folder.
String specifying how to package the output files generated from this document. Use one
of these values:
• zipped (default)
• unzipped
• both
For zipped packaging, the document output is a zip file located at the location specified
by the OutputPath property. The zip file has the extension that matches the document
type: docx (for Word output) or htmx (for HTML output). For example, if the document
type is docx and OutputPath is s:\docs\MyDoc, the output is packaged in a zip file
named s:\docs\MyDoc.docx.
12-74
mlreportgen.dom.Document class
For unzipped packaging, the document output is stored in a folder having the root file
name of the OutputPath property. For example, if the OutputPath is s:\docs\MyDoc,
the output folder is s:\docs\MyDoc.
If you set PackageType to both, generating the report produces zipped and unzipped
output.
By default, document elements are stored in memory until the document is closed. Set
this property to true to write document elements to disk as the elements are appended
to the document.
Data Types: logical
String that identifies this document. The tag has the form CLASS:ID, where CLASS is the
document class and ID is the value of the Id property of the object.
An example of a reason for specifying your own tag value is to make it easier to identify
where an issue occurred during document generation.
Data Types: char
The full path to the HTML or Word template to use for this document element.
For HTML documents, this property specifies the text for the title bar of the browser.
Word documents ignore this property.
12-75
12 Classes – Alphabetical List
• 'html'— HTML output HTML output as a zipped or unzipped folder containing the
HTML document text, image, style sheet, and JavaScript files
• 'docx'— Word output
• 'html-file'— HTML output consisting of a single file that contains the text, style
sheets, JavaScript, and images for the report
If you specify a template using the TemplatePath property, the template must be
consistent with the type argument. You must specify a Word template (.dotx) for docx
output, an HTML template package (.htmtx) for HTML output, and a single-file HTML
template (.html) for html-file output.
To generate a PDF report, create a Word report and use the rptview function with the
'pdf' argument to convert the Word report to PDF.
Methods
Method Purpose
addHTML Append HTML string to document
addHTMLFile Append HTML file contents to document
append Append document element to the
document.
close Close this document.
createAutoNumberStream Create automatically generated numbering
stream.
createTemplate Create document template.
fill Fill document hole.
getAutoNumberStream Get the automated numbering stream.
getCoreProperties Get core properties of document.
getMainPartPath Get relative path of main part of output
document.
12-76
mlreportgen.dom.Document class
Method Purpose
getOPCMainPart Get full path of main part of output
document.
moveToNextHole Move to next template hole.
open Open this document.
package Append file to OPC package of document.
setCoreProperties Set core properties of document element.
Examples
Create a Word Document
import mlreportgen.dom.*;
d = Document('mydoc','docx');
p = Paragraph('Hello World');
append(d,p);
close(d);
rptview('mydoc_1.htmx');
Create an HTML document as a single HTML file that includes the images of
the document. The example assumes that there is a MyImage.jpg image and a
myHTMLTemplate.html HTML template file.
import mlreportgen.dom.*;
d = Document('mydoc','html-file','myHTMLTemplate');
open(d);
append(d,'Hello world');
append(d,Image('C:/images/LocalSystem/MyImage.jpg'));
12-77
12 Classes – Alphabetical List
close(d);
rptview(d.OutputPath);
See Also
mlreportgen.dom.DocumentPart
12-78
mlreportgen.dom.DocumentPart class
mlreportgen.dom.DocumentPart class
Package: mlreportgen.dom
Document part
Description
This class defines a form that can be filled out and appended to a document or another
document part of the same output type.
Construction
documentPartObj = DocumentPart() creates an HTML document part using the
default HTML template.
documentPartObj = DocumentPart(type,templatePath,
embeddedTemplateName) creates a document part of the specified type based on the
embedded template stored in the specified master template.
documentPartObj = DocumentPart(templateSrc,embeddeTemplateName)
creates a document part with the output type of the template used by the specified
master template source. The template source is a document or document part that
contains the embedded template.
Input Arguments
type — Type of output
'html' (default) | 'docx' | 'html-file'
12-79
12 Classes – Alphabetical List
If you specify a template using the templatePath input argument, the value for type
must be consistent with that type of template.
To generate a PDF report, create a Word report and use the rptview function with the
'pdf' argument to convert the Word report to PDF.
You cannot set this property once the document has been opened.
If you do not want to use the default HTML or Word template, specify a template.
Full path of output file or folder for the template. If you do not specify a file extension,
the extension is based on the document type (for example, .docx for Word).
Output Arguments
documentPartObj — Document part
mlreportgen.dom.DocumentPart object
12-80
mlreportgen.dom.DocumentPart class
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
This read-only property is the hole ID of the current hole in this document.
This read-only property is the type (inline or block) of the current template hole.
• An inline hole is for document elements that a paragraph element can contain: Text,
Image, LinkTarget, ExternalLink, InternalLink, CharEntity, AutoNumber.
• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList,
DocumentPart, and Group.
12-81
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
The full path to the HTML or Word template to use for this document element.
• html
• docx
If you specify a template using the TemplatePath property, the value for Type must be
consistent with that type of template.
To generate a PDF report, create a Word report and use the rptview function with the
'pdf' argument to convert the Word report to PDF.
Methods
Use DocumentPart methods like you use the corresponding Document methods.
Method Purpose
addHTML Append HTML string to document
Use DocumentPart.addHTMLFile
in a similar way to how you use
Document.addHTMLFile.
12-82
mlreportgen.dom.DocumentPart class
Method Purpose
append Append document element to the document
part.
close Close this document part.
createTemplate Create document part template.
fill Fill document hole.
getCoreProperties Get core properties of document part.
getOPCMainPart Get full path of main part of output
document.
moveToNextHole Move to next template hole.
open Open this document part.
setCoreProperties Set core properties of document part.
See Also
mlreportgen.dom.Document | mlreportgen.dom.DOCXSection |
mlreportgen.dom.DOCXSubDoc
Related Examples
• “Use Subforms in a Report”
More About
• “Form-Based Reporting”
12-83
12 Classes – Alphabetical List
mlreportgen.dom.DOCXPageFooter class
Package: mlreportgen.dom
Description
Add a footer to the first page of a section or to odd pages, even pages, or both.
Construction
docxPageFooterObj = DOCXPageFooter() creates an empty page footer based on the
default Word template.
docxPageFooterObj =
DOCXPageFooter(pageType,templatePath,embeddedTemplateName) creates
an empty page footer for the specified type of page, based on the specified template
embedded in the specified master template.
docxPageFooterObj =
DOCXPageFooter(pageType,templateSrc,embeddedTemplateName) creates
an empty page footer for the specified type of page, based on the specified embedded
template in the specified master template of the specified document or document part
(templateSrc).
Input Arguments
pageType — Type of pages on which footer appears
[] (default) | string
• default— footer appears on odd pages in a section and the first page, if there are no
page footers defined with pageType set to first
12-84
mlreportgen.dom.DOCXPageFooter class
For example, to have a footer appear on the first page and on even pages, define two
separate footers, one with pageType set to first and the other with pageType set to
even.
To use a template other than the default Word template, specify a Word footer template.
Output Arguments
docxPageFooterObj — Page footer for Word document
mlreportgen.dom.DOCXPageFooter object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
12-85
12 Classes – Alphabetical List
This read-only property is the hole ID of the current hole in this document.
This read-only property is the type (inline or block) of the current template hole.
• An inline hole is for document elements that a paragraph element can contain: Text,
Image, LinkTarget, ExternalLink, InternalLink, CharEntity, AutoNumber.
• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList,
DocumentPart, and Group.
• default— appears on odd pages in a section and the first page, if there are no page
footers defined with pageType set to first
• first— appears only on the first page of a section
• even— appears even paged in a section
To have a footer appear on the first page and on even pages, define two separate footers,
one with pageType set to first and the other with pageType set to even.
12-86
mlreportgen.dom.DOCXPageFooter class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Use DocumentPageFooter methods like you use the corresponding Document methods.
Method Purpose
append Append one of these DOM objects to the
footer:
• CustomElement
• DOCXSection
• FormalTable
• Group
• ExternalLink
• Image
• InternalLink
• OrderedList
• Paragraph
• RawText
• Table
12-87
12 Classes – Alphabetical List
Method Purpose
• Text
• UnorderedList
close Close footer.
fill Fill template hole.
moveToNextHole Move to next template hole.
open Open footer.
See Also
mlreportgen.dom.DOCXPageHeader | mlreportgen.dom.DOCXSection
Related Examples
• “Create Page Footers and Headers”
12-88
mlreportgen.dom.DOCXPageHeader class
mlreportgen.dom.DOCXPageHeader class
Package: mlreportgen.dom
Description
Add a header to the first page of a section or to odd pages, even pages, or both.
Construction
docxPageHeaderObj = DOCXPageHeader() creates an empty page header based on
the default Word template.
docxPageHeaderObj =
DOCXPageHeader(pageType,templatePath,embeddedTemplateName) creates
an empty page header for the specified type of page, based on the specified embedded
template in the specified master template.
docxPageHeaderObj =
DOCXPageHeader(pageType,templateSrc,embeddedTemplateName) creates
an empty page header for the specified type of page, based on the specified embedded
template in the template used by the specified document or document part (templateSrc).
Input Arguments
pageType — Type of pages on which header appears
[] (default) | string
• default— header appears on odd pages in a section and the first page, if there are
no page headers defined with pageType set to first
• first— header appears only on the first page of a section
• even— header appears even paged in a section
12-89
12 Classes – Alphabetical List
For example, to have a header appear on the first page and on even pages, define two
separate headers, one with pageType set to first and the other with pageType set to
even.
To use a template other than the default Word template, specify a Word header template.
Output Arguments
docxPageHeaderObj — Page header for Word document
mlreportgen.dom.DOCXPageHeader object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
This read-only property is the hole ID of the current hole in this document.
12-90
mlreportgen.dom.DOCXPageHeader class
This read-only property is the type (inline or block) of the current template hole.
• An inline hole is for document elements that a paragraph element can contain: Text,
Image, LinkTarget, ExternalLink, InternalLink, CharEntity, AutoNumber.
• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList,
DocumentPart, and Group.
• default— header appears on odd pages in a section and the first page, if there are
no page headers defined with pageType set to first
• first— header appears only on the first page of a section
• even— header appears on even pages in a section
For example, to have a header appear on the first page and on even pages, define two
separate headers, one with pageType set to first and the other with pageType set to
even.
12-91
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Use DocumentPageHeader methods like you use the corresponding Document methods.
Method Purpose
append Append one of these DOM objects to the
header:
• CustomElement
• DOCXSection
• FormalTable
• Group
• ExternalLink
• Image
• InternalLink
• OrderedList
• Paragraph
• RawText
• Table
• Text
• UnorderedList
12-92
mlreportgen.dom.DOCXPageHeader class
Method Purpose
close Close header.
fill Fill template hole.
moveToNextHole Move to next template hole.
open Open header.
See Also
mlreportgen.dom.DOCXPageFooter | mlreportgen.dom.DOCXSection
Related Examples
• “Create Page Footers and Headers”
12-93
12 Classes – Alphabetical List
mlreportgen.dom.DOCXPageMargins class
Package: mlreportgen.dom
Description
Specifies the size of the page margins of a section of a Microsoft Word document.
Construction
docxPageMarginsObj = DOCXPageMargins() specifies default page margins, which
are one inch for the top, bottom, left, and right margins, and one-half inch for the gutter,
header, and footer margins.
Output Arguments
docxPageMarginsObj — Page margins
DOCXPageMargins object
Properties
Bottom — Bottom margin size
string
String specifying the width of the bottom margin. The string must have the format
valueUnits where Units is an abbreviation for the units in which the width size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
12-94
mlreportgen.dom.DOCXPageMargins class
• pi — picas
• pt — points
• px — pixels
Specify the size using the same format used for the Bottom property.
Specify the size using the same format used for the Bottom property.
Specify the size using the same format used for the Bottom property.
Specify the size using the same format used for the Bottom property.
Specify the size using the same format used for the Bottom property.
12-95
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Specify the size using the same format used for the Bottom property.
Examples
Reset Default Margins
s = d.CurrentDOCXSection;
s.PageMargins.Left = '.5in';
s.PageMargins.Right = '.5in';
append(d,'Left and right margins are .5 inch');
close(d);
rptview('myreport','docx');
See Also
mlreportgen.dom.DOCXSection
More About
• “Report Formatting Approaches”
12-96
mlreportgen.dom.DOCXPageSize class
mlreportgen.dom.DOCXPageSize class
Package: mlreportgen.dom
Description
Specifies the height, width, and orientation of pages in a section of a Microsoft Word
document.
Construction
docxPageSizeObj = DOCXPageSize() creates a page size object having default values
of 8.5-by-11 inches and portrait orientation.
Input Arguments
height — Height of page
'11in' (default) | string
String specifying the height of the page. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
12-97
12 Classes – Alphabetical List
• pi — picas
• pt — points
• px — pixels
The string must have the format valueUnits, where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
• 'portrait' (default)
• 'landscape'
Specify height and width values that reflect the orientation setting. For example, if the
orientation is landscape and the document is to be printed on 8.5x11-inch paper, set
height to '8.5in' and width to '11in'.
Output Arguments
docxPageSizeObj — Page size and orientation of Word document
mlreportgen.dom.DOCXPageSize object
12-98
mlreportgen.dom.DOCXPageSize class
Properties
Height — Height of pages in Word page layout section
string
String specifying the page height. The string must have the format valueUnits where
Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
• 'portrait' (default)
• 'landscape'
Specify height and width values that reflect the orientation setting. For example, if the
orientation is landscape and the document is to be printed on 8.5x11-inch paper, set
height to '8.5in' and width to '11in'.
12-99
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
The string must have the format valueUnits, where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Examples
Set Page Orientation and Size
Change the page orientation and size specified by the default DOM template.
import mlreportgen.dom.*;
d = Document('myreport','docx');
open(d);
s = d.CurrentDOCXSection;
s.PageSize.Orientation ='landscape';
s.PageSize.Height = '8.5in';
s.PageSize.Width = '11in';
append(d,'This document has landscape pages');
close(d);
12-100
mlreportgen.dom.DOCXPageSize class
rptview('myreport','docx');
See Also
mlreportgen.dom.DOCXPageMargins | mlreportgen.dom.DOCXSection
12-101
12 Classes – Alphabetical List
mlreportgen.dom.DOCXRawFormat class
Package: mlreportgen.dom
Description
XML markup for an array of Microsoft Word formats.
Construction
docxRawFormatObj = DOCXRawFormat() creates an empty array of raw formats.
Output Arguments
docxRawFormatObj — XML markup for Word formats
mlreportgen.dom.DOCXRawFormat object
Properties
Id — ID for document element
string
Specify a cell array of strings. Each string contains Word XML markup for a Word
format.
12-102
mlreportgen.dom.DOCXRawFormat class
For information about XML markup for Word formats, see http://officeopenxml.com/
anatomyofOOXML.php.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Turn on Line Numbering Based on Default DOM Template
s = d.CurrentDOCXSection;
s.RawFormats = [s.RawFormats ...
{'<w:lnNumType w:countBy="1" w:start="1" w:restart="newSection"/>'}];
append(d,'This document has line numbers');
close(d);
rptview('myreport','docx');
See Also
mlreportgen.dom.DOCXSection
More About
• “Report Formatting Approaches”
12-103
12 Classes – Alphabetical List
mlreportgen.dom.DOCXSection class
Package: mlreportgen.dom
Description
Use an mlreportgen.dom.DOCXSection object to define the page format, headers, and
footers of a Word document section.
If this is the first DOCXSection in a document, then it controls the page layout of all the
document elements from the beginning of a document to this DOCXSection.
If this is the second or later DOCXSection in a document, then it controls the page layout
of all the document elements from the preceding DOCXSection to itself.
Before you set properties (such as margin widths) of a DOCXSection object, open the
Document object that contains the DOCXSection object.
Construction
docxSectionObj = DOCXSection() creates an empty document section.
Output Arguments
docxSectionObj — Numbering stream counter reset
mlreportgen.dom.DOCXSection object
Properties
Id — ID for document element
string
12-104
mlreportgen.dom.DOCXSection class
You can define up to three page footers for a section — one each for:
You can define up to three page headers for a section — one each for:
Cell array of strings, with each string containing Word XML markup for a Word format.
For information about XML markup for Word formats, see http://officeopenxml.com/
anatomyofOOXML.php.
12-105
12 Classes – Alphabetical List
The formats you specify using this property override corresponding formats defined by
the stylesheet style specified by the StyleName property. The DOM interface ignores
formats that do not apply to this element.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Change Page Margins of a Document Section
import mlreportgen.dom.*;
d = Document('mydoc','docx');
Open the document, which generates a DOCXSection object from the default template
and assigns the handle of the object to d.CurrentDOCXSection.
open(d);
Assign a handle for the document DOCXSection object to the DOCXSection object s.
s = d.CurrentDOCXSection;
s.PageMargins.Left = '0.5in';
12-106
mlreportgen.dom.DOCXSection class
p = Paragraph('Hello World');
append(d,p);
close(d);
rptview('mydoc.docx');
See Also
mlreportgen.dom.DocumentPart | mlreportgen.dom.DOCXPageFooter |
mlreportgen.dom.DOCXPageHeader | mlreportgen.dom.DOCXPageMargins
| mlreportgen.dom.DOCXPageSize | mlreportgen.dom.DOCXRawFormat |
mlreportgen.dom.DOCXSubDoc
More About
• “Report Formatting Approaches”
12-107
12 Classes – Alphabetical List
mlreportgen.dom.DOCXSubDoc class
Package: mlreportgen.dom
Description
Reference to external Microsoft Word document.
Construction
docxSubDocObj = DOCXSubDoc() creates an empty document reference.
Input Arguments
path — Path of document targeted by this reference
string
Output Arguments
docxSubDocObj — Reference to external Word document
mlreportgen.dom.DOCXSubDoc object
12-108
mlreportgen.dom.DOCXSubDoc class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Path of document targeted by this reference, specified as a string. Use ASCII characters.
Use the following format for specifying a full path involving a mapped drive.
'file:///C:/UserPath/FileName.docx'
Methods
Method Purpose
clone Clone this Word document reference.
12-109
12 Classes – Alphabetical List
Examples
Append a Word Document to a Report
import mlreportgen.dom.*
info = Document('CompanyInfo','docx');
append(info,'XYZ, Inc., makes widgets.');
close(info);
infoPath = info.OutputPath;
rpt = Document('Report','docx');
open(rpt);
append(rpt,DOCXSubDoc(infoPath));
close(rpt);
rptview(rpt.OutputPath);
See Also
mlreportgen.dom.DocumentPart | mlreportgen.dom.DOCXSection
12-110
mlreportgen.dom.ErrorMessage class
mlreportgen.dom.ErrorMessage class
Package: mlreportgen.dom
Error message
Description
Specifies error message text originating from a specified source object.
Construction
errorMsgObj = ErrorMessage(text,sourceObject) creates an error message with
the specified text originating from the specified source object.
Input Arguments
text — Message text
string
Output Arguments
errorMsgObj — Error message
mlreportgen.dom.ErrorMessage object
Properties
Id — ID for document element
string
12-111
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Use ErrorMessage methods similar to how you use ProgressMessage methods.
Method Purpose
formatAsHTML Format message as HTML.
formatAsText Format message as text.
passesFilter Determine whether message passes filter.
Examples
Create an Error Message
import mlreportgen.dom.*;
12-112
mlreportgen.dom.ErrorMessage class
d = Document('test','html');
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher,ErrorMessage('invalid chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = {CounterInc('chapter'),...
CounterReset('table'),WhiteSpace('pre')};
append(p,AutoNumber('chapter'));
append(d,p);
close(d);
rptview('test','html');
delete(l);
See Also
mlreportgen.dom.MessageDispatcher.dispatch
12-113
12 Classes – Alphabetical List
mlreportgen.dom.ExternalLink class
Package: mlreportgen.dom
Description
Defines a hyperlink to a location outside of the document.
Construction
externalLinkObj = ExternalLink(target,linkText) creates a hyperlink to the
specified target and having the specified link text. This constructor creates a text object
(mlreportgen.dom.Text) to hold the link text.
externalLinkObj = ExternalLink(target,linkText,linkTextStyleName)
creates a hyperlink with the specified link text and style name.
Input Arguments
target — Target of link
string | mlreportgen.dom.LinkTarget object
The link target of the external link, specified as either a string (for a URL) or as an
mlreportgen.dom.LinkTarget object.
12-114
mlreportgen.dom.ExternalLink class
Output Arguments
externalLinkObj — External link
mlreportgen.dom.ExternalLink object
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
HTML or Microsoft Word must support the custom attributes of this document element.
Name of link style defined in the template, specified as a string. The style specified by
styleName must be defined in the template used to create the document to which the
link is appended.
12-115
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
This read-only property displays the URL of the link target of this hyperlink.
Methods
Method Purpose
append Append text or a Text, Image, or
CustomElement object.
clone Copy the external link
Examples
Add an External Link
import mlreportgen.dom.*
d = Document('mydoc');
append(d,ExternalLink('http://www.mathworks.com/','MathWorks'));
close(d);
rptview('mydoc','html');
• “Create Links”
See Also
mlreportgen.dom.InternalLink | mlreportgen.dom.LinkTarget
12-116
mlreportgen.dom.FirstLineIndent class
mlreportgen.dom.FirstLineIndent class
Package: mlreportgen.dom
Description
Indent first line of a paragraph.
Construction
firstLineIndentObj = FirstLineIndent() creates an empty first line indentation
format object.
Input Arguments
width — Width of indentation of first line of paragraph
string
String specifying the width of indentation of first line of paragraph. String must have the
format valueUnits where Units is an abbreviation for the units in which the size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
12-117
12 Classes – Alphabetical List
• pt — points
• px — pixels
String specifying the style of indentation of the first line of the paragraph.
Output Arguments
firstLineIndentObj — Indentation for first line of paragraph
mlreportgen.dom.FirstLineIndent object
Properties
Id — ID for document element
string
String specifying the style of indentation of the first line of the paragraph.
12-118
mlreportgen.dom.FirstLineIndent class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String specifying the width of indentation of first line of paragraph. String must have the
format valueUnits where Units is an abbreviation for the units in which the size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
See Also
mlreportgen.dom.Paragraph
More About
• “Report Formatting Approaches”
12-119
12 Classes – Alphabetical List
mlreportgen.dom.FlowDirection class
Package: mlreportgen.dom
Description
Specifies the direction for text to flow across a page or the order of columns.
Construction
flowDirectionObj = FlowDirection() causes text to flow from left to right and for
the first column to be on the left side of a table.
Input Arguments
flow — Control text flow or table column ordering
string
String specifying the direction for text to flow or for table columns to appear.
Output Arguments
flowDirectionObj — Text flow direction or column order
mlreportgen.dom.FlowDirection object
12-120
mlreportgen.dom.FlowDirection class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String specifying the direction for text to flow or the order of table columns.
Examples
Flow Text from Right to Left
In this example, changing the text flow direction changes “stressed” into “desserts”.
import mlreportgen.dom.*;
doctype = 'docx';
d = Document('test',doctype);
p = Paragraph('desserts');
p.Style = {FlowDirection('rtl')};
append(d,p);
12-121
12 Classes – Alphabetical List
q = clone(p);
q.Style = {FlowDirection('ltr')};
append(d,q);
close(d);
rptview(d.OutputPath,doctype);
12-122
mlreportgen.dom.FontFamily class
mlreportgen.dom.FontFamily class
Package: mlreportgen.dom
Font family
Description
Properties of font family to be used to format document text.
Construction
fontFamilyObj = FontFamily() creates a Times New Roman font family.
Input Arguments
fontStr — Font family
string
Output Arguments
fontFamilyObj — Font family
mlreportgen.dom.FontFamily object
Properties
BackupFamilyNames — Backup font families
cell array
For HTML documents only. Cell array of strings specifying font families that a browser
can use if the font family specified in FamilyName is not available on a system.
12-123
12 Classes – Alphabetical List
For Word documents only. String specifying a font family to substitute in a locale that
requires a complex script (such as Arabic) to render text.
For Word documents only. String specifying a font family to substitute in an East Asian
locale, such as China, Japan, or Korea.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.CharEntity | mlreportgen.dom.FontSize |
mlreportgen.dom.Paragraph | mlreportgen.dom.Text
More About
• “Report Formatting Approaches”
12-124
mlreportgen.dom.FontSize class
mlreportgen.dom.FontSize class
Package: mlreportgen.dom
Font size
Description
Specifies the size of a font.
Construction
fontSizeObj = FontSize() creates a 12-point font.
Input Arguments
sizeStr — Font size
'12pt' (default) | string
String having the format valueUnits, where Units is an abbreviation for the units in
which the size is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Output Arguments
fontSizeObj — Font size
mlreportgen.dom.FontSize object
12-125
12 Classes – Alphabetical List
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String having the format valueUnits, where Units is an abbreviation for the units in
which the size is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
See Also
mlreportgen.dom.FontFamily | mlreportgen.dom.Paragraph |
mlreportgen.dom.Text
12-126
mlreportgen.dom.FontSize class
More About
• “Report Formatting Approaches”
12-127
12 Classes – Alphabetical List
mlreportgen.dom.FormalTable class
Package: mlreportgen.dom
Formal table
Description
Defines a formal table, which is a table that has a body and optionally a
table header or table footer, or both. The table header, body, and footer are
mlreportgen.dom.TableHeader, mlreportgen.dom.TableBody, and
mlreportgen.dom.TableFooter objects, respectively.
Construction
formalTableObj = FormalTable() creates an empty formal table. Use this
constructor as the starting point to create a formal table from scratch.
12-128
mlreportgen.dom.FormalTable class
Input Arguments
ncols — Number of columns in table
numeric value
The style specified by styleName must be defined in the template used to create the
document that contains this table.
12-129
12 Classes – Alphabetical List
12-130
mlreportgen.dom.FormalTable class
Output Arguments
formalTableObj — Formal table
mlreportgen.dom.FormalTable object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
The table constructor creates a table body object and assigns it to this property when the
formal table is constructed. You cannot subsequently set this property. However, you can
append content to the table body and set its properties via this property.
12-131
12 Classes – Alphabetical List
12-132
mlreportgen.dom.FormalTable class
BorderCollapse — Collapse borders of adjacent cells into single border (HTML only)
string
A value of 'on' collapses borders of adjacent cells into a single border. A value of 'off'
keeps borders of adjacent cells.
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
12-133
12 Classes – Alphabetical List
String specifying the width of the border. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
This read-only property lists child elements that the document element contains.
The style the line separating the columns of a table or table section (header, body, footer),
as specified by a mlreportgen.dom.ColSep object.
See the description of the Border property for a description of the possible values.
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
12-134
mlreportgen.dom.FormalTable class
String having the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
For example, for a three pica wide column separator, set the ColSepWidth property to
3pi.
The custom attributes must be supported by the output type of the document to which
this document element is appended.
• 'ltr' — flow from left to right (column 1 is to the left in the table)
• 'rtl' — flow from right to left (column 1 is to the right in the table)
12-135
12 Classes – Alphabetical List
The table constructor creates a table footer object and assigns it to this property when
the formal table is constructed. You cannot subsequently set this property. However, you
can append content to the table body and set its properties via this property.
• center
• left
• right
The table constructor creates a table header object and assigns it to this property when
the formal table is constructed. You cannot subsequently set this property. However, you
can append content to the table body and set its properties via this property.
String specifying the left indentation. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
12-136
mlreportgen.dom.FormalTable class
• pi — picas
• pt — points
• px — pixels
The style of a line separating the rows of a table or table section (header, body, or footer).
See the description of the Border property for a description of the possible values.
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String specifying the width of the row separator. The string must have the format
valueUnits where Units is an abbreviation for the units in which the width size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
12-137
12 Classes – Alphabetical List
Array of format objects (such as Bold objects) that specify the format for this table.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
Name of a style specified in the stylesheet of the document or document part to which
this table is appended
The style that specifies the appearance of this table in the output document, for formats
not specified by Style property.
You can set the StyleName property of any formal table section. Setting StyleName
overrides the style specified by the formal table itself. However, if you do this for a Word
document, you must explicitly specify the width of each column in a section to ensure
that all sections have the same width. Word, unlike HTML, has no built-in support for
formal tables. To handle this, the DOM interface represents a formal table as three
tables, one for each section, embedded in a 3x1 table.
Cell array of format objects that specify the format for table entries.
The inner margin is the margin between table cell content and the cell borders.
The string must have the format valueUnits where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
12-138
mlreportgen.dom.FormalTable class
• pt — points
• px — pixels
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String representing a percentage (for example, '100%') of the page width (minus
margins for Word reports) or a number of units of measurement, having the format
valueUnits, where Units is an abbreviation for the units in which the width is
expressed.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Methods
Method Purpose
append Append a row of table entries to table.
12-139
12 Classes – Alphabetical List
Method Purpose
clone Copy the table.
See Also
mlreportgen.dom.ResizeToFitContents | mlreportgen.dom.Table
| mlreportgen.dom.TableBody | mlreportgen.dom.TableColSpec
| mlreportgen.dom.TableEntry | mlreportgen.dom.TableFooter |
mlreportgen.dom.TableHeader | mlreportgen.dom.TableRow
Related Examples
• “Create and Format Tables”
12-140
mlreportgen.dom.Group class
mlreportgen.dom.Group class
Package: mlreportgen.dom
Description
Group of document objects that you can append multiple times in a document without
you having to clone the group. When you append a group to a document, the DOM
interface clones the group.
• Use a group object to append the same content in multiple places in a document
without having to clone the group. Group objects do not have a Style property for
using the same applicable styles to all document elements in the group.
Construction
groupObj = Group() creates an empty group.
Output Arguments
groupObj — Group of document objects
mlreportgen.dom.Group object
12-141
12 Classes – Alphabetical List
Properties
Id — ID for document element
string
This read-only property lists child elements that the document element contains.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append a DOM object to the group
See Also
mlreportgen.dom.Container
12-142
mlreportgen.dom.Group class
Related Examples
• “Add Content as a Group”
• “Create Object Containers”
12-143
12 Classes – Alphabetical List
mlreportgen.dom.HAlign class
Package: mlreportgen.dom
Description
Specifies horizontal alignment of a document object.
Construction
alignObj = HAlign() creates an alignment object having the value 'left'.
Input Arguments
value — Horizontal alignment
string
• 'center'
• 'left'
• 'right'
Output Arguments
horizontalAlignObj — Horizontal alignment
mlreportgen.dom.HAlign object
Properties
Id — ID for document element
string
12-144
mlreportgen.dom.HAlign class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• 'center'
• 'left'
• 'right'
See Also
mlreportgen.dom.VAlign
More About
• “Report Formatting Approaches”
12-145
12 Classes – Alphabetical List
mlreportgen.dom.Heading class
Package: mlreportgen.dom
Heading paragraph
Description
Create a heading paragraph.
Construction
headingObj = Heading(level) creates an empty heading at the specified level.
Input Arguments
text — Text string
string
12-146
mlreportgen.dom.Heading class
The style specified by styleName must specify a paragraph style defined in the template
used to create the document to which this heading is appended.
• ExternalLink
• Image
• InternalLink
• LinkTarget
• Text
Output Arguments
headingObj — Heading paragraph
mlreportgen.dom.Heading object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
To make text bold, set this property to true or 1. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the weight
of the text is determined by that style. Setting the Bold property adds a corresponding
mlreportGen.dom.Bold format object to the Style property of this document element.
Removing the Bold property setting removes the object.
12-147
12 Classes – Alphabetical List
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
HTML or Microsoft Word must support the custom attributes of this document element.
Amount by which to indent the first line of this paragraph relative to succeeding lines.
To create a hanging indent, in which all the lines are indented except for the first line,
use a negative number.
The string has the format valueUnits, where Units is an abbreviation for the units
in which the indentation is expressed. Use one of these abbreviations for the units for
indentation.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
12-148
mlreportgen.dom.Heading class
To specify substitutions for this font, do not set this property. Instead create and add a
mlreportgen.dom.FontFamily object to the Style property of this document element.
String having the format valueUnits, where Units is an abbreviation for the units in
which the font size is expressed. Use one of these abbreviations for the units for the font
size.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
• center
• left
• right
To use italics for text, set this property to true. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the slant of
the text is determined by that style. Setting the Italic property adds a corresponding
mlreportGen.dom.Italic format object to the Style property of this document
element. Removing the Italic property setting removes the object.
12-149
12 Classes – Alphabetical List
String specifying the left indentation. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
The default for this property is []. You can set it to one of these values:
12-150
mlreportgen.dom.Heading class
The style specified by styleName must be defined in the template used to create the
document element to which this text is appended.
Data Types: char
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-151
12 Classes – Alphabetical List
If this property is empty and StyleName property of this document element specifies a
style sheet style, the type of underline is determined by that style.
To specify the color as well as the type of the underline, do not set the Underline
property. Instead, set the Style property of this document element to include an
mlreportgen.dom.Underline format object that specifies the desired underline type
and color.
To specify how to handle white space, use one of the following strings.
12-152
mlreportgen.dom.Heading class
If you want to view HTML output in the MATLAB browser and you want to preserve
white space and wrap text only on line breaks, use the preserve setting rather than the
pre setting.
Methods
Method Purpose
append Append content to heading.
12-153
12 Classes – Alphabetical List
Method Purpose
clone Copy heading.
See Also
mlreportgen.dom.Paragraph
12-154
mlreportgen.dom.Height class
mlreportgen.dom.Height class
Package: mlreportgen.dom
Height of object
Description
Specifies the height of an image.
Construction
heightObj = Height() creates a format object that specifies a height of 1 inch.
Input Arguments
value — Height of object
'1in' (default) | string
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Output Arguments
heightObj — Height of object
mlreportgen.dom.Height object
12-155
12 Classes – Alphabetical List
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
See Also
mlreportgen.dom.RowHeight | mlreportgen.dom.Width
12-156
mlreportgen.dom.Height class
More About
• “Report Formatting Approaches”
12-157
12 Classes – Alphabetical List
mlreportgen.dom.HTML class
Package: mlreportgen.dom
Description
Converts a string of HTML text to an HTML object containing DOM objects having the
same content and format.
Construction
htmlObj = HTML() creates an empty HTML object.
12-158
mlreportgen.dom.HTML class
For information about these elements, see the W3Schools tags documentation at
www.w3schools.com/tags.
• background-color
• border
• border-bottom
• border-bottom-color
• border-bottom-style
• boder-bottom-width
• border-color
• border-left
12-159
12 Classes – Alphabetical List
• border-left-color
• border-left-style
• boder-left-width
• border-right
• border-right-color
• border-rigtht-style
• border-right-width
• border-style
• border-top
• border-top-color
• border-top-style
• border-top-width
• color
• font-family
• font-size
• font-style
• font-weight
• height
• line-height
• margin
• margin-bottom
• margin-left
• margin-right
• margin-top
• padding
• padding-bottom
• padding-left
• padding-right
• padding-top
• text-align
12-160
mlreportgen.dom.HTML class
• text-decoration
• text-indent
• vertical-align
• white-space
• width
For information about these formats, see the W3Schools CSS documentation at
www.w3schools.com/cssref.
Input Arguments
htmlText — HTML text
string
Properties
Id — ID for HTML object
string
Tag name of HTML container element, specified as a string, such as 'div', 'section',
or 'article' corresponding to this HTML object. This property applies only to HTML
output.
This read-only property lists child elements that the HTML object contains.
12-161
12 Classes – Alphabetical List
Formatting to apply to this HTML object, specified as a cell array of DOM format objects.
The children of this HTML object inherit any of these formats that they do not override.
Style name of this HTML object, specified as a string. Use a name of a style specified in
the stylesheet of the document to which this HTML object is appended. The specified style
defines the appearance of the HTML object in the output document where not overridden
by the formats specified by this StyleName property of the HTML object.
A session-unique ID is generated as part of HTML object creation. The generated tag has
the form CLASS:ID, where CLASS is the class of the element and ID is the value of the
Id property of the object. You can specify a tag to replace the generated tag.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Examples
Convert HTML Text to a Word Report
Create an HTML object from HTML text to use for a Word report.
import mlreportgen.dom.*;
12-162
mlreportgen.dom.HTML class
rpt = Document('MyRep1','docx');
html = HTML('<p><b>Hello</b> <i style="color:green">World</i></p>');
Append content to the HTML object and append the HTML object to the document.
See Also
mlreportgen.dom.Document.addHTML | mlreportgen.dom.HTMLFile
More About
• “Appending HTML to DOM Reports”
• “HTML Code Requirements for DOM Reports”
Introduced in R2015a
12-163
12 Classes – Alphabetical List
mlreportgen.dom.HTMLFile class
Package: mlreportgen.dom
Description
Converts the contents of an HTML file to an HTMLFile object containing DOM objects
having the same content and format.
Construction
htmlFileObj = HTMLFile(htmlFile) converts the HTML file to an HTMLFile object
containing DOM objects having the same content and format.
12-164
mlreportgen.dom.HTMLFile class
For information about these elements, see the W3Schools tags documentation at
www.w3schools.com/tags.
• background-color
• border
• border-bottom
• border-bottom-color
• border-bottom-style
• boder-bottom-width
• border-color
• border-left
• border-left-color
12-165
12 Classes – Alphabetical List
• border-left-style
• boder-left-width
• border-right
• border-right-color
• border-rigtht-style
• border-right-width
• border-style
• border-top
• border-top-color
• border-top-style
• border-top-width
• color
• font-family
• font-size
• font-style
• font-weight
• height
• line-height
• margin
• margin-bottom
• margin-left
• margin-right
• margin-top
• padding
• padding-bottom
• padding-left
• padding-right
• padding-top
• text-align
• text-decoration
12-166
mlreportgen.dom.HTMLFile class
• text-indent
• vertical-align
• white-space
• width
For information about these formats, see the W3Schools CSS documentation at
www.w3schools.com/cssref.
Input Arguments
htmlFile — HTML file path
string
Properties
Id — ID for HTMLFile object
string
Tag name of HTML container element, specified as a string, such as 'div', 'section',
or 'article' corresponding to this HTMLFile object. This property applies only to
HTML output.
This read-only property lists child elements that the HTMLFile object contains.
12-167
12 Classes – Alphabetical List
Formatting to apply to the HTMLFile object, specified as a cell array of DOM format
objects. The children of this HTMLFile object inherit any of these formats that they do
not override.
Style name of this HTMLFile object, specified as a string. Use a name of a style specified
in the stylesheet of the document to which this HTMLFile object is appended. The
specified style defines the appearance of the HTMLFile object in the output document
where not overridden by the formats specified by this StyleName property of the
HTMLFile object.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Examples
Convert Simulink HTML File to Word Report
This example assumes that there are HTML files called myHTMLfile1.html and
myHTMLfile2.htmlin the MATLAB current folder.
12-168
mlreportgen.dom.HTMLFile class
rpt = Document('MyHTMLReport','docx');
Create the first HTMLFile object and append HTML markup and an HTML object to the
HTMLFile object.
path = 'myHTMLfile1.html';
htmlFile1 = HTMLFile(path);
append(htmlFile1,'<p>This is <u>HTML markup text</u></p>');
htmlObj = HTML('<p>This is an <b>HTML object</b></p>');
append(htmlFile1,htmlObj);
Append the second HTMLFile object to the first HTMLFile object, and append the first
HTMLFile object to the document.
append(htmlFile1,htmlFile2)
append(rpt,htmlFile1);
See Also
mlreportgen.dom.Document.addHTMLFile | mlreportgen.dom.HTML
More About
• “Appending HTML to DOM Reports”
• “HTML Code Requirements for DOM Reports”
Introduced in R2015a
12-169
12 Classes – Alphabetical List
mlreportgen.dom.Image class
Package: mlreportgen.dom
Description
Create an image to be included in a report.
Construction
imageObj = Image(imagePath) creates an image object containing the image file
specified by imagePath.
The contents of the specified image file are copied into the output document either when
the image object is appended to the document (in document streaming mode) or when
the document is closed. Do not delete the original file before it has been copied into the
document.
Input Arguments
imagePath — Path of image file
string
For a Microsoft Word report, you can use these image formats:
• .bmp
• .emf
• .eps
• .gif
• .jpeg
• .jpg
12-170
mlreportgen.dom.Image class
• .png
• .tif
• .tiff
For HTML reports, you can use the same image formats as for a Word report, plus you
can use .svg format.
Output Arguments
imageObj — Image
mlreportgen.dom.Image object
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
HTML or Microsoft Word must support the custom attributes of this document element.
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Alternatively, you can specify the image height using the Image.Style property. For
example:
12-171
12 Classes – Alphabetical List
Image.Style = {Height('4in')};
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-172
mlreportgen.dom.Image class
• top
• bottom
• middle
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Methods
Method Purpose
append Append a custom element to this image.
See Also
mlreportgen.dom.ImageArea | mlreportgen.dom.ImageMap |
mlreportgen.dom.ScaleToFit
12-173
12 Classes – Alphabetical List
Related Examples
• “Create and Format Images”
12-174
mlreportgen.dom.ImageArea class
mlreportgen.dom.ImageArea class
Package: mlreportgen.dom
Description
Define an area in an image to be an HTML hyperlink. When a user clicks an image area,
the HTML browser displays the target page, based on the URL or link target you specify.
You can provide alternative text for screen reader users.
Construction
imageAreaObj = ImageArea() creates an empty image area.
Input Arguments
target — Image area hyperlink target
string
12-175
12 Classes – Alphabetical List
12-176
mlreportgen.dom.ImageArea class
Specify an array of x and y coordinate pairs, with coordinates for each corner of the
polygon, in the form [x1, y1, x2, y2, ... xN, yN]. Specify the coordinates to
reflect the corners of the polygon, in sequence.
Specify each coordinate relative to the top-left corner of the image, in pixels.
Output Arguments
imageAreaObj — Image area hyperlink
mlreportgen.dom.ImageArea object
Properties
Target — Image area target
string
12-177
12 Classes – Alphabetical List
(Read-only) The coordinates represent different kinds of points, depending on the shape
of the image area. Coordinates are relative to the top-left corner of the image.
• For a rectangle, the coordinates represent the top-left corner and the bottom-right
corner.
• For a circle, the array represents the coordinates at the center of the circle and the
radius.
• For a polygon, the coordinates represent the corners.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Add Image Area to Image of a MATLAB Plot
import mlreportgen.dom.*
d = Document('imageArea','html');
12-178
mlreportgen.dom.ImageArea class
x = 0:pi/100:2*pi;
y = sin(x);
plot(x,y);
annotation('textbox', [0.2,0.4,0.1,0.1],...
'String', 'Help on plot function');
saveas(gcf,'plot_img.png');
plot1 = Image('plot_img.png');
append(d,plot1);
area1 = ImageArea(...
['http://www.mathworks.com/help/matlab/ref/' ...
'plot.html?searchHighlight=plot'], ...
'plot function help', 240,450,463,492);
map = ImageMap();
plot1.Map = map;
append(map,area1);
close(d);
rptview(d.OutputPath);
See Also
mlreportgen.dom.Image | mlreportgen.dom.ImageMap |
mlreportgen.dom.LinkTarget
12-179
12 Classes – Alphabetical List
mlreportgen.dom.ImageMap class
Package: mlreportgen.dom
Description
Map of image areas, which are areas within an image where a user can click to open
content in an HTML browser.
Construction
map = ImageMap() creates an empty image map. Use the ImageMap.append method
to add image areas to the map.
Output Arguments
map — Map of hyperlink areas in image
mlreportgen.dom.ImageMap object
Properties
Id — ID for document element
string
12-180
mlreportgen.dom.ImageMap class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append an image area to this image map.
clone Clone this image map.
Examples
Append an Image Area to an Image Map
import mlreportgen.dom.*
d = Document('imageArea','html');
x = 0:pi/100:2*pi;
y = sin(x);
plot(x,y);
annotation('textbox', [0.2,0.4,0.1,0.1],...
'String', 'Help on plot function');
saveas(gcf,'plot_img.png');
plot1 = Image('plot_img.png');
append(d,plot1);
area1 = ImageArea(...
['http://www.mathworks.com/help/matlab/ref/' ...
'plot.html?searchHighlight=plot'], ...
'plot function help', 240,450,463,492);
map = ImageMap();
12-181
12 Classes – Alphabetical List
plot1.Map = map;
append(map,area1);
close(d);
rptview(d.OutputPath);
See Also
mlreportgen.dom.Image | mlreportgen.dom.ImageArea
12-182
mlreportgen.dom.InnerMargin class
mlreportgen.dom.InnerMargin class
Package: mlreportgen.dom
Description
Specifies the margin between the content and the bounding box of a document object. A
bounding box of an object includes the border of the object (if it has a border), the inner
margin, and the object content.
Construction
marginObj = InnerMargin() creates an unspecified margin between the content of an
object and its bounding box.
Input Arguments
all — Margin size on all sides
string
String specifying the margin on all sides between the content of an object and its
bounding box. String must have the format valueUnits where Units is an abbreviation
for the units in which the width size is expressed. Valid abbreviations are:
• No abbreviation — pixels
12-183
12 Classes – Alphabetical List
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixel
String specifying the left margin between the content of an object and its bounding box.
See the all input argument description for valid strings.
String specifying the right margin between the content of an object and its bounding box.
See the all input argument description for valid strings.
String specifying the top margin between the content of an object and its bounding box.
See the all input argument description for valid strings.
String specifying the bottom margin between the content of an object and its bounding
box. See the all input argument description for valid strings.
Output Arguments
marginObj — Margin between content and bounding box
mlreportgen.dom.InnerMargin object
12-184
mlreportgen.dom.InnerMargin class
Properties
Bottom — Size of bottom margin
string
String specifying the bottom margin. String must have the format valueUnits where
Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• No abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixel
String specifying the left margin between the content of an object and its bounding box.
See the Bottom property description for valid strings.
String specifying the right margin between the content of an object and its bounding box.
See the Bottom property description for valid strings.
12-185
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String specifying the top margin between the content of an object and its bounding box.
See the Bottom property description for valid strings.
Examples
Add Inner Margins to a Paragraph
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Hello World');
p.Style = {Border('solid','red'), ...
HAlign('center'),InnerMargin('12pt')};
append(d,p);
p = Paragraph('More Greetings');
p.Style = {Border('solid','blue'), ...
HAlign('center'),InnerMargin('30pt')};
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.OuterMargin
More About
• “Report Formatting Approaches”
12-186
mlreportgen.dom.InternalLink class
mlreportgen.dom.InternalLink class
Package: mlreportgen.dom
Description
Hyperlink to a location in the same document that contains the hyperlink. Use this kind
of link to provide internal navigation within a document.
Construction
internalLinkObj = InternalLink(targetName,linkText) creates a hyperlink to
the specified link target object and uses the specified link text.
internalLinkObj = InternalLink(targetName,linkText,
linkTextStyleName) creates a hyperlink to the specified link target and uses the
specified style name for the link text.
Input Arguments
targetName — Link target name
string
Link target name, specified as string. The string is the value in the Name property
of an mlreportgen.dom.LinkTarget object or a URL.
12-187
12 Classes – Alphabetical List
Output Arguments
internalLinkObj — Internal link
mlreportgen.dom.InternalLink object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
HTML or Microsoft Word must support the custom attributes of this document element.
12-188
mlreportgen.dom.InternalLink class
Name of link style defined in the template, specified as a string. The style specified by
styleName must be defined in the template used to create the document to which the
link is appended.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append text or a Text, Image, or
CustomElement object.
Use InternalLink.append
in a similar way to how you use
ExternalLink.append.
clone Copy the internal link.
12-189
12 Classes – Alphabetical List
Examples
Add Internal Link
import mlreportgen.dom.*
d = Document('mydoc');
close(d);
rptview('mydoc','html');
• “Create Links”
See Also
mlreportgen.dom.ExternalLink | mlreportgen.dom.LinkTarget
12-190
mlreportgen.dom.Italic class
mlreportgen.dom.Italic class
Package: mlreportgen.dom
Description
Specifies whether text should be rendered italic.
Construction
italicObj = Italic() creates a format object that specifies that text should be
rendered italic.
italicObj = Italic(value) creates a format object that specifies that text should be
rendered italic if value is true; otherwise, upright.
Input Arguments
value — Option to use italic or not for a text object
logical value
A setting of false (or 0) uses upright text. A setting of true (or 1) renders text in italic
Data Types: logical
Output Arguments
italicObj — Italic format object
mlreportgen.dom.Italic object
Properties
Id — ID for document element
string
12-191
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Create paragraph that whose text is italic by default
import mlreportgen.dom.*
d = Document('mydoc');
p = Paragraph('italic text');
p.Style = {Italic};
append(d,p);
close(d);
rptview('mydoc', 'html');
12-192
mlreportgen.dom.Italic class
p.Style = {Italic};
append(d,p);
t = Text('upright text');
t.Style = {Italic(false)};
append(p,t);
close(d);
rptview('mydoc', 'html');
More About
• “Report Formatting Approaches”
12-193
12 Classes – Alphabetical List
mlreportgen.dom.KeepLinesTogether class
Package: mlreportgen.dom
Description
Start paragraph on new page if necessary
Construction
keepLinesTogetherObj = KeepLinesTogether() starts a paragraph on a new page
if it cannot fit entirely on current page.
Input Arguments
onoff — Keep paragraph on one page
logical
• true (default)
• false
• 0
A setting of true (or 1) starts a paragraph on a new page when it cannot fit entirely on
the current page. A setting of false (or 0) allows a paragraph to span two pages when it
cannot fit entirely on the current page.
Data Types: logical
Output Arguments
keepLinesTogetherObj — Start paragraph on new page if necessary
mlreportgen.dom.KeepLinesTogether object
12-194
mlreportgen.dom.KeepLinesTogether class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• true or 1 — Starts paragraph on a new page when it cannot fit entirely on the
current page.
• false or 0 — Allows the paragraph to span two pages when it cannot fit entirely on
the current page.
See Also
mlreportgen.dom.KeepWithNext | mlreportgen.dom.PageBreakBefore
More About
• “Report Formatting Approaches”
12-195
12 Classes – Alphabetical List
mlreportgen.dom.KeepWithNext class
Package: mlreportgen.dom
Description
Keep paragraph on same page as paragraph that follows it. This format applies only to
Microsoft Word documents.
Construction
obj = KeepWithNext() keeps a paragraph on the same page as the paragraph that
follows it.
Input Arguments
onoff — Keep paragraph on same page as next
logical
• true (default)
• false
• 1
• 0
A setting of true (or 1) keeps a paragraph on the same page as the paragraph that
follows it. A setting of false (or 0) allows a paragraph to be on a different page from the
paragraph that follows it.
Data Types: logical
12-196
mlreportgen.dom.KeepWithNext class
Output Arguments
keepWithNextObj — Keep paragraph on same page as next
mlreportgen.dom.keepWithNext object
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• true or 1 — Keeps a paragraph on the same page as the paragraph that follows it.
• false or 0 — Allows a paragraph to be on a different page from the paragraph that
follows it.
See Also
mlreportgen.dom.KeepLinesTogether | mlreportgen.dom.PageBreakBefore
12-197
12 Classes – Alphabetical List
More About
• “Report Formatting Approaches”
12-198
mlreportgen.dom.LineSpacing class
mlreportgen.dom.LineSpacing class
Package: mlreportgen.dom
Description
Specifies the spacing between lines of a paragraph.
Construction
lineSpacingObj = LineSpacing() specifies line spacing equal to the height of one
line at the paragraph font size.
Input Arguments
mulitple — Multiple of paragraph line height
1 (default) | scalar
Scalar that specifies the line spacing relative to the paragraph text line height.
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
12-199
12 Classes – Alphabetical List
• in — inches
• mm — millimeters
• pi — picas
• pt — points
Output Arguments
lineSpacingObj — Spacing between lines of paragraph
mlreportgen.com.LineSpacing object
Properties
Id — ID for document element
string
12-200
mlreportgen.dom.LineSpacing class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
Examples
Create Line Spacing 1.5 Times the Height of the Paragraph Text Lines
p = Paragraph();
p.Style = {LineSpacing(1.5)};
12-201
12 Classes – Alphabetical List
mlreportgen.dom.LinkTarget class
Package: mlreportgen.dom
Description
A target to use for internal and external links and for image area links. You can specify
a LinkTarget object when you construct an mlreportgen.dom.InternalLink or
mlreportgen.dom.ImageArea object.
Construction
targetObj = LinkTarget(name) creates a link target with the specified name.
Input Arguments
name — Name of link target
string
Microsoft Word replaces spaces in a link target names with underscore characters. Avoid
spaces in link target names in Word reports.
Output Arguments
targetObj — Link target object
mlreportgen.dom.LinkTarget object
12-202
mlreportgen.dom.LinkTarget class
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
HTML or Microsoft Word must support the custom attributes of this document element.
Microsoft Word replaces spaces in a link target names with underscore characters. Avoid
spaces in link target names in Word reports.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-203
12 Classes – Alphabetical List
Methods
Method Purpose
append Append content to link target.
clone Copy link target.
Examples
Link to Top of a Document
Define a link target at the top of the report and add an internal link to that target. In an
actual report, links to this target would appear further down in the report.
import mlreportgen.dom.*
d = Document('mydoc');
append(d,LinkTarget('home'));
append(d,InternalLink('home','Go to Top'));
close(d);
rptview('mydoc', 'html');
• “Create Links”
See Also
mlreportgen.dom.ExternalLink | mlreportgen.dom.ImageArea |
mlreportgen.dom.InternalLink
12-204
mlreportgen.dom.ListItem class
mlreportgen.dom.ListItem class
Package: mlreportgen.dom
Description
Specifies an item in an ordered (numbered) or unordered (bulleted) list.
Construction
listItemObj = ListItem() creates an empty list item.
listItemObj = ListItem(text) creates a list item using the specified text. The
constructor creates a Text object and appends the text object to the list item.
Input Arguments
text — Text for list item
string
You can specify a Paragraph object or elements that you can append to a paragraph,
including the following kinds of DOM objects:
• mlreportgen.dom.Text
12-205
12 Classes – Alphabetical List
• mlreportgen.dom.Paragraph
• mlreportgen.dom.Image
• mlreportgen.dom.Table
• mlreportgen.dom.FormalTable
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.InternalLink
• mlreportgen.dom.CustomElement
Output Arguments
listItemObj — List item
mlreportgen.dom.ListItem object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
HTML or Microsoft Word must support the custom attributes of this document element.
12-206
mlreportgen.dom.ListItem class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append a string or any of these kinds of
DOM objects to a list item:
Use ListItem.append in a similar way
as you use Paragraph.append, except you • Text
can append different content to a list item • Paragraph
than to a paragraph.
• Table
• Image
• ExternalLink
• InternalLink
• CustomElement
12-207
12 Classes – Alphabetical List
Method Purpose
clone Clone a list item.
Examples
Create List Items for an Ordered List
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Perform the following steps.');
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.OrderedList | mlreportgen.dom.UnorderedList
12-208
mlreportgen.dom.MessageDispatcher class
mlreportgen.dom.MessageDispatcher class
Package: mlreportgen.dom
Description
Dispatcher for document generation status messages.
Properties
Filter — Message filter
string
(Read-only) The value of this property is a filter that determines the types of messages
the dispatcher dispatches. You can control which types of messages are dispatched by
setting the properties of the filter.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-209
12 Classes – Alphabetical List
Methods
Method Purpose
dispatch Dispatch a document generation status
message.
getTheDispatcher Get the message dispatcher.
Examples
Add and Dispatch a Progress Message
This example shows how to add a progress message to display when generating a report.
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
d.Tag = 'My report';
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src,evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher,ProgressMessage('starting chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
append(d,p);
close(d);
rptview('test',doctype);
delete (l);
Check the progress messages in the MATLAB Command Window. The starting
chapter message appears, in addition to the predefined DOM progress messages.
12-210
mlreportgen.dom.MessageDispatcher class
See Also
mlreportgen.dom.MessageDispatcher.dispatch |
mlreportgen.dom.MessageDispatcher.getTheDispatcher |
mlreportgen.dom.MessageEventData | mlreportgen.dom.MessageFilter
12-211
12 Classes – Alphabetical List
mlreportgen.dom.MessageEventData class
Package: mlreportgen.dom
Description
Contains the message that triggered a message event.
Construction
messageEventDataObj = MessageEventData(msg) creates a message
event data object that contains a DOM message (for example, a message of type
mlreportgen.dom.ProgressMessage).
The DOM message dispatcher attaches an object of this type to a message event when
it dispatches a message. This enables message event listeners to retrieve the dispatched
message. You need to create instances of this type only if you want to create your own
message dispatcher.
Input Arguments
msg — Message object
message object
Output Arguments
messageEventDataObj — Holds message triggering message event
mlreportgen.dom.MessageEventData object
12-212
mlreportgen.dom.MessageEventData class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Capture Message Event Data
When you add a dispatcher, the DOM API creates the evtdata object, which is an
mlreportgen.dom.MessageEventData object.
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test', doctype);
d.Tag = 'My report';
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher, 'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
12-213
12 Classes – Alphabetical List
open(d);
dispatch(dispatcher, ProgressMessage('starting chapter', d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'), CounterReset('table'), WhiteSpace('pre') };
append(p, AutoNumber('chapter'));
append(d, p);
close(d);
rptview('test', doctype);
delete (l);
See Also
mlreportgen.dom.MessageDispatcher
12-214
mlreportgen.dom.MessageFilter class
mlreportgen.dom.MessageFilter class
Package: mlreportgen.dom
Description
Filter for messages dispatched by the message dispatcher.
Properties
DebugMessagePass — Pass or block debug messages
logical value
12-215
12 Classes – Alphabetical List
Pass messages only from the specified DOM object if the messages meet the other filter
conditions specified by this MessageFilter object.
See Also
mlreportgen.dom.MessageDispatcher.dispatch
Related Examples
• “Display Report Generation Messages”
12-216
mlreportgen.dom.OPCPart class
mlreportgen.dom.OPCPart class
Package: mlreportgen.dom
Description
Document part to include in an OPC package.
Construction
opcPartObj = OPCPart() creates an empty OPC part.
Input Arguments
name — Name of part
string
Output Arguments
opcPartObj — OPC part
mlreportgen.dom.OPCPart object
12-217
12 Classes – Alphabetical List
Properties
ContentType — Content type of part
string
Specifies the content type, using a file extension. For a list of file content types, see http://
www.en.wikipedia.org/wiki/Open_Packaging_Conventions.
If you do not set this property is not set and the part is one of the types listed below, the
DOM interface sets the content type when you append the part to a document.
12-218
mlreportgen.dom.OPCPart class
Path of this part relative to the root of the package. For example, to add an image
named myimage.jpg to a document images folder, specify the path as '/images/
myimage.jpg'.
RelationshipID — Relationship ID
string
Specifies a relationship type, using a file extension. For a list of file content types, see
http://www.en.wikipedia.org/wiki/Open_Packaging_Conventions.
If you do not set this property is not set and the part is one of the types listed below, the
DOM interface sets the content type when you append the part to a document.
12-219
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-220
mlreportgen.dom.OPCPart class
Examples
Add a File to an OPC Package
This code inserts a copy of the data.json file in the data subfolder of the mydoc
package. This example assumes that there is a data.json file in the current folder.
import reportgen.dom.*;
d = Document('mydoc','html');
package(d,OPCPart('/data/data.json','data.json'));
close(d);
See Also
mlreportgen.dom.Document.package
More About
• “Report Packages”
12-221
12 Classes – Alphabetical List
mlreportgen.dom.OrderedList class
Package: mlreportgen.dom
Description
Create an ordered (numbered) list.
Construction
orderedListObj = OrderedList() creates an empty ordered list.
Input Arguments
listItems — Content to include in the ordered list
cell array of strings
• A string
• A number
• A Boolean value
• One of the following DOM objects:
• mlreportgen.dom.Text
• mlreportgen.dom.Paragraph
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.InternalLink
• mlreportgen.dom.Table
• mlreportgen.dom.Image
12-222
mlreportgen.dom.OrderedList class
• mlreportgen.dom.CustomElement
• Horizontal one-dimensional array (for a sublist)
To append an ordered list, use an OrderedList DOM object instead of using the
listItems argument.
Output Arguments
orderedListObj — Ordered list
mlreportgen.dom.OrderedList object
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
HTML or Microsoft Word must support the custom attributes of this document element.
12-223
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append items to this list.
clone Copy the list.
Examples
Create an Ordered List
import mlreportgen.dom.*;
d = Document('test','html');
close(d);
rptview('test','html');
See Also
mlreportgen.dom.ListItem | mlreportgen.dom.UnorderedList
12-224
mlreportgen.dom.OuterMargin class
mlreportgen.dom.OuterMargin class
Package: mlreportgen.dom
Description
Specifies the margin between the bounding box of an object and adjacent document
objects. A bounding box of an object includes the border of the object (if it has a border),
the inner margin, and the object content.
Construction
marginObj = OuterMargin() creates an unspecified margin between the bounding
box of an object and its surroundings.
Input Arguments
all — Outer margin size on all sides
string
String specifying the margin on all sides between the bounding box of an object and its
surroundings. String must have the format valueUnits where Units is an abbreviation
for the units in which the width size is expressed. Valid abbreviations are:
• No abbreviation — pixels
12-225
12 Classes – Alphabetical List
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
String specifying the left margin between the bounding box of an object and its
surroundings. See the all argument for description of valid strings.
String specifying the right margin between the bounding box of an object and its
surroundings. See the all argument for description of valid strings.
String specifying the top margin between the bounding box of an object and its
surroundings. See the all argument for description of valid strings.
String specifying the bottom margin between the bounding box of an object and its
surroundings. See the all argument for description of valid strings.
Output Arguments
marginObj — Margin between bounding box and surroundings
mlreportgen.dom.OuterMargin object
12-226
mlreportgen.dom.OuterMargin class
Properties
Bottom — Size of bottom margin
string
String specifying the bottom margin. String must have the format valueUnits where
Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• No abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
String specifying the left margin. See the Bottom property for description of valid
strings.
String specifying the right margin. See the Bottom property for description of valid
strings.
String specifying the top margin. See the Bottom property for description of valid
strings.
12-227
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Add Margins to Paragraph That Has a Border
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Hello World');
p.Style = {Border('solid','Red'), ...
HAlign('center'),...
OuterMargin('0pt','0pt','0pt','24pt')};
append(d, p);
p = Paragraph('End of report');
p.Style = {Border('solid','blue'),...
HAlign('center'),...
OuterMargin('0pt','0pt','0pt','12pt')}
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.InnerMargin
12-228
mlreportgen.dom.OuterMargin class
More About
• “Report Formatting Approaches”
12-229
12 Classes – Alphabetical List
mlreportgen.dom.OutlineLevel class
Package: mlreportgen.dom
Description
Specifies the level of a paragraph in an automatically generated outline. This class
is intended for Microsoft Word reports, because HTML does not support displaying
paragraphs in a table of contents.
Construction
outlineLevelObj = OutlineLevel() sets the outline level of this paragraph to 1.
This causes the content of the paragraph to appear at the top level in an automatically
generated outline (for example, a table of contents).
Input Arguments
level — Specify the level of a paragraph in an outline
integer
Output Arguments
outlineLevelObj — Level of paragraph in outline
mlreportgen.dom.OutlineLevel object
12-230
mlreportgen.dom.OutlineLevel class
Properties
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Add a Table of Contents
Add an automatically generated table of contents and set the outline level of the
“Glossary” paragraph so that the paragraph appears at the top level of the table of
contents. This example uses the default DOM Word template.
Create a document and document part for the table of contents. The document part uses
the ReportTOC building block from the default DOM Word template.
import mlreportgen.dom.*
d = Document('tocDoc','docx');
12-231
12 Classes – Alphabetical List
open(d);
dp = DocumentPart(d,'ReportTOC');
append(d,dp);
Set the OutlineLevel property internally, so that there are four levels in the table of
contents.
for i = 1:4
% set internally the OutlineLevel property
append(d,Heading(i,'My Chapter'));
append(d,Paragraph('chapter content....'));
end
Use OutlineLevel to set the level of the Glossary paragraph to 1, so that the
paragraph appears at the top level of the table of contents. Display the report.
para = append(d,Paragraph('Glossary'));
para.Style = {OutlineLevel(1)};
close(d);
rptview(d.OutputPath,d.Type);
See Also
mlreportgen.dom.Heading | mlreportgen.dom.Paragraph
More About
• “Automatically Number Document Content”
12-232
mlreportgen.dom.PageBreakBefore class
mlreportgen.dom.PageBreakBefore class
Package: mlreportgen.dom
Description
Specifies to always start paragraph on new page. This is for Microsoft Word reports.
Construction
pageBreakBeforeObj = PageBreakBefore() always starts paragraph on a new
page.
Input Arguments
onOff — Start paragraph on new page
true (default)
Output Arguments
pageBreakBeforeObj — Start paragraph on new page
mlreportgen.dom.PageBreakBefore object
12-233
12 Classes – Alphabetical List
Properties
Tag — Tag for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.Paragraph
More About
• “Report Formatting Approaches”
12-234
mlreportgen.dom.Paragraph class
mlreportgen.dom.Paragraph class
Package: mlreportgen.dom
Description
Use a mlreportgen.dom.Paragraph object to define a paragraph. You can append
document elements, such as an image, to a paragraph.
Construction
paragraphObj = Paragraph(text) creates a paragraph containing a
mlreportgen.dom.Text object with the text specified by the text string.
Input Arguments
text — Paragraph text
string
The name of a style, specified as a string. The style must be defined in the template used
to create the document to which this paragraph is appended.
12-235
12 Classes – Alphabetical List
A DOM object to include in a paragraph. You can specify these DOM objects:
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.Image
• mlreportgen.dom.InternalLink
• mlreportgen.dom.Text
• mlreportgen.dom.LinkTarget
Output Arguments
paragraphObj — Paragraph
mlreportgen.dom.Paragraph object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
To make text bold, set this property to true or 1. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the weight
of the text is determined by that style. Setting the Bold property adds a corresponding
mlreportGen.dom.Bold format object to the Style property of this document element.
Removing the Bold property setting removes the object.
Data Types: logical
12-236
mlreportgen.dom.Paragraph class
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
HTML or Microsoft Word must support the custom attributes of this document element.
Amount by which to indent the first line of this paragraph relative to succeeding lines.
To create a hanging indent, in which all the lines are indented except for the first line,
use a negative number.
The string has the format valueUnits, where Units is an abbreviation for the units
in which the indentation is expressed. Use one of these abbreviations for the units for
indentation.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
12-237
12 Classes – Alphabetical List
To specify substitutions for this font, do not set this property. Instead create and add a
mlreportgen.dom.FontFamily object to the Style property of this document element.
The string has the format valueUnits, where Units is an abbreviation for the units
in which the indentation is expressed. Use one of these abbreviations for the units for
indentation.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Horizontal alignment for a paragraph, relative to page margins or table cell borders,
specified as a string.
12-238
mlreportgen.dom.Paragraph class
To use italics for text, set this property to true. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the slant of
the text is determined by that style. Setting the Italic property adds a corresponding
mlreportGen.dom.Italic format object to the Style property of this document
element. Removing the Italic property setting removes the object.
Data Types: logical
Space between the left outer boundary of this paragraph and the left inner boundary
of its container. This is equivalent to the left indentation property of a Microsoft Word
paragraph.
To indent a paragraph from both the left and right margin of a page, do not
set this property. Instead, add to the Style property of this paragraph a
mlreportgen.dom.OuterMargin object specifying the left and right indentations.
12-239
12 Classes – Alphabetical List
The string has the format valueUnits, where Units is an abbreviation for the units
in which the indentation is expressed. Use one of these abbreviations for the units for
indentation.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
The default for this property is []. You can set it to one of these values:
12-240
mlreportgen.dom.Paragraph class
A cell array of DOM format objects that specifies the formats for this paragraph style.
The style specified by styleName must be defined in the template used to create the
document element to which this paragraph is appended.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-241
12 Classes – Alphabetical List
If this property is empty and StyleName property of this document element specifies a
style sheet style, the type of underline is determined by that style.
To specify the color as well as the type of the underline, do not set the Underline
property. Instead, set the Style property of this document element to include an
mlreportgen.dom.Underline format object that specifies the desired underline type
and color.
12-242
mlreportgen.dom.Paragraph class
To specify how to handle white space, use one of the following strings.
If you want to view HTML output in the MATLAB browser and you want to preserve
white space and wrap text only on line breaks, use the preserve setting rather than the
pre setting.
Methods
Method Purpose
append Append text, images, links, link targets, or
custom elements to paragraph.
12-243
12 Classes – Alphabetical List
Method Purpose
clone Copy paragraph.
Examples
Add Paragraphs
close(doc);
rptview('mydoc','html');
See Also
mlreportgen.dom.LineSpacing | mlreportgen.dom.Text
More About
• “Report Formatting Approaches”
12-244
mlreportgen.dom.ProgressMessage class
mlreportgen.dom.ProgressMessage class
Package: mlreportgen.dom
Progress message
Description
Create a progress message with the specified text originating from the specified source
object.
Construction
progressMsgObj = ProgressMessage(text,sourceDOMObject) creates a progress
message with the specified text, originating from the specified source object.
Input Arguments
text — Message text
string
Output Arguments
progressMsgObj — Progress message
mlreportgen.dom.ProgressMessage object
12-245
12 Classes – Alphabetical List
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
formatAsHTML Wrap message in HTML tags.
formatAsText Format message as text.
passesFilter Determine if message passes filter.
12-246
mlreportgen.dom.ProgressMessage class
Examples
Create a Progress Message
delete(l);
See Also
mlreportgen.dom.MessageDispatcher.dispatch
12-247
12 Classes – Alphabetical List
mlreportgen.dom.RawText class
Package: mlreportgen.dom
Description
Word XML or HTML markup to insert in a document.
Construction
text = RawText() creates an empty RawText object.
You can append a RawText object only to a Document object. For a Word document, the
markup specified by the DOCXText property is included in the document. For an HTML
document, the value of the HTMLText property is included. In either case, the markup
must be valid Word XML or HTML markup, respectively, that can be validly inserted
in the body element of the output document. If you insert invalid markup in a Microsoft
Word document, Word may be unable to open the document.
Input Arguments
htmlMarkup — HTML markup code
string
HTML markup, specified as a string. To improve the readability of your report document,
consider assigning the markup to a variable. Then use the variable as an input
argument, as shown in the example below.
12-248
mlreportgen.dom.RawText class
Word XML markup or HTML markup, specified as a string. For a Word document, the
markup must be valid Word XML markup that can be inserted into the w:body element.
To improve the readability of your report document, consider assigning the markup to a
variable. Then use the variable as an input argument, as shown in the example below.
Output Arguments
rawText — Word XML or HTML markup to insert in document
mlreportgen.dom.RawText object
Properties
DOCXText — Text to output to Word document
string
Word XML markup, specified as a string. The value of this property is included in a Word
document. The markup must be valid Word XML markup that can be inserted into the
w:body element of a Word document.
HTML markup, specified as a string. The value of this property is included in an HTML
document. The text must be valid HTML markup that can be inserted into the body
element of an HTML document.
12-249
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Add HTML Markup
Assign HTML markup to a variable and use that variable to create a RawText object to
append to a document.
import mlreportgen.dom.*;
d = Document('test','html');
script = [ ...
'<script>' ...
'document.write("Hello World!")' ...
'</script>' ...
];
append(d,RawText(script));
close(d);
rptview('test','html');
See Also
mlreportgen.dom.CustomAttribute
12-250
mlreportgen.dom.RepeatAsHeaderRow class
mlreportgen.dom.RepeatAsHeaderRow class
Package: mlreportgen.dom
Description
Specifies to repeat a table row on each new page when a table flows across multiple
pages. This format applies only to Microsoft Word documents.
Construction
repeatAsHeaderRowObj = RepeatAsHeaderRow() repeats table row on each new
page when a table flows across multiple pages.
Input Arguments
onOff — Controls table row repeating on each new page
true (default)
• true or 1 — Table row repeats on each new page when a table flows across multiple
pages.
• false or 0 — Table row does not repeat on each new page when a table flows across
multiple pages.
Output Arguments
repeatAsHeaderRowObj — Repeat table row
mlreportgen.dom.RepeatAsHeaderRow object
12-251
12 Classes – Alphabetical List
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• true or 1 — Table row repeats on each new page when a table flows across multiple
pages.
• false or 0 — Table row does not repeat on each new page when a table flows across
multiple pages.
Examples
Repeat Table Row
12-252
mlreportgen.dom.RepeatAsHeaderRow class
import mlreportgen.dom.*;
doctype = 'docx';
d = Document('repeatHeader',doctype);
append(d,'Table 1');
table = Table(ones(15, 2));
table.Style = {Border('solid'),RowSep('solid')};
append(d,table);
Create a second table with repeated row with a table row that cannot break across pages.
append(d,'Table 2');
table = Table(ones(15,2));
table.entry(1,1).Children(1).Content = 'Header A';
table.entry(1,2).Children(1).Content = 'Header B';
table.row(1).Style = {RepeatAsHeaderRow(true)};
table.Style = {Border('solid'),RowSep('solid')};
append(d, table);
table.row(6).Style = {AllowBreakAcrossPages(false)};
table.entry(6,1).Children(1).Content = ...
'Start this row on new page if it does not fit on current page';
for i=2:10
table.entry(6,1).append(Paragraph(Text(i)));
end
close(d);
rptview(d.OutputPath,doctype);
See Also
mlreportgen.dom.AllowBreakAcrossPages | mlreportgen.dom.TableHeader
More About
• “Report Formatting Approaches”
12-253
12 Classes – Alphabetical List
mlreportgen.dom.ResizeToFitContents class
Package: mlreportgen.dom
Description
Specifies whether a table resizes its columns to fit content.
Construction
resizeToFitContentsObj = ResizeToFitContents() allows a table to resize its
columns to fit their contents.
Input Arguments
value — Allow table to resize its columns
logical value
A setting of true (or 1) allows a table to resize its columns to fit their contents. A setting
of false (or 0) causes the content to wrap.
Data Types: logical
Output Arguments
resizeToFitContentsObj — Allow table to resize its columns
mlreportgen.dom.ResizeToFitContents object
Specification of whether a table resizes its columns to fit content or wraps content,
represented by an mlreportgen.dom.ResizeToFitContents object.
12-254
mlreportgen.dom.ResizeToFitContents class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
A setting of true (or 1) allows a table to resize its columns to fit their contents. A setting
of false (or 0) causes the content to wrap.
Data Types: logical
Examples
Resize Table Columns to Fit Content
Create a table and specify to resize the column widths to fit the widest table entry in the
column.
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
append(d,Heading(1,'Table 1'));
table1 = Table(ones(4,4));
12-255
12 Classes – Alphabetical List
table1.entry(1,2).Children(1).Content = 'MathWorks';
table1.TableEntriesStyle = {Width('0.25in')};
append(d,table1);
Create a second table, but do not have the columns resize to fit content.
append(d,Heading(1,'Table 2'));
table2 = Table(ones(4, 4));
table2.entry(1,2).Children(1).Content = 'MathWorks';
table2.TableEntriesStyle = {Width('0.25in')};
append(d,table2);
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.Table |
mlreportgen.dom.TableColSpec | mlreportgen.dom.TableColSpecGroup
More About
• “Report Formatting Approaches”
12-256
mlreportgen.dom.RowHeight class
mlreportgen.dom.RowHeight class
Package: mlreportgen.dom
Description
Specifies the height of a table row.
Construction
rowHeightObj = RowHeight() specifies row height to be 1 inch.
Input Arguments
height — Height of table row
'1in' (default)
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
12-257
12 Classes – Alphabetical List
String that defines a row to be exactly the specified height or to be the specified height or
taller.
Output Arguments
rowHeightObj — Height of table row
mlreportgen.dom.RowHeight object
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String that defines a row to be exactly the specified height or to be the specified height or
taller.
12-258
mlreportgen.dom.RowHeight class
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Examples
Specify Table Row Heights
Create a table with two rows. The first row has a variable height and the second has a
fixed maximum height.
import mlreportgen.dom.*;
d = Document('myTableDoc','docx');
t = Table(2);
t.Style = {Border('solid'),RowSep('solid'),ColSep('solid')};
t.Width = '1in';
r1 = TableRow();
r1.Style = {RowHeight('.25in','atleast')};
append(r1,TableEntry(...
'This row can expand beyond .25 inches'));
append(r1,TableEntry('x'));
r2 = TableRow();
r2.Style = {RowHeight('.25in','exact')};
append(r2,TableEntry...
('Truncated text because height is fixed'));
append(r2,TableEntry('x'));
append(t,r1);
append(t,r2);
append(d,t);
12-259
12 Classes – Alphabetical List
close(d);
rptview('myTableDoc','docx');
See Also
mlreportgen.dom.TableRow
12-260
mlreportgen.dom.RowSep class
mlreportgen.dom.RowSep class
Package: mlreportgen.dom
Description
Draw lines (separators) between table rows.
Construction
rowSepObj = RowSep() creates unspecified row separators.
Input Arguments
style — Line style of table row separator
string
String Applies To
Word HTML
'dashed' X X
'dashdotstroked' X
'dashsmallgap' X
'dotted' X X
12-261
12 Classes – Alphabetical List
String Applies To
Word HTML
'dotdash' X
'dotdotdash' X
'double' X X
'doublewave' X
'inset' X X
'none' X X
'outset' X X
'single' X
'solid' X
'thick' X
'thickthinlargegap' X
'thickthinmediumgap' X
'thickthinsmallgap' X
'thinthicklargegap' X
'thinthickmediumgap' X
'thinthicksmallgap' X
'thinthickthinlargegap' X
'thinthickthinmediumgap' X
'thinthickthinsmallgap' X
'threedemboss' X
'threedengrave' X
'triple' X
'wave' X
String specifying the color of the table row separator. String can be a color, such as
'red' or a hexadecimal RGB value, such as '#0000ff'.
12-262
mlreportgen.dom.RowSep class
String specifying the color of the table row separator. String must have the format
valueUnits where Units is an abbreviation for the units in which the width size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Output Arguments
rowSepObj — Draw lines between table rows
mlreportgen.dom.RowSep object
Properties
Color — Text color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
12-263
12 Classes – Alphabetical List
Line style for the row separator. See the description of the style input argument for a
list of possible values.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String specifying the width of the table row separator. String must have the format
valueUnits where Units is an abbreviation for the units in which the width size is
expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Examples
Use Table Row Separators
Define the row separator as part of the Style property definition for the table.
12-264
mlreportgen.dom.RowSep class
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
t = Table(magic(5));
t.Style = {Border('inset','crimson','6pt'), ...
ColSep('double','DarkGreen','3pt'), ...
RowSep('double','Gold','3pt'), ...
Width('50%')};
t.TableEntriesInnerMargin = '6pt';
t.TableEntriesHAlign = 'center';
t.TableEntriesVAlign = 'middle';
append(d,t);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.Border | mlreportgen.dom.ColSep |
mlreportgen.dom.TableEntry | mlreportgen.dom.TableRow
12-265
12 Classes – Alphabetical List
mlreportgen.dom.ScaleToFit class
Package: mlreportgen.dom
Description
Specifies whether to scale an image to fit a page.
Construction
scaleToFitObj = ScaleToFit() scales an image to fit between the margins of a
Microsoft Word page.
Input Arguments
value — Scale image to fit page
[] (default) | logical value
A setting of false (or 0) does not scale the image. A setting of true (or 1) scales the
image to fit between the margins of a Microsoft Word page.
Data Types: logical
Output Arguments
scaleToFitObj — Scale image to fit page
mlreportgen.dom.ScaleToFit object
Properties
Id — ID for document element
string
12-266
mlreportgen.dom.ScaleToFit class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.Height | mlreportgen.dom.Image | mlreportgen.dom.Width
Related Examples
• “Create and Format Images”
12-267
12 Classes – Alphabetical List
mlreportgen.dom.Strike class
Package: mlreportgen.dom
Description
Specifies whether to use a strikethrough line for a text object. Strike appears as a single,
horizontal line drawn through the text.
Construction
strikeObj = Strike() draws a single, horizontal line through text.
Input Arguments
type — Specifies strike type
string
Output Arguments
strike — Strike through text
mlreportgen.dom.Strike object
12-268
mlreportgen.dom.Strike class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.Underline
More About
• “Report Formatting Approaches”
12-269
12 Classes – Alphabetical List
mlreportgen.dom.Table class
Package: mlreportgen.dom
Create table
Description
Use an mlreportgen.dom.Table object to define a table. Append rows and table
entries to add content to the table. You can define column properties.
Construction
tableObj = Table(ncols) creates an empty table having the specified number of
columns. Use this constructor as the starting point for creating a table from scratch.
Input Arguments
ncols — Number of columns in the table
double, specifying the number of columns in the table
Data Types: double
12-270
mlreportgen.dom.Table class
• mlreportgen.dom.Paragraph
• mlreportgen.dom.Text (CharEntity included)
• mlreportgen.dom.Image
• mlreportgen.dom.Table
• mlreportgen.dom.OrderedList
• mlreportgen.dom.UnorderedList
The style specified by styleName must be defined in the template of the document to
which this table is appended.
Data Types: char
Output Arguments
tableObj — Table
mlreportgen.dom.Table object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
12-271
12 Classes – Alphabetical List
12-272
mlreportgen.dom.Table class
BorderCollapse — Collapse borders of adjacent cells into single border (HTML only)
string
A value of 'on' collapses borders of adjacent cells into a single border. A value of 'off'
keeps borders of adjacent cells.
12-273
12 Classes – Alphabetical List
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String specifying the width of the border. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
This read-only property lists child elements that the document element contains.
The style the line separating the columns of a table or table section (header, body, footer),
as specified by a mlreportgen.dom.ColSep object.
See the description of the Border property for a description of the possible values.
12-274
mlreportgen.dom.Table class
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String having the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
For example, for a three pica wide column separator, set the ColSepWidth property to
3pi.
The custom attributes must be supported by the output type of the document to which
this document element is appended.
12-275
12 Classes – Alphabetical List
• center
• left
• right
String specifying the left indentation. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
12-276
mlreportgen.dom.Table class
The style of a line separating the rows of a table or table section (header, body, or footer).
See the description of the Border property for a description of the possible values.
• The name of a color. See the mlreportGen.dom.Color class reference page for a list
of supported colors.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
The string has the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Array of format objects (such as Bold objects) that specify the format for this table.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
12-277
12 Classes – Alphabetical List
Name of a style specified in the stylesheet of the document or document part to which
this table is appended
The style that specifies the appearance of this table in the output document, for formats
not specified by Style property.
• top
• middle
• bottom
The inner margin is the margin between table cell content and the cell borders.
The string must have the format valueUnits where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
12-278
mlreportgen.dom.Table class
Cell array of format objects that specify the format for table entries.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
String representing a percentage (for example, '100%') of the page width (minus
margins for Word reports) or a number of units of measurement, having the format
valueUnits, where Units is an abbreviation for the units in which the width is
expressed.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Methods
Method Purpose
append Append a content to a table.
clone Clone this table.
entry Get a table entry.
12-279
12 Classes – Alphabetical List
Method Purpose
row Create a table row.
Examples
Create a Table
import mlreportgen.dom.*;
d = Document('myreport', 'html');
open(d);
t = Table(magic(5));
t.Style = {RowHeight('1in')};
t.Border = 'solid';
t.BorderWidth = 'thin';
t.ColSep = 'solid';
t.ColSepWidth = '1';
t.RowSep = 'solid';
t.RowSepWidth = '1';
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.TableBody |
mlreportgen.dom.TableEntry | mlreportgen.dom.TableFooter |
mlreportgen.dom.TableHeader | mlreportgen.dom.TableHeaderEntry |
mlreportgen.dom.TableRow
12-280
mlreportgen.dom.TableBody class
mlreportgen.dom.TableBody class
Package: mlreportgen.dom
Description
Specifies the body of a formal table
Construction
tableBodyObj = TableBody() creates an empty table body.
Output Arguments
tableBodyObj — Formal table body
mlreportgen.dom.TableBody object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
The style the line separating the columns of a table or table section (header, body, footer),
as specified by a mlreportgen.dom.ColSep object.
See the description of the Border property for a description of the possible values.
12-281
12 Classes – Alphabetical List
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String having the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
For example, for a three pica wide column separator, set the ColSepWidth property to
3pi.
The style of a line separating the rows of a table or table section (header, body, or footer).
See the description of the Border property for a description of the possible values.
12-282
mlreportgen.dom.TableBody class
• The name of a color. See the mlreportGen.dom.Color class reference page for a list
of supported colors.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
• top
• middle
• bottom
12-283
12 Classes – Alphabetical List
The inner margin is the margin between table cell content and the cell borders.
The string must have the format valueUnits where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Cell array of format objects that specify the format for table entries.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Appends content to a table body.
entry Get a table entry.
row Create a table row.
12-284
mlreportgen.dom.TableBody class
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.Table |
mlreportgen.dom.TableEntry | mlreportgen.dom.TableFooter |
mlreportgen.dom.TableHeader | mlreportgen.dom.TableHeaderEntry |
mlreportgen.dom.TableRow
Related Examples
• “Create and Format Tables”
12-285
12 Classes – Alphabetical List
mlreportgen.dom.TableColSpec class
Package: mlreportgen.dom
Description
Define the formatting for one or more adjacent table columns. Use a TableColSpec
object to override formats specified by a TableColSpecGroup object.
Construction
colSpecObj = TableColSpec() creates a column specification having a span of 1.
Output Arguments
colSpecObj — Formatting for one or more adjacent table columns
mlreportgen.dom.TableColSpec object
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
HTML or Microsoft Word must support the custom attributes of this document element.
12-286
mlreportgen.dom.TableColSpec class
Span — Number of adjacent table columns to which this document element applies
number of adjacent table columns
If this property is not specified (its value is []), the value is assumed to be 1.
Data Types: double
Format objects that specify the style of the columns governed by this specification.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.ResizeToFitContents |
mlreportgen.dom.Table | mlreportgen.dom.TableColSpecGroup
Related Examples
• “Create and Format Tables”
12-287
12 Classes – Alphabetical List
mlreportgen.dom.TableColSpecGroup class
Package: mlreportgen.dom
Description
Define the style for a group of table columns. Use a TableColSpec object to override
formats specified by a TableColSpecGroup object.
Construction
colSpecGroupObj = TableColSpecGroup() creates a column specification that
spans an entire table.
Output Arguments
colSpecGroupObj — Table column specification
mlreportgen.dom.TableColSpecGroup object
Properties
ColSpec — Type of line to draw between columns of this table
this property accepts the same set of values as the Border property
Data Types: char
HTML or Microsoft Word must support the custom attributes of this document element.
12-288
mlreportgen.dom.TableColSpecGroup class
Span — Number of adjacent table columns to which this document element applies
number of adjacent table columns
If this property is not specified (its value is []), the value is assumed to be 1.
Data Types: double
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Make the First Column Green and Remaining Columns Red
import mlreportgen.dom.*
doc = Document('mydoc', 'docx');
append(doc, 'Table');
grps(1) = TableColSpecGroup;
grps(1).Style = {Color('red')};
specs(1) = TableColSpec;
specs(1).Style = {Color('green')};
grps(1).ColSpecs = specs;
12-289
12 Classes – Alphabetical List
table = Table(magic(5));
table.ColSpecGroups = grps;
close(doc);
rptview(doc.OutputPath);
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.ResizeToFitContents |
mlreportgen.dom.Table | mlreportgen.dom.TableColSpec
12-290
mlreportgen.dom.TableEntry class
mlreportgen.dom.TableEntry class
Package: mlreportgen.dom
Table entry
Description
Specifies the content and style of a table entry.
Tip To specify formatting for all table entries in a table, use the TableEntriesStyle
property of the Table or FormalTable object. For example, you can set border
formatting.
import mlreportgen.dom.*
t = Table(magic(5));
t.TableEntriesStyle = {Border('solid','black','1')};
Properties you set for a TableEntry object take precedence over TableEntriesStyle
format objects.
Construction
entryObj = TableEntry() creates an empty table entry.
entryObj = TableEntry(text) creates a table entry using the text included in the
specified mlreportgen.dom.Text object.
Input Arguments
text — Table entry text
string
12-291
12 Classes – Alphabetical List
textObj — Text object containing the text for the table entry
mlreportgen.dom.Text object
The style specified by styleName must be defined in the template of the document to
which this table is appended.
• mlreportgen.dom.Paragraph
• mlreportgen.dom.Text (CharEntity included)
• mlreportgen.dom.Image
• mlreportgen.dom.Table
• mlreportgen.dom.OrderedList
• mlreportgen.dom.UnorderedList
• mlreportgen.dom.CustomElement
Output Arguments
entryObj — Table entry
mlreportgen.dom.TableEntry object
Properties
Border — Type of border to draw
string
12-292
mlreportgen.dom.TableEntry class
12-293
12 Classes – Alphabetical List
12-294
mlreportgen.dom.TableEntry class
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String specifying the width of the border. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
The custom attributes must be supported by the output type of the document to which
this document element is appended.
12-295
12 Classes – Alphabetical List
String specifying the inner margin. String must have the format valueUnits where
Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Array of format objects (such as Bold objects) that specify the format for this table.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
Name of a style specified in the stylesheet of the document or document part to which
this table is appended
The style that specifies the appearance of this table in the output document, for formats
not specified by Style property.
12-296
mlreportgen.dom.TableEntry class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• top
• bottom
• middle
Methods
Use TableEntry.append and TableEntry.clone methods the same way you use
Paragraph.append and Paragraph.clone.
Method Purpose
append Append text, paragraphs, images, tables,
and other elements to this table entry.
clone Clone this table entry.
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.Table |
mlreportgen.dom.TableBody | mlreportgen.dom.TableFooter |
mlreportgen.dom.TableHeader | mlreportgen.dom.TableHeaderEntry |
mlreportgen.dom.TableRow
Related Examples
• “Create and Format Tables”
12-297
12 Classes – Alphabetical List
mlreportgen.dom.TableFooter class
Package: mlreportgen.dom
Description
Specifies the content and format of a formal table footer.
Construction
tableFooterObj = TableFooter() creates an empty table footer.
Output Arguments
tableFooterObj — Table footer
mlreportgen.dom.TableFooter object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
The style the line separating the columns of a table or table section (header, body, footer),
as specified by a mlreportgen.dom.ColSep object.
See the description of the Border property for a description of the possible values.
12-298
mlreportgen.dom.TableFooter class
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String having the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
For example, for a three pica wide column separator, set the ColSepWidth property to
3pi.
12-299
12 Classes – Alphabetical List
The style of a line separating the rows of a table or table section (header, body, or footer).
See the description of the Border property for a description of the possible values.
• The name of a color. See the mlreportGen.dom.Color class reference page for a list
of supported colors.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
The string has the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Array of format objects (such as Bold objects) that specify the format for the table footer.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
Name of a style specified in the stylesheet of the document or document part to which the
table footer is appended
12-300
mlreportgen.dom.TableFooter class
The inner margin is the margin between table cell content and the cell borders.
The string must have the format valueUnits where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Cell array of format objects that specify the format for table entries.
• top
• middle
• bottom
12-301
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Appends a row of table entries to this table
footer.
entry Get a footer entry
row Get a footer row
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.TableBody |
mlreportgen.dom.TableEntry | mlreportgen.dom.TableHeader |
mlreportgen.dom.TableHeaderEntry | mlreportgen.dom.TableRow
Related Examples
• “Create and Format Tables”
12-302
mlreportgen.dom.TableHeader class
mlreportgen.dom.TableHeader class
Package: mlreportgen.dom
Table header
Description
Table header for labeling columns.
Construction
tableHeaderObj = TableHeader() creates an empty table header.
Output Arguments
tableHeaderObj — Table header
mlreportgen.dom.TableHeader object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
The style the line separating the columns of a table or table section (header, body, footer),
as specified by a mlreportgen.dom.ColSep object.
See the description of the Border property for a description of the possible values.
12-303
12 Classes – Alphabetical List
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
String having the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
For example, for a three pica wide column separator, set the ColSepWidth property to
3pi.
The style of a line separating the rows of a table or table section (header, body, or footer).
See the description of the Border property for a description of the possible values.
12-304
mlreportgen.dom.TableHeader class
• The name of a color. See the mlreportGen.dom.Color class reference page for a list
of supported colors.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
The string has the format valueUnits, where Units is an abbreviation for the units in
which the width is expressed. Use one of these abbreviations for the units of a width.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Array of format objects (such as Bold objects) that specify the format for the table
header.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
12-305
12 Classes – Alphabetical List
Name of a style specified in the stylesheet of the document or document part to which the
table header is appended
The style that specifies the appearance of the table header in the output document, for
formats not specified by Style property.
The inner margin is the margin between table cell content and the cell borders.
The string must have the format valueUnits where Units is an abbreviation for the
units in which the width size is expressed. Valid abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Cell array of format objects that specify the format for table entries.
• top
• middle
• bottom
12-306
mlreportgen.dom.TableHeader class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Appends a row of table entries to this table
header.
entry Get a header entry.
row Get a header row.
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.TableBody |
mlreportgen.dom.TableEntry | mlreportgen.dom.TableFooter |
mlreportgen.dom.TableHeaderEntry | mlreportgen.dom.TableRow
Related Examples
• “Create and Format Tables”
12-307
12 Classes – Alphabetical List
mlreportgen.dom.TableHeaderEntry class
Package: mlreportgen.dom
Description
Specifies a table header entry.
Construction
entryObj = TableHeaderEntry() creates an empty table header entry.
Output Arguments
entryObj — Table header entry
mlreportgen.dom.TableHeaderEntry object
Properties
Border — Type of border to draw
string
12-308
mlreportgen.dom.TableHeaderEntry class
12-309
12 Classes – Alphabetical List
• Name of a color. The name must be a CSS color name. See http://www.crockford.com/
wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
12-310
mlreportgen.dom.TableHeaderEntry class
String specifying the width of the border. The string must have the format valueUnits
where Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
The custom attributes must be supported by the output type of the document to which
this document element is appended.
String specifying the inner margin. String must have the format valueUnits where
Units is an abbreviation for the units in which the width size is expressed. Valid
abbreviations are:
12-311
12 Classes – Alphabetical List
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Array of format objects (such as Bold objects) that specify the format for this table.
This property overrides corresponding formats defined by the stylesheet style specified by
the StyleName property.
Name of a style specified in the stylesheet of the document or document part to which
this table is appended
The style that specifies the appearance of this table in the output document, for formats
not specified by Style property.
12-312
mlreportgen.dom.TableHeaderEntry class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• top
• bottom
• middle
Methods
Use TableHeaderEntry.append and TableHeaderEntry.clone methods the same
way you use Paragraph.append and Paragraph.clone.
Method Purpose
append Append text, paragraphs, images, tables,
and other elements to this entry.
clone Clone this table header entry.
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.TableBody |
mlreportgen.dom.TableFooter | mlreportgen.dom.TableHeader |
mlreportgen.dom.TableRow
Related Examples
• “Create and Format Tables”
12-313
12 Classes – Alphabetical List
mlreportgen.dom.TableRow class
Package: mlreportgen.dom
Table row
Description
Creates a table row.
Construction
tableRowObj = TableRow() creates an empty table row.
Output Arguments
tableRowObj — Table row
mlreportgen.dom.TableRow object
Properties
CustomAttributes — Custom attributes for document element
array of mlreportgen.doc.CustomAttribute objects
The custom attributes must be supported by the output type of the document to which
this document element is appended.
12-314
mlreportgen.dom.TableRow class
String having the format valueUnits, where Units is an abbreviation for the units in
which the height is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
Alternatively, you can specify the table row height using the TableRow.Style property.
For example:
TableRow.Style = {RowHeight('.5in')};
Array of format objects (such as Bold objects) that specify the style of the table row.
Name of a style specified in the stylesheet of the HTML document or document part
containing this row. This property is ignored for Word output.
12-315
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append entries to this row.
clone Clone this row.
See Also
mlreportgen.dom.FormalTable | mlreportgen.dom.Table |
mlreportgen.dom.TableBody | mlreportgen.dom.TableEntry |
mlreportgen.dom.TableFooter | mlreportgen.dom.TableHeader
Related Examples
• “Create and Format Tables”
12-316
mlreportgen.dom.Template class
mlreportgen.dom.Template class
Package: mlreportgen.dom
Description
Create a template for a document.
Construction
templateObj = Template() creates an HTML template named Untitleld.htmtx in
the current folder, using the DOM default HTML template.
Input Arguments
templatePath — Path and name for the template
string
12-317
12 Classes – Alphabetical List
If you specify a template using the templatePath input argument, the template must be
consistent with the type argument. You must specify a Word template (.dotx) for docx
output, an HTML template package (.htmtx) for HTML output, and a single-file HTML
template (.html) for html-file output.
The location of the template to copy. The source template used is based on the type of
template specified in the type input argument.
Output Arguments
templateObj — Template for document
mlreportgen.dom.Template object
Properties
Children — Children of this document
cell array of mlreportgen.dom.Element objects
This read-only property lists child elements that the document element contains.
This read-only property is the hole ID of the current hole in this document.
This read-only property is the type (inline or block) of the current template hole.
• An inline hole is for document elements that a paragraph element can contain: Text,
Image, LinkTarget, ExternalLink, InternalLink, CharEntity, AutoNumber.
12-318
mlreportgen.dom.Template class
Set this property to true to overwrite an existing output file of the same name for a
report from this document. If this property is false, or if the existing output file is read-
only, then generating an output file using the same path as an existing output file causes
an error.
Data Types: logical
Path of output file for this document. If you do not specify a file extension, the extension
is based on the output type (for example, .docx for Word).
For unzipped output packaging, the path specifies the folder for the output files. The
default is the current folder.
12-319
12 Classes – Alphabetical List
Specifies how to package the output files generated from this document.
For zipped packaging, the document output is a zip file located at the location specified
by the OutputPath property. The zip file has the extension that matches the document
type: docx (for Word output) or htmx (for HTML output). For example, if the document
type is docx and OutputPath is s:\docs\MyDoc, the output is packaged in a zip file
named s:\docs\MyDoc.docx.
For unzipped packaging, the document output is stored in a folder having the root file
name of the OutputPath property. For example, if the OutputPath is s:\docs\MyDoc,
the output folder is s:\docs\MyDoc.
If you set PackageType to both, generating the report produces zipped and unzipped
output.
Data Types: char
By default, document elements are stored in memory until the document is closed. Set
this property to true to write document elements to disk as the elements are appended
to the document.
Data Types: logical
String that identifies this document. The tag has the form CLASS:ID, where CLASS is the
document class and ID is the value of the Id property of the object.
An example of a reason for specifying your own tag value is to make it easier to identify
where an issue occurred during document generation.
The full path to the HTML or Word template to use for this document element.
12-320
mlreportgen.dom.Template class
For HTML documents, this property specifies the text for the title bar of the browser.
Word documents ignore this property.
• 'html'— HTML output HTML output as a zipped or unzipped folder containing the
HTML document text, image, style sheet, and JavaScript files
• 'docx'— Word output
• 'html-file'— HTML output consisting of a single file that contains the text, style
sheets, JavaScript®, and images for the report
If you specify a template using the TemplatePath property, the template must be
consistent with the type argument. You must specify a Word template (.dotx) for docx
output, an HTML template package (.htmtx) for HTML output, and a single-file HTML
template (.html) for html-file output.
Methods
Use the Template methods the same way you use the corresponding Document methods.
Method Purpose
append Append document element to the
document.
close Close this document.
createTemplate Create default template.
fill Fill document hole.
getCoreProperties Get core properties of document.
getImageDirectory Get image directory for the document.
12-321
12 Classes – Alphabetical List
Method Purpose
getImagePrefix Get generated image name prefix for the
document.
getMainPartPath Get relative path of main part of output
document.
getOPCMainPart Get full path of main part of output
document.
moveToNextHole Move to next template hole.
open Open this document.
package Append file to OPC package of document.
setCoreProperties Set core properties of document element.
Examples
Create a Template and Use it in a Report
import mlreportgen.dom.*;
t = Template('mytemplate');
p = Paragraph('My Company');
p.FontSize = '24';
p.Color = 'DeepSkyBlue';
p.Bold = true;
p.HAlign = 'center';
append(t,p);
p = Paragraph;
p.FontFamilyName = 'Arial';
p.FontSize = '18pt';
p.Bold = true;
p.HAlign = 'center';
append(p,TemplateHole('ReportTitle','Report Title'));
append(t,p);
close(t);
rptview('mytemplate.htmtx');
12-322
mlreportgen.dom.Template class
See Also
mlreportgen.dom.Document.createTemplate |
mlreportgen.dom.TemplateHole | rptview
12-323
12 Classes – Alphabetical List
mlreportgen.dom.TemplateHole class
Package: mlreportgen.dom
Description
Hole to append to a document template.
• Paragraph
• TableEntry
• Group
• Template
Construction
templateHoleObj = TemplateHole() creates a hole with empty properties.
Input Arguments
id — ID for template hole
string
Description for the template hole, specified as a string. The value of this argument
becomes the content of the hole in the template to which it is assigned to allow you to
12-324
mlreportgen.dom.TemplateHole class
determine the purpose of the hole when viewing the template in Microsoft Word (for
Word templates) or in a Web browser (for HTML templates). The description is replaced
by appended hole content in a report generated from the template.
Output Arguments
templateHoleObj — Hole to append to template
mlreportgen.dom.TemplateHole object
Properties
DefaultHoleStyleName — Name of default style for hole content
string
Name of default style for hole content. This style name is assigned to hole content that
does not specify a style name. For example, suppose you append a Text object to this
hole and the Text object does not specify a style name. Then the value of this property
is assigned to the text object as its style name. This property allows a template to specify
the appearance of appended content.
Description for the template hole, specified as a string. The value of this property
becomes the content of the hole in the template to which it is assigned to allow you to
determine the purpose of the hole when viewing the template in Microsoft Word (for
Word templates) or in a Web browser (for HTML templates). The description is replaced
by appended hole content in a report generated from the template.
12-325
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
clone Clone this hole object.
See Also
mlreportgen.dom.Document.createTemplate | mlreportgen.dom.Template |
rptview
Related Examples
• “Create a Microsoft Word Template”
• “Create an HTML Template”
• “Use Style Sheets”
12-326
mlreportgen.dom.Text class
mlreportgen.dom.Text class
Package: mlreportgen.dom
Text object
Description
Text string to include in a document element
Construction
textObj = Text() creates an empty text object.
textObj = Text(text) creates a text object containing the specified text string.
Input Arguments
text — Text string
array of chars
The style specified by styleName must be defined in the template used to create the
document to which this text is appended.
Data Types: char
12-327
12 Classes – Alphabetical List
Output Arguments
textObj — Text string
mlreportgen.dom.Text object
Properties
BackgroundColor — Background color
string
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
To make text bold, set this property to true or 1. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the weight
of the text is determined by that style. Setting the Bold property adds a corresponding
mlreportGen.dom.Bold format object to the Style property of this document element.
Removing the Bold property setting removes the object.
Data Types: logical
• The name of a color. The name must be a CSS color name. See http://
www.crockford.com/wrrrld/color.html.
• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade
of blue.
12-328
mlreportgen.dom.Text class
HTML or Microsoft Word must support the custom attributes of this document element.
To specify substitutions for this font, do not set this property. Instead create and add a
mlreportgen.dom.FontFamily object to the Style property of this document element.
If you need to specify substitutions for this font, do not set this property. Instead
create and add a mlreportgen.dom.FontFamily object to the Style property of this
document element.
String having the format valueUnits, where Units is an abbreviation for the units in
which the font size is expressed. Use one of these abbreviations for the units for the font
size.
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
12-329
12 Classes – Alphabetical List
• pi — picas
• pt — points
• px — pixels
To use italics for text, set this property to true. If this property is empty and the
StyleName property for this document element specifies a style sheet style, the slant of
the text is determined by that style. Setting the Italic property adds a corresponding
mlreportGen.dom.Italic format object to the Style property of this document
element. Removing the Italic property setting removes the object.
Data Types: logical
The default for this property is []. You can set it to one of these values:
12-330
mlreportgen.dom.Text class
The style specified by styleName must be defined in the template used to create the
document element to which this text is appended.
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-331
12 Classes – Alphabetical List
If this property is empty and StyleName property of this document element specifies a
style sheet style, the type of underline is determined by that style.
To specify the color as well as the type of the underline, do not set the Underline
property. Instead, set the Style property of this document element to include an
mlreportgen.dom.Underline format object that specifies the desired underline type
and color.
To specify how to handle white space, use one of the following strings.
12-332
mlreportgen.dom.Text class
If you want to view HTML output in the MATLAB browser and you want to preserve
white space and wrap text only on line breaks, use the preserve setting rather than the
pre setting.
Methods
Use the Text.append and Text.clone methods the same way you use the
Paragraph.append and Paragraph.clone methods.
Method Purpose
append Append a custom element to this text
object.
clone Clone this text object
See Also
mlreportgen.dom.CharEntity | mlreportgen.dom.CustomText |
mlreportgen.dom.Paragraph
Related Examples
• “Add Content to a Report”
12-333
12 Classes – Alphabetical List
More About
• “Report Formatting Approaches”
12-334
mlreportgen.dom.Underline class
mlreportgen.dom.Underline class
Package: mlreportgen.dom
Description
Draw line under text
Construction
underline = Underline() draws a single line under text.
underline = Underline(type) draws a line of the specified type under the text.
Input Arguments
type — Style of underline
string
Applies To
String Description
DOCX HTML
'single' Single underline X X
'double' Double underline X
'words' Words only underlined (not spaces) X
'thick' Thick underline X
'dotted' Dotted underline X
'dottedHeavy' Thick, dotted underline X
12-335
12 Classes – Alphabetical List
Applies To
String Description
DOCX HTML
'dashed' Dashed underline X
'dashedHeavy' Thick, dashed underline X
'dashLong' Long, dashed underline X
'dashLongHeavy' Thick, long, dashed underline X
'dotDash' Dot dash underline X
'dotDotDash' Dash dot dot underline X
'dashDotDotHeavy' Thick dash dot dot underline X
'dashDotHeavy' Thick dash dot underline X
'none' No underline X
'wave' Wavy underline X
'wavyDouble' Two wavy underlines X
'wavyHeavy' Thick wavy underline X
Output Arguments
underline — Line under text
mlreportgen.dom.Underline object
Properties
Type — Underline style
string
Underline style. See the description of the type input argument for the constructor.
12-336
mlreportgen.dom.Underline class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.Text
More About
• “Report Formatting Approaches”
12-337
12 Classes – Alphabetical List
mlreportgen.dom.UnorderedList class
Package: mlreportgen.dom
Description
Specifies an unordered (bulleted) list.
Construction
unorderedListObj = UnorderedList() creates an empty unordered list.
Input Arguments
items — Content to include in each item in unordered list
cell array of strings
A one-dimensional cell array containing a string for each item in the unordered list.
• A string
• A number
• A Boolean value
• One of the following DOM objects:
• mlreportgen.dom.Text
• mlreportgen.dom.Paragraph
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.InternalLink
12-338
mlreportgen.dom.UnorderedList class
• mlreportgen.dom.Table
• mlreportgen.dom.Image
• mlreportgen.dom.CustomElement
• Horizontal one-dimensional array (for a sublist)
To append an ordered list, use an OrderedList DOM object instead of using the
listItems argument.
Output Arguments
unorderedListObj — Content to include in each item in the unordered list
mlreportgen.dom.UnorderedList object
Properties
CustomAttributes — Custom attributes of document element
array of mlreportgen.dom.CustomAttribute objects
HTML or Microsoft Word must support the custom attributes of this document element.
12-339
12 Classes – Alphabetical List
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Method Purpose
append Append items to this list.
Examples
Create an Unordered List
import mlreportgen.dom.*;
d = Document('mydoc');
ul = UnorderedList({Text('a'),'b',1,{'c',Paragraph('d')}});
append(d,ul);
close(d):
rptview('mydoc','html');
12-340
mlreportgen.dom.UnorderedList class
See Also
mlreportgen.dom.ListItem | mlreportgen.dom.OrderedList
12-341
12 Classes – Alphabetical List
mlreportgen.dom.VAlign class
Package: mlreportgen.dom
Description
Specifies vertical alignment of objects.
Construction
vAlignObj = VAlign() creates an alignment object having the value 'top'.
Input Arguments
value — Specify vertical alignment
'top' (default) | 'bottom' | 'middle'
Output Arguments
vAlignObj — Vertical alignment of document object
mlreportgen.dom.VAlign object
Properties
Id — ID for document element
string
12-342
mlreportgen.dom.VAlign class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
See Also
mlreportgen.dom.HAlign
More About
• “Report Formatting Approaches”
12-343
12 Classes – Alphabetical List
mlreportgen.dom.VerticalAlign class
Package: mlreportgen.dom
Description
Specifies vertical alignment of text.
Construction
verticalAlignObj = VerticalAlign() creates a superscript alignment.
Input Arguments
align — Vertical alignment of text relative to baseline
'superscript' (default) | 'subscript' | 'baseline'
Output Arguments
verticalAlignObj — Vertical alignment of text
mlreportgen.dom.VerticalAlignment object
Properties
Id — ID for document element
string
12-344
mlreportgen.dom.VerticalAlign class
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Examples
Use a Superscript
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('e = mc');
t = Text('2');
t.Style = {VerticalAlign('superscript')};
append(p,t);
append(d,p);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.Text
12-345
12 Classes – Alphabetical List
More About
• “Report Formatting Approaches”
12-346
mlreportgen.dom.WarningMessage class
mlreportgen.dom.WarningMessage class
Package: mlreportgen.dom
Warning message
Description
Create a warning message with the specified text originating from the specified source
object.
Construction
warningMsgObj = WarningMessage(text,source) creates a warning message with
the specified text originating from the specified source object.
Input Arguments
text — Message text
string
Output Arguments
warningMsgObj — Warning message
mlreportgen.dom.WarningMessage object
12-347
12 Classes – Alphabetical List
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Methods
Use WarningMessage methods similar to how you use ProgressMessage methods.
Method Purpose
formatAsHTML Wrap message in HTML tags.
formatAsText Format message as text.
passesFilter Determine if message passes filter.
12-348
mlreportgen.dom.WarningMessage class
Examples
Create a Warning Message
import mlreportgen.dom.*;
d = Document('test','html');
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher,WarningMessage('invalid chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = {CounterInc('chapter'),...
CounterReset('table'),WhiteSpace('pre')};
append(p,AutoNumber('chapter'));
append(d,p);
close(d);
rptview('test','html');
delete(l);
See Also
mlreportgen.dom.MessageDispatcher.dispatch
12-349
12 Classes – Alphabetical List
mlreportgen.dom.WhiteSpace class
Package: mlreportgen.dom
Description
Preserves white space and line breaks in text.
Construction
ws = WhiteSpace() collapses white space.
Input Arguments
option — White space type
string
String Description
'preserve' Preserves white space and line breaks.
This is default.
'nowrap' Sequences of white spaces collapse into a single white space.
Text does not wrap to the next line. The text continues on the
same line until a <br /> tag is encountered.
12-350
mlreportgen.dom.WhiteSpace class
String Description
'pre' White space is preserved by the browser. Text wraps only on
line breaks. Acts like the <pre> tag in HTML.
'pre-line' Sequences of white spaces collapses into a single white space.
Text wraps when necessary and on line breaks.
'pre-wrap' White space is preserved by the browser. Text wraps when
necessary and on line breaks.
Output Arguments
ws — White space type
mlreportgen.dom.WhiteSpace object
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
12-351
12 Classes – Alphabetical List
String Description
'preserve' Preserves white space and line breaks.
This is default.
'nowrap' Sequences of white spaces collapse into a single white space.
Text does not wrap to the next line. The text continues on the
same line until a <br /> tag is encountered.
'pre' White space is preserved by the browser. Text wraps only on
line breaks. Acts like the <pre> tag in HTML.
'pre-line' Sequences of white spaces collapses into a single white space.
Text wraps when necessary and on line breaks.
'pre-wrap' White space is preserved by the browser. Text wraps when
necessary and on line breaks.
Examples
Include White Space Between Titles
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
p = Paragraph('Chapter ');
p.Style = { CounterInc('chapter'),WhiteSpace('preserve') };
append(p, AutoNumber('chapter'));
append(d, p);
p = Paragraph('Chapter ');
p.Style = { CounterInc('chapter'),WhiteSpace('preserve') };
append(p,AutoNumber('chapter'));
append(d,p);
12-352
mlreportgen.dom.WhiteSpace class
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.Text
More About
• “Report Formatting Approaches”
12-353
12 Classes – Alphabetical List
mlreportgen.dom.WidowOrphanControl class
Package: mlreportgen.dom
Description
Specifies whether to prevent widows and orphans. This format applies only to Microsoft
Word documents.
Construction
widowOrphanControlObj = WidowOrphanControl() prevents a page break after the
first line of a paragraph (orphan) or before the last line of a paragraph (widow).
Input Arguments
tf — Controls orphans and widows
true (default) | false | 1 | 0
A setting of true (or 1) prevents a page break after the first line of a paragraph (orphan)
or before the last line of a paragraph (widow). A setting of false (or 0) allows a page
break after the first line of a paragraph (orphan) or before the last line of a paragraph
(widow).
Data Types: logical
Output Arguments
widowOrphanControlObj — Widow and orphan handling
mlreportgen.dom.WidowOrphanControl object
12-354
mlreportgen.dom.WidowOrphanControl class
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
• true or 1 — Prevents a page break after the first line of a paragraph (orphan) or
before the last line of a paragraph (widow).
• false or 0 — Allows a page break after the first line of a paragraph (orphan) or
before the last line of a paragraph (widow).
See Also
mlreportgen.dom.Paragraph
More About
• “Report Formatting Approaches”
12-355
12 Classes – Alphabetical List
mlreportgen.dom.Width class
Package: mlreportgen.dom
Object width
Description
Specifies the width of an object, such as an image or a table cell.
Construction
widthObj = Width() creates a format object that specifies a width of 1 inch.
Input Arguments
value — Width of object
string
Width of object, such as an image or a table cell, specified as a string. The string having
the format valueUnits, where Units is an abbreviation for the units in which the width
is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
• pt — points
• px — pixels
• % — percent
12-356
mlreportgen.dom.Width class
Output Arguments
widthObj — Object width
mlreportgen.dom.Width object
Properties
Id — ID for document element
string
Specify your own tag value, for example, to make it easier to identify where an issue
occurred during document generation.
Width of object, such as an image or a table cell, specified as a string. The string having
the format valueUnits, where Units is an abbreviation for the units in which the width
is expressed. The following abbreviations are valid:
• no abbreviation — pixels
• cm — centimeters
• in — inches
• mm — millimeters
• pi — picas
12-357
12 Classes – Alphabetical List
• pt — points
• px — pixels
• % — percent
Examples
Set Width and Other Formats for a Table
import mlreportgen.dom.*;
doctype = 'html';
d = Document('test',doctype);
t = Table(magic(5));
t.Style = {Border('inset','crimson','6pt'),...
Width('50%')};
t.TableEntriesInnerMargin = '6pt';
t.TableEntriesHAlign = 'center';
t.TableEntriesVAlign = 'middle';
append(d,t);
close(d);
rptview('test',doctype);
See Also
mlreportgen.dom.Height | mlreportgen.dom.Image | mlreportgen.dom.Table
More About
• “Report Formatting Approaches”
12-358
13
13-2
Create a Report Program
To get started learning about creating reports with the DOM API, see “Document Object
Model” on page 13-4.
More About
• “Document Object Model” on page 13-4
13-3
13 Create a Report Program
The DOM API's document object model consists of a hierarchical set of data structures,
known as objects, that represent the document and its contents. At the top of the
hierarchy is an object representing the document itself. The document object maintains a
list of objects, called its children, that represent its contents (such as paragraphs, images,
tables, lists, and so on). Each child object, in turn, maintains a list of its contents. For
example, a table lists its rows, a row lists its table entries, a table entry lists its contents,
and so on.
The DOM API contains functions that allow you to create and assemble DOM objects,
such as paragraphs, images, and tables, into a model of a specific document. You can
then use the API to write the model out to disk as an HTML or Microsoft Word document
file.
To get help for a specific object, such as a Paragraph, use a help command such as this.
help mlreportgen.dom.Paragraph
To get a complete list of DOM API classes and functions in the MATLAB Report
Generator documentation, open the Functions pane.
doc mlreportgen.dom.Paragraph
Related Examples
• “Construct a DOM Object” on page 13-6
• “Get and Set DOM Object Properties” on page 13-8
13-4
Document Object Model
13-5
13 Create a Report Program
The name of an object constructor is the name of the MATLAB class from which the
DOM creates an object. For example, the name of the constructor for a DOM paragraph
object is mlreportgen.dom.Paragraph. Some constructors do not require any
arguments. Other constructors can take one or more arguments that typically specify its
initial content and properties. For example, the following line creates a paragraph whose
initial content is Chapter 1.
p = mlreportgen.dom.Paragraph('Chapter 1.');
A constructor returns a handle to the object it creates. Assigning the handle to a variable
allows you to subsequently append content to the object or set its properties. For
example, the following line appends content to the paragraph object p created in the
previous example.
append(p,'In the Beginning');
Note that you can assign an object handle to multiple variables and hence access the
same object via multiple variables.
Related Examples
• “Import the DOM API Package” on page 13-7
• “Get and Set DOM Object Properties” on page 13-8
More About
• “Document Object Model” on page 13-4
13-6
Import the DOM API Package
The documentation frequently refers to DOM API objects and functions without the
mlreportgen.dom prefix, assuming that you have already imported the DOM API
package.
Related Examples
• “Create a Report Program” on page 13-3
More About
• “Document Object Model” on page 13-4
13-7
13 Create a Report Program
saveFont = p.FontFamily;
p.FontFamily = 'Arial';
Related Examples
• “Construct a DOM Object” on page 13-6
• “Use Format Properties” on page 13-24
More About
• “Document Object Model” on page 13-4
13-8
Create a Document Object to Hold Content
If you use the constructor with no arguments, the DOM API creates an HTML document
named Untitled.htmx in the current folder.
You can specify the file system path of the report as the first argument of the constructor.
You can specify the type of report to be generated by using a second argument. You can
specify the type to be 'html' or 'docx' (for Microsoft Word). You can then use the
rptview function to convert a Word report to PDF, or you can open the report in Word
and save it as PDF.
Using a third argument, you can specify the file system path of a Word or HTML
template to be used as a basis for creating the report. You need to specify a template
only if you are using template-based formatting (using style sheets) or form-based report
generation. If you specify a template, it must be a Word template (.dotx) for Word
reports or an HTML template (.htmtx) for HTML reports. For example, this Document
constructor creates a Word report using the Word template myWordTemplate.dotx.
d = Document('myreport','docx','myWordTemplate');
See Also
Functions
rptview
Classes
mlreportgen.dom.Document
Related Examples
• “Create a Report Program” on page 13-3
• “Use Style Sheets” on page 13-21
13-9
13 Create a Report Program
More About
• “Form-Based Reporting” on page 13-28
• “Document Object Model” on page 13-4
13-10
Add Content to a Report
The append function throws an error if the second argument (the content to be
appended), is incompatible with the first argument (the object to which the content is to
be appended). For example, the append method in the following script throws an error.
% This code throws an error
image = Image('membrane.png');
append(image,Paragraph('Hello World'));
This is because you cannot add a paragraph to an image. The reference documentation
for classes lists the types of objects that you can append to instances of the classes. To
get a complete list of DOM API classes and functions in the MATLAB Report Generator
documentation, open the Functions pane. To see the documentation reference page for
an object, search in documentation or in MATLAB use a doc command such as this.
doc mlreportgen.dom.Paragraph
As shown in the preceding examples, the append method, depending on the target object
type, allows you to append strings, doubles, arrays, and other basic MATLAB data types,
without first converting the data to DOM objects. The function converts the appended
data to a DOM object before appending it to the target object. For example, the following
script appends a two-dimensional array of strings to a document as a table.
d = Document('MyDoc');
tableArray = {'a','b';'c','d'};
append(d,tableArray);
Many constructors also allow you to specify basic MATLAB data types as the initial
content of the object when you construct the object. This example is equivalent to the
preceding example.
d = Document('MyDoc');
tableArray = {'a','b';'c','d'};
13-11
13 Create a Report Program
append(d,Table(tableArray));
See Also
Functions
mlreportgen.dom.Paragraph.append
Related Examples
• “Construct a DOM Object” on page 13-6
• “Clone a DOM Object” on page 13-13
• “Add Content as a Group” on page 13-14
• “Stream a Report” on page 13-16
More About
• “Document Object Model” on page 13-4
13-12
Clone a DOM Object
d = Document('MyDoc');
text = append(d,'Hello World');
text.Color = 'magenta';
text = clone(text);
text.Color = 'cyan';
append(d,text);
See Also
Functions
mlreportgen.dom.Paragraph.clone
Related Examples
• “Add Content to a Report” on page 13-11
• “Construct a DOM Object” on page 13-6
More About
• “Document Object Model” on page 13-4
13-13
13 Create a Report Program
This example shows the key code to include. After describing the steps involved in using
a group, this example includes code for a complete report that uses a group.
1 Define the DOM objects that you want to include repeatedly in a report.
disclaimer = Group();
append(disclaimer,disclaimerHead);
append(disclaimer,disclaimerIntro);
append(disclaimer,disclaimerList);
3 Append the Group object in the place in the report where you want to repeat the
content. For example, if the document object is doc:
append(doc,disclaimer);
import mlreportgen.dom.*;
doc = Document('groupReport','html');
disclaimerHead = Heading(2,'Results May Vary');
disclaimerIntro = Paragraph('The following results assume:');
disclaimerList = UnorderedList(...
{'Temperature between 30 and 70 degrees F',...
'Wind less than 20 MPH','Dry road conditions'});
disclaimer = Group();
append(disclaimer,disclaimerHead);
append(disclaimer,disclaimerIntro);
append(disclaimer,disclaimerList);
append(doc,disclaimer);
p1 = Paragraph('First set of results...');
p1.Bold = true;
p2 = Paragraph('more report content...');
13-14
Add Content as a Group
p2.Bold = true;
append(doc,p1);
append(doc,p2);
append(doc,disclaimer);
close(doc);
rptview('groupReport','html');
See Also
Functions
mlreportgen.dom.Paragraph.append
Classes
mlreportgen.dom.Group
Related Examples
• “Add Content to a Report” on page 13-11
13-15
13 Create a Report Program
Stream a Report
The DOM API supports two modes of appending content to a document:
To enable streaming mode, set the StreamOutput property of the Document object for
the report to true.
d = Document('MyDoc');
d.StreamOutput = true;
See Also
Classes
mlreportgen.dom.Document
Related Examples
• “Add Content to a Report” on page 13-11
13-16
Report Packages
Report Packages
A Microsoft Word document packages all of its contents, text, images, style sheets, and so
on, in a single compressed file having a docx extension.
For HTML documents, the DOM API defines an analogous packaging scheme, with an
htmtx compressed file extension. By default, the DOM API generates HTML reports
as htmx files. To generate an HTML report in unzipped format or both zipped and
unzipped format, set the PackageType property of the Document object for a report to
'unzipped' or 'both', respectively.
See Also
Functions
unzipTemplate | zipTemplate
Classes
mlreportgen.dom.Document
More About
• “Document Object Model” on page 13-4
13-17
13 Create a Report Program
Close a Report
The last step in creating a report with the DOM API is to close the report. Closing a
report writes out any content that remains in memory and closes the report file. Use the
close function.
d = Document('MyDoc');
append(d,'Hello World');
close(d);
See Also
Functions
mlreportgen.dom.Document.close
Related Examples
• “Create a Report Program” on page 13-3
More About
• “Document Object Model” on page 13-4
13-18
Display a Report
Display a Report
The DOM API rptview function allows you to display a generated report in a viewer
appropriate to its document type: the Microsoft Word editor for Word documents, an
HTML browser for HTML reports, and Adobe Acrobat for PDF reports.
If you omit the second argument (the output type), rptview uses the output type from
the report’s extension.
If an HTML report is in zipped format, rptview creates a copy of the report in your
temporary directory and displays the temporary copy. If you specify 'pdf', the function
uses Word to convert the report to PDF format. It then displays the report in Adobe
Acrobat.
See Also
Functions
rptview
Related Examples
• “Create a Report Program” on page 13-3
13-19
13 Create a Report Program
p.Color = 'red'
Related Examples
• “Use Style Sheets” on page 13-21
• “Use Format Objects” on page 13-23
• “Use Format Properties” on page 13-24
More About
• “Format Inheritance” on page 13-25
13-20
Use Style Sheets
DOM API objects that have a StyleName property allow you to leverage Word and
HTML style sheets to format reports as follows.
1 Create a Word or HTML template, using the DOM API or a Word or HTML editor,
depending on the report type.
2 Optionally, you can change a template style definition or add a new style. For
details, see “Modify Styles in a Microsoft Word Template” on page 13-117 or
“Modify Styles in an HTML Template” on page 13-127.
3 In a DOM report, create a Document object that uses the template.
4 Assign the names of styles defined in the style sheet to the StyleName property of
objects that you want to have the specified style.
For example, the following script assigns a style named Warning to a paragraph object.
It assumes that you have defined the Warning style previously in a Word template
named MyTemplate.dotx.
d = Document('MyDoc','docx','MyTemplate');
p = Paragraph('Danger');
p.StyleName = 'Warning';
append(d,p);
close(d);
Assigning the Warning style to the DOM paragraph object causes Word to use the
Warning style to render the generated paragraph when you open the generated report.
Tip Some document object constructors allow you to specify the value of the StyleName
property as an argument. For example, this paragraph has the text Danger and uses a
style defined for the template style named Warning.
p = Paragraph('Danger','Warning');
13-21
13 Create a Report Program
Related Examples
• “Create a Microsoft Word Template” on page 13-111
• “Modify Styles in a Microsoft Word Template” on page 13-117
• “Create an HTML Template” on page 13-122
• “Modify Styles in an HTML Template” on page 13-127
More About
• “Report Formatting Approaches” on page 13-20
• “Format Inheritance” on page 13-25
13-22
Use Format Objects
You can assign the same array of format objects to more than one DOM document object.
This allows you to create a programmatic equivalent of a template style sheet. For
example:
warning = {Color('red'), FontFamily('Arial'), FontSize('18pt')};
p = Paragraph('Danger!');
p.Style = warning;
p = Paragraph('Caution!');
p.Style = warning;
The DOM API allows you to assign any format object to any document object, regardless
of whether the format applies. If the format does not apply, it is ignored.
More About
• “Report Formatting Approaches” on page 13-20
• “Format Inheritance” on page 13-25
13-23
13 Create a Report Program
p = Paragraph('Danger!');
p.Color = 'red';
p.FontFamily = 'Arial';
p.FontSize = '18pt';
Assigning a value to a format property causes the API to create an equivalent format
object and assign it to the Style property of the document object. Similarly, assigning
a format object to an object's Style property causes the API to assign an equivalent
value to the corresponding format property if it exists. In this way, the API keeps format
properties for an object in sync with the Style property of the object.
Note: When you change the value of a format property, the DOM API:
In this way, the DOM prevents changing a format property in one object from changing a
style originally assigned to other objects as well.
More About
• “Report Formatting Approaches” on page 13-20
• “Format Inheritance” on page 13-25
13-24
Format Inheritance
Format Inheritance
The DOM API allows you to use both template-based styles and format object-based
styles (or equivalent format properties) to specify the appearance of an object. If you
set both the StyleName and the Style property of an object, the formats in the Style
property override corresponding formats specified by the template-based style of the
StyleName property. Consider, for example, the following script.
d = Document('MyDoc','docx','MyTemplate');
p = Paragraph('Danger!');
p.StyleName = 'Warning';
p.Style = {Color('red')};
append(d,p);
close(d);
Suppose that the Warning style defines the color of a warning as yellow. In that case,
this example overrides the color specified by the Warning style.
d = Document('MyDoc');
tableArray = {'a', 'b'; 'c', 'd'};
table = append(d, tableArray);
table.Style = {Color('blue')};
append(d, table);
close(d);
Related Examples
• “Use Style Sheets” on page 13-21
• “Use Format Objects” on page 13-23
More About
• “Report Formatting Approaches” on page 13-20
13-25
13 Create a Report Program
In HTML output, a Container object generates an HTML element of the type specified
by its HTMLTag property and containing HTML elements corresponding to its DOM
contents. For example, a Container object with the HTMLTag property div and that
contains the text Hello World generates this markup:
<div><p><span>Hello World</span></p></div>
The generated HTML container element has the class and style properties specified
by the Container object StyleName and Style properties, respectively. The rules
of HTML CSS (cascading style sheets) format inheritance assure that the generated
children of the Container object inherit the formats specified by the Container object
Style and StyleName properties. For example, if the Container object specifies red as
its text color and none of its text children specify a color, the text children are colored red.
For Microsoft Word report output, a Container object simulates container format
inheritance, applying the formats specified by the Container object Style attribute
to each child, unless overridden by the child, and then appending the child to the
Word output. The Word output ignores the HTMLTag and StyleName properties of the
Container object.
• Use a container object to apply format inheritance to a set of objects and to create
HTML container elements not otherwise supported by the DOM, such as div, section,
and article.
• Use a group object to append the same content in multiple places in a document
without cloning the group.
See Also
Classes
mlreportgen.dom.Container | mlreportgen.dom.Group
13-26
Create Object Containers
Related Examples
• “Use Style Sheets” on page 13-21
• “Use Format Objects” on page 13-23
More About
• “Report Formatting Approaches” on page 13-20
13-27
13 Create a Report Program
Form-Based Reporting
The DOM API supports a form-based approach to report generation. You can use
Microsoft Word or an HTML editor to create a template that defines the fixed content
of the form, interspersed with holes (blanks), that your DOM report program fills with
generated content.
Related Examples
• “Fill the Blanks in a Report Form” on page 13-29
• “Use Subforms in a Report” on page 13-31
• “Create a Microsoft Word Template” on page 13-111
• “Add Holes in a Microsoft Word Template” on page 13-112
• “Create an HTML Template” on page 13-122
• “Add Holes in an HTML Template” on page 13-124
13-28
Fill the Blanks in a Report Form
For example, this function generates a report from a Word template that has three holes
named Title, Author, and Content. The arguments title, author, and content, are
assumed to be strings.
function makerpt(title,author,content,rptname,rpttemplate)
import mlreportgen.dom.*
rpt = Document(rptname,'docx',rpttemplate);
while ~strcmp(rpt.CurrentHoleId,'#end#')
switch rpt.CurrentHoleId
case 'Title'
append(rpt,title);
case 'Author'
append(rpt,author);
case 'Content'
append(rpt,content);
end
moveToNextHole(rpt);
end
close(rpt);
See Also
Functions
mlreportgen.dom.Document.moveToNextHole
13-29
13 Create a Report Program
Related Examples
• “Use Subforms in a Report” on page 13-31
• “Create a Microsoft Word Template” on page 13-111
• “Add Holes in a Microsoft Word Template” on page 13-112
• “Create an HTML Template” on page 13-122
• “Add Holes in an HTML Template” on page 13-124
More About
• “Form-Based Reporting” on page 13-28
13-30
Use Subforms in a Report
For an example of a report that uses subforms, open the Functional Report example.
Tip The DOM API allows you to store the templates for document parts in the main
template for a report. This allows you to use a single template file to supply all the
templates required for a report. For details, see “Create Document Part Template
Libraries” on page 13-33.
See Also
Functions
mlreportgen.dom.Document.moveToNextHole
Classes
mlreportgen.dom.DocumentPart
Related Examples
• “Fill the Blanks in a Report Form” on page 13-29
• “Create a Microsoft Word Template” on page 13-111
• “Add Holes in a Microsoft Word Template” on page 13-112
• “Create an HTML Template” on page 13-122
• “Add Holes in an HTML Template” on page 13-124
13-31
13 Create a Report Program
More About
• “Form-Based Reporting” on page 13-28
13-32
Create Document Part Template Libraries
In this section...
“Create a Document Part Template Library in a Microsoft Word Template File” on page
13-33
“Create a Document Part Template Library in an HTML Template File” on page
13-35
A document part template library is a set of document part templates stored by name in
another template. You can create a document part based on a template stored in a library
by specifying the name of the template in the document part constructor. Document part
template libraries allow you to store all the templates for a report in a single template
file, for example, the main template file of a report.
1 Open the Word template in which you want to create the document part template.
2 In the template, create the Word content to serve as a prototype for the document
part template. (You will delete the prototype after copying it to the parent template
Quick Part Gallery.) The document part template content that you create can
contain holes and page layout sections, as well as other types of Word content. For
example:
13-33
13 Create a Report Program
6 In the Create New Building Block dialog box, in the Name field, enter a unique
name for the template. Use this name in the constructor of a DocumentPart object
to be based on this quick part.
7 For the first document part template you create in the template file, in the
Category list, click Create New Category. Create a category named
mlreportgen. Then select mlreportgen from the Category list.
13-34
Create Document Part Template Libraries
You can modify a document part template located in a Quick Part Gallery.
1 Open the Word template that contains the document part template.
2 Click in the template where you want to create an instance of the document part
template.
3 In the Word ribbon, select the Insert tab.
4
On the Insert ribbon, click the Explore Quick Parts button to display the
Quick Part Gallery.
5 To create an instance of the template in the parent template file, in the Quick Part
Gallery, select the document part template to modify.
6 Edit the instance.
7 Select and save the modified instance to the Quick Part Gallery using the same
name as the original template.
8 Delete the instance from the parent template file.
9 Save the parent template file.
13-35
13 Create a Report Program
API. You can modify these templates and add your own templates by editing this file,
using the markup conventions.
You can also create a template part library file in an HTML template that you create
from scratch. In this case, you must ensure that the file observes the HTML markup
conventions that the DOM API uses to indicate the name and content of a document
part template in a document part library. To ensure this, copy the default template part
library file into the template you create from scratch.
1 Unzip the template package containing the part template library file.
2 Open the file, named docpart_templates.html by default, in an HTML or text
editor.
3 Create the following HTML markup in the <body> element of the file.
<div class="Template">
<div class="TemplateName">
<span class="TemplateName">TEMPLATE_NAME</span>
</div>
<div class="TemplateBody">
TEMPLATE_BODY
</div>
</div>
4 Replace TEMPLATE_NAME with a unique name for the template. Use this name in the
constructor of a DOM DocumentPart object to be based on this template.
5 Replace TEMPLATE_BODY with HTML markup that defines the fixed content and
holes of the template.
6 Save the library file.
7 Repackage the template.
See Also
Classes
mlreportgen.dom.DocumentPart
Related Examples
• “Fill the Blanks in a Report Form” on page 13-29
13-36
Create Document Part Template Libraries
More About
• “Form-Based Reporting” on page 13-28
13-37
13 Create a Report Program
Note: This section assumes that you are familiar with object-oriented programming in
MATLAB. For information on object-oriented programming in MATLAB, see “Object-
Oriented Programming” in the MATLAB documentation.
The DOM API supports an object-oriented approach to creating report programs. With
this approach, you subclass the DOM Document and DocumentPart classes to create
document and document part classes tailored to your report application. You then create
instances of these classes to generate a report.
Related Examples
• “Simplify Filling in Forms” on page 13-39
13-38
Simplify Filling in Forms
The HoleID part of the signature is the ID of a hole defined by the document or
document part template. The obj argument is an instance of the derived class. For
example, supposed that a template defines a hole named Author. Then the derived class
would define a method name fillAuthor to fill the Author hole. Assuming that the
derived class defines methods for filling the holes, the fill method moves from the first
hole in the document or part to the last, invoking the corresponding fillHoleId method
to fill each hole.
The fill method eliminates the need for a report program to loop explicitly through
the holes in a document or document part's template. The report need only invoke the
document or part fill method. For example, suppose that you have derived a report
class, name MyReport, from the mlreportgen.dom.Document class and that this
derived class defines methods for each of the holes defined by the report template, based
on data supplied in its constructor. Then, you would need only three lines to generate an
instance of MyReport:
function makeReport(rptdata)
rpt = MyReport(rptdata);
fill(rpt);
close(rpt);
See Also
Functions
mlreportgen.dom.Document.moveToNextHole
Classes
mlreportgen.dom.DocumentPart
13-39
13 Create a Report Program
Related Examples
• “Use Subforms in a Report” on page 13-31
• “Fill the Blanks in a Report Form” on page 13-29
• “Create a Microsoft Word Template” on page 13-111
• “Add Holes in a Microsoft Word Template” on page 13-112
• “Create an HTML Template” on page 13-122
• “Add Holes in an HTML Template” on page 13-124
More About
• “Form-Based Reporting” on page 13-28
13-40
Create and Format Text
Create Text
You can create text by appending a string to a document, paragraph, table entry, or list
item. The DOM append function converts the string to a Text object, appends it, and
returns the Text object. Use the Text object to format the text. You can also create a
text object directly and append it to a document. This example:
• Creates the Text object t1 by appending the string 'Hello' to the document
• Uses a Text constructor to create a Text object and append the text 'World' to the
document
import mlreportgen.dom.*
doc = Document('mydoc','html');
t1 = append(doc,'Hello');
append(doc, Text('World'));
close(doc);
rptview('mydoc','html');
13-41
13 Create a Report Program
p = Paragraph(CharEntity('pound'));
append(d,p);
append(p,'3');
close(d);
rptview('test','html');
close(d);
rptview('test','html');
Format Text
You can format text programmatically, using either DOM format objects or Text object
format properties. You can also use Word and HTML template styles. For information
about these formatting techniques and format inheritance, see “Report Formatting
Approaches” on page 13-20.
You can use format objects to format Text objects or format properties to specify
commonly used text formats. This example uses:
13-42
Create and Format Text
fontFamily = FontFamily('Arial');
fontFamily.BackupFamilyNames = {'Helvetica'};
t.Style = {fontFamily};
t.Bold = true;
close(d);
rptview('test','html');
You can format a paragraph using a style defined in the Word template used to generate
the report.
13-43
13 Create a Report Program
For more information about working with Word styles, see “Modify Styles in a Microsoft
Word Template” on page 13-117.
You can format text using a style defined in the HTML template used to generate the
report. Apply a template style to a Text object either as the second argument in a Text
object constructor or by setting the StyleName property to a template style.
For more information about using HTML styles with DOM objects, see “Modify Styles in
an HTML Template” on page 13-127 .
Apply a template style to a Text object either as the second argument in a Text object
constructor or by setting the StyleName property to a template style. For example,
suppose you have defined styles named Body, Pass, and Fail in the template for your
report. You can then apply the styles as follows.
import mlreportgen.dom.*;
passed = rand(1) >= 0.5;
rpt = Document('MyReport','html','MyTemplate');
13-44
Create and Format Text
if passed
status = 'Passed';
statusStyle = 'Pass';
else
status = 'Failed';
statusStyle = 'Fail';
end
t2 = Text(status,statusStyle);
statusPara = Paragraph(t1);
append(statusPara,t2);
append(rpt, statusPara);
close(rpt);
rptview(rpt.OutputPath);
You can use programmatic formats to override the formats defined in a template-based
style. For example, suppose you define a style named AlertLevel in your template and
set the color to be green by default. You can override the style in your report program to
set a color based on the current alert level. For example:
t = Text('Danger!','AlertLevel');
t.Color = 'red';
See Also
Classes
mlreportgen.dom.Bold | mlreportgen.dom.CharEntity |
mlreportgen.dom.FontFamily | mlreportgen.dom.FontSize |
mlreportgen.dom.Italic | mlreportgen.dom.Strike | mlreportgen.dom.Text
| mlreportgen.dom.Underline
Related Examples
• “Add Content to a Report” on page 13-11
More About
• “Report Formatting Approaches” on page 13-20
13-45
13 Create a Report Program
In this section...
“Create a Paragraph” on page 13-46
“Create a Heading” on page 13-46
“Format a Paragraph” on page 13-47
Create a Paragraph
You can create a paragraph by using an mlreportgen.dom.Paragraph constructor
with a text string. For example:
You can also specify these DOM objects in a Paragraph object constructor.
• mlreportgen.dom.Text
• mlreportgen.dom.ExternalLink
• mlreportgen.dom.InternalLink
• mlreportgen.dom.LinkTarget
• mlreportgen.dom.Image
Create a Heading
You can use an mlreportgen.dom.Heading object to create a paragraph that you want
to appear in the table of contents of a document (see “Create a Table of Contents” on
page 13-78). Specify the heading level as the first argument in the Heading object
constructor, followed by the heading content. Optionally, as a third argument, you can
specify the name of a paragraph style defined in the template used to generate your
report.
This example creates a heading with the text Chapter 1: System Overview and
specifies the heading to appear at the top level in a table of contents.
13-46
Create and Format Paragraphs
Format a Paragraph
You can format a paragraph programmatically, using DOM format objects or format
properties. You can also use Word and HTML template styles. For information about
these formatting techniques and format inheritance, see “Report Formatting Approaches”
on page 13-20.
Note: You can use the same format objects and properties for Heading objects as you do
for Paragraph objects.
You can use format objects to format Paragraph objects or format properties to specify
commonly used paragraph formats. This example uses:
import mlreportgen.dom.*;
doc = Document('test','html');
p = Paragraph('Centered paragraph');
p.HAlign = 'center';
append(doc,p);
close(doc);
rptview('test','html');
13-47
13 Create a Report Program
13-48
Create and Format Paragraphs
You can format using an existing style in a Word template or using a template style that
you modify or add.
For more information about working with Word styles, see “Modify Styles in a Microsoft
Word Template” on page 13-117.
You can format using an existing style in an HTML template or using a template style
that you modify or add.
p.BodyPara {
font-family: "Times New Roman", Times, serif;
font-style: normal;
font-size: 11pt;
color: black;
margin-left: 0.5in;
13-49
13 Create a Report Program
For more information about using HTML styles with DOM objects, see “Modify Styles in
an HTML Template” on page 13-127.
p = Paragraph(sprintf('Rank %d MagicSquare',rank));
p.StyleName = 'TableTitle';
append(rpt,magic(rank));
close(rpt);
rptview(rpt.OutputPath);
You can use programmatic formats to override the paragraph formats defined in a
template-based paragraph style. For example, suppose you define a paragraph style
named BodyPara in your Word template and set the KeepWithNext property to off. You
can override the style in your report program to keep a particular paragraph on the same
page with the next paragraph. For example:
import mlreportgen.dom.*;
rpt = Document('MyReport','docx','MyTemplate');
p = Paragraph('Next paragraph.');
13-50
Create and Format Paragraphs
append(rpt, p);
close(rpt);
rptview(rpt.OutputPath);
See Also
Classes
mlreportgen.dom.Bold | mlreportgen.dom.FontFamily |
mlreportgen.dom.FontSize | mlreportgen.dom.Italic |
mlreportgen.dom.KeepLinesTogether | mlreportgen.dom.KeepWithNext
| mlreportgen.dom.LineSpacing | mlreportgen.dom.PageBreakBefore
| mlreportgen.dom.Paragraph | mlreportgen.dom.Strike |
mlreportgen.dom.Text | mlreportgen.dom.Underline
Related Examples
• “Add Content to a Report” on page 13-11
More About
• “Report Formatting Approaches” on page 13-20
13-51
13 Create a Report Program
In this section...
“Create an Unordered List” on page 13-52
“Create an Ordered List” on page 13-53
“Create a Multilevel List” on page 13-55
“Format Lists” on page 13-56
• Unordered (bulleted)
• Ordered (numbered)
• Multilevel (lists that contain ordered or unordered lists in any combination)
• Creating a list from a cell array allows you to include items of different types in the
list.
• Creating a list from scratch is useful for including multiple objects in a list item.
import mlreportgen.dom.*;
d = Document('myListReport','html');
t = Text('third item');
append(d,{'first item',6,t,'fourth item'});
13-52
Create and Format Lists
close(d);
rptview('myListReport','html');
You can also create an unordered list from an array by including the array in an
UnorderedList object constructor.
import mlreportgen.dom.*;
d = Document('unorderedListReport','html');
ul = UnorderedList({Text('item1'),'item 2',3});
append(d,ul);
close(d);
rptview('unorderedListReport','html');
import mlreportgen.dom.*;
d = Document('unorderedListReport','html');
ul = UnorderedList();
append(ul,li1);
append(ul,li2);
append(ul,li3);
append(d,ul);
close(d);
rptview('unorderedListReport','html');
13-53
13 Create a Report Program
• Creating an ordered list from a cell array allows you to include items of different
types in the list.
• Creating a list from scratch is useful for including multiple objects in a list item.
You can create an unordered list from a numeric array or cell array by including the
array in an mlreportgen.dom.OrderedList object constructor. In the cell array, you
can include strings, numbers, and some DOM objects, such as a Text object. For a list of
DOM objects you can include, see mlreportgen.dom.ListItem.
import mlreportgen.dom.*;
d = Document('orderedListReport','html');
t = Text('step 1');
ol = OrderedList({t,'step 2','step 3'});
append(d,ol);
close(d);
rptview('orderedListReport','html');
ol = OrderedList();
append(ol,li1);
append(ol,li2);
append(ol,li3);
append(d,ol);
close(d);
rptview('orderedListReport','html');
13-54
Create and Format Lists
You can create multilevel lists either from cell arrays or from scratch. Creating a
multilevel list from scratch is useful for creating list items that contain multiple
paragraphs, paragraphs and tables, and other combinations of document elements.
You can use any of these approaches to create a multilevel list from a cell array.
import mlreportgen.dom.*;
d = Document('orderedListReport','html');
close(d);
rptview('orderedListReport','html');
• Include list objects as members of a one-dimensional cell array representing the
parent list. Use this approach to create ordered sublists from cell arrays.
d = Document('myListReport','html');
close(d);
rptview('myListReport','html');
• Combine the nested cell array and nested list object approaches.
You can create a multilevel list from scratch by appending child lists to parent lists.
import mlreportgen.dom.*;
13-55
13 Create a Report Program
d = Document('orderedListReport','html');
Format Lists
You can use list styles defined in a report style sheet to specify the indentation of each
level of a list and the type of bullet or the number format used to render list items. To use
a template-defined list style to format a list, set the StyleName property of the list to the
name of the style. For example:
import mlreportgen.dom.*;
d = Document('myListReport','html','MyTemplate');
close(d);
rptview('myListReport','html');
Note: A list style determines how list items are rendered regardless of the list type.
If you do not specify a list style, the DOM API uses a default list style that renders
the list according to type. For example, the default list style for unordered lists uses
bullets to render list items. If you specify a list style for an UnorderedList object that
numbers top-level items, the top-level items are numbered, even though the object type is
unordered (bulleted).
13-56
Create and Format Lists
To define a list style in a Word template, select List as the style type in the Create
New Style from Formatting dialog box (see “Add Styles to a Word Template” on page
13-118).
To define a list style in an HTML template cascading style sheet (CSS), use the ul
element for unordered list styles and the ol element for ordered list styles. You can use
the parent element selector (>) to define multilevel list styles. For example, this CSS
code defines the appearance of a two-level unordered list that can contain ordered or
unordered sublists.
ul.MyUnorderedList {
list-style-type:disc;
}
ul.MyUnorderedList > ul {
list-style-type:circle;
}
ul.MyUnorderedList > ol {
list-style-type:decimal;
}
For information about editing a cascading style sheet (CSS), see documentation such as
the W3Schools.com CSS tutorial.
See Also
Classes
mlreportgen.dom.ListItem | mlreportgen.dom.OrderedList |
mlreportgen.dom.UnorderedList
Functions
mlreportgen.dom.OrderedList.append
Related Examples
• “Use Style Sheets” on page 13-21
13-57
13 Create a Report Program
• An informal table (i.e., a table) consists of rows that contain table entries.
• A formal table contains a header, a body, and a footer section. Each section contains
rows that contain table entries.
Informal tables are useful for most of your reporting needs. Use formal tables for tables
whose headers or footers contain multiple rows.
13-58
Create and Format Tables
This example shows how to create a table from a numeric array and another table from
a cell array of various object types. The cell array contains a magic square, which is
rendered as an inner table. The cell array also includes a Text object constructor that
uses the AlertLevel template style.
import mlreportgen.dom.*;
doc = Document('test');
table1 = append(doc,magic(5));
table1.Border = 'single';
table1.ColSep = 'single';
table1.RowSep = 'single';
close(doc);
rptview(doc.OutputPath);
import mlreportgen.dom.*;
doc = Document('test');
a = magic(5);
[v,i] = max(a);
[v1,i1] = max(max(a));
13-59
13 Create a Report Program
table = Table(a);
text = table.entry(i(i1),i1).Children(1);
text.Color = 'red';
append(doc,table);
close(doc);
rptview(doc.OutputPath);
import mlreportgen.dom.*;
doc = Document('test');
table = Table(4);
table.Border = 'single';
table.ColSep = 'single';
table.RowSep = 'single';
row = TableRow;
append(row, TableEntry('entry 11'));
te = TableEntry('entry 12-13');
te.ColSpan = 2;
te.Border = 'single';
append(row, te);
append(row, TableEntry('entry 14'));
append(table,row);
row = TableRow;
for c = 1:4
append(row, TableEntry(sprintf('entry 2%i', c)));
end
append(table,row);
append(doc,table);
13-60
Create and Format Tables
close(doc);
rptview(doc.OutputPath);
Format a Table
You can format a table programmatically, using DOM format objects or format
properties. You can also use Word and HTML template styles. For information about
these formatting techniques and format inheritance, see “Report Formatting Approaches”
on page 13-20.
You can use format objects to format tables or use Table format properties to specify
commonly used table formats. This example uses:
• Border, ColSep, and RowSep format objects to specify a red table border and the
green column and row separators
• The Width format property to specify the table width
import mlreportgen.dom.*;
doc = Document('test','html');
table = Table(magic(5));
table.Style = {Border('inset','red','3px'), ...
ColSep('single','green','1px'), ...
RowSep('single','green','1px')};
table.Width = '50%';
append(doc, table);
close(doc);
rptview(doc.OutputPath);
13-61
13 Create a Report Program
A Table object has properties that allow you to specify the same format or set of formats
for all of its entries.
13-62
Create and Format Tables
p = Paragraph('Table 1');
p.Style = {Bold,KeepLinesTogether,KeepWithNext};
append(rpt, p);
ca{1,1}.Children(1).Bold = true;
ca{1,2}.Children(1).Bold = true;
for r = 1:2
for c = 1:2
ca{r, c}.Style = {KeepLinesTogether,KeepWithNext};
end
end
for c = 1:2
ca{3, c}.Style = {KeepLinesTogether};
end
13-63
13 Create a Report Program
append(rpt, ca);
close(rpt);
rptview(rpt.OutputPath);
You can format tables using an existing Word styles in a template or a template style
that you modify or add.
For more information about using Word styles with DOM objects, see “Modify Styles in a
Microsoft Word Template” on page 13-117.
You can format tables using an HTML style defined in the template used to generate the
report.
To define a table style in an HTML template, define the style as a table style. For
example:
table.MyTable {
border-bottom-color: rgb(128, 128, 128);
border-bottom-width: thin;
border-collapse: collapse;
}
Tip Use the CSS parent (>) selector to specify the format of the children of a table to be
formatted with your table style. For example, this CSS code specifies the format of the
table entries (td elements) of a table whose style is MyTable.
13-64
Create and Format Tables
Once you have defined a table style in a template, you can apply it to a Table object in
your report program either as the second argument in the Table object constructor or
by setting it to the StyleName property of the Table object. For example, suppose you
have defined styles named BodyPara, TableTitle, and RuledTable in the template
for your report. This example specifies style names in a Paragraph constructor, in the
StyleName property of a Paragraph object, and in a Table constructor.
import mlreportgen.dom.*;
rank = 5;
rpt = Document('MyReport','html','MyTemplate');
p = Paragraph(sprintf('Rank %d MagicSquare',rank));
p.StyleName = 'TableTitle';
append(rpt,Table(magic(rank),'RuledTable'));
close(rpt);
rptview(rpt.OutputPath);
You can use programmatic formats to override the styles defined in a template-based
table style. For example, suppose you define a table style named UnruledTable in your
template to create tables without any borders or column or row separators. You can then
override the style in your report program to draw a frame around a table.
import mlreportgen.dom.*;
rpt = Document('MyReport','html','MyTemplate');
table = Table(magic(5),'UnruledTable');
table.Border = 'single';
append(rpt,table);
close(rpt);
rptview(rpt.OutputPath);
13-65
13 Create a Report Program
If you choose to build a formal table completely or partially from scratch, you can use the
FormalTable object functions appendHeaderRow and appendBodyRow to append rows
to the table header and footer sections. The FormalTable.append function appends a
row to the body section. Alternatively, you can access a section using the Header, Body,
or Footer properties of the FormalTable object.
import mlreportgen.dom.*
d = Document('test');
t = FormalTable({'a','b';'c','d'});
r = TableRow();
append(r,TableEntry('Column 1'));
append(r,TableEntry('Column 2'));
append(t.Header,r);
append(d,t);
close(d);
rptview(d.OutputPath);
You can format a formal table programmatically the same way you format an informal
table. The format objects and properties that apply to an informal table also apply to
formal tables. In addition, you can format the header, body, and footer sections of an
informal table programmatically. If you specify a format for the table and one of its
sections, the value you specify for the section overrides the value you specify for the table
13-66
Create and Format Tables
as a whole. Not all formal table formats apply to formal table sections. For example, you
cannot indent a header, body, or footer section independently of the containing table. In
other words, the OuterLeftMargin property does not apply to formal table sections.
Use the same procedure for defining formal table styles in Word and HTML templates as
you use for defining informal table styles.
You can apply a table style to a formal table and to each of its sections. If you apply
a table style to the table itself and to one of its section (for example, the header), the
section style overrides the table style.
Note: If you apply a table style to one or more sections of a Word formal table, you must
specify the widths of each of the table columns. Otherwise, the columns of the sections
may not line up.
import mlreportgen.dom.*
rpt = Document('test');
table = Table(2);
row = TableRow();
append(row,TableEntry('Col1'));
append(row,TableEntry('Col2'));
append(table,row);
13-67
13 Create a Report Program
row = TableRow();
append(row,TableEntry('data11'));
append(row,TableEntry('data12'));
append(table,row);
append(rpt,table);
close(rpt);
rptview(rpt.OutputPath);
Use these format objects and format properties to format a table row.
import mlreportgen.dom.*
rpt = Document('test');
rank = 5;
13-68
Create and Format Tables
table = Table(magic(rank));
table.Border = 'single';
table.BorderWidth = '1px';
grps(1) = TableColSpecGroup;
grps(1).Span = rank;
grps(1).Style = {Width('0.2in'),Color('green')};
specs(1) = TableColSpec;
specs(1).Span = 1;
specs(1).Style = {Width('0.5in'),Bold,Color('red')};
grps(1).ColSpecs = specs;
table.ColSpecGroups = grps;
append(rpt,table);
close(rpt);
rptview('test','html');
To have columns resize to fit the widest content of the table entries in a column, include a
ResizeToFitContents object in the Style property of the table.
Use a TableEntry constructor to create a table entry. You can optionally use the
constructor to specify these kinds of entry content:
• Char array
• Any of these kinds of DOM objects:
• Paragraph
• Text
13-69
13 Create a Report Program
• Image
• Table
• OrderedList
• UnorderedList
• CustomElement
You can use format objects or TableEntry format properties to format a table entry
programmatically.
You can specify formatting for all table entries in a table, use the TableEntriesStyle
property of the Table or FormalTable object. For example, you can set border
formatting.
import mlreportgen.dom.*
t = Table(magic(5));
13-70
Create and Format Tables
t.TableEntriesStyle(Border('solid','black','1 px'));
Properties you set for a TableEntry object take precedence over TableEntriesStyle
format objects.
For HTML reports, you can use styles defined in an HTML template style sheet to format
table entries. When defining a table entry style, use a td element selector. For example:
td.TableEntryWithBorder {
border:5px solid red;
}
te = TableEntry('Hello World','TableEntryWithBorder');
See Also
Classes
mlreportgen.dom.AllowBreakAcrossPages |
mlreportgen.dom.ColSep | mlreportgen.dom.FlowDirection |
mlreportgen.dom.FormalTable | mlreportgen.dom.RepeatAsHeaderRow
| mlreportgen.dom.ResizeToFitContents | mlreportgen.dom.RowHeight
| mlreportgen.dom.RowSep | mlreportgen.dom.Table |
mlreportgen.dom.TableBody | mlreportgen.dom.TableColSpec |
mlreportgen.dom.TableColSpecGroup | mlreportgen.dom.TableEntry
| mlreportgen.dom.TableFooter | mlreportgen.dom.TableHeader |
mlreportgen.dom.TableHeaderEntry | mlreportgen.dom.TableRow
Functions
mlreportgen.dom.FormalTable.appendFooterRow |
mlreportgen.dom.FormalTable.appendHeaderRow |
mlreportgen.dom.TableRow.append
Related Examples
• “Add Content to a Report” on page 13-11
13-71
13 Create a Report Program
More About
• “Report Formatting Approaches” on page 13-20
13-72
Create Links
Create Links
In this section...
“Links” on page 13-73
“Create a Link Target” on page 13-73
“Create an External Link” on page 13-74
“Create an Internal Link” on page 13-74
“Add Text or Images to Links” on page 13-74
Links
You can add these kinds of links to a report:
• External — Link to a location outside of the report, such as an HTML page or a PDF
file. Use an mlreportgen.dom.ExternalLink object.
• Internal — Link to locations in the report. Use an
mlreportgen.dom.InternalLink object.
This example creates a link target called home, and uses home as the target for an
internal link.
import mlreportgen.dom.*
d = Document('mydoc');
append(d,LinkTarget('home'));
append(d,InternalLink('home','Go to Top'));
close(d);
rptview('mydoc', 'html');
13-73
13 Create a Report Program
import mlreportgen.dom.*
d = Document('mydoc');
append(d,ExternalLink('http://www.mathworks.com/','MathWorks'));
close(d);
rptview('mydoc','html');
import mlreportgen.dom.*
d = Document('mydoc');
close(d);
rptview('mydoc','html');
See Also
mlreportgen.dom.ExternalLink | mlreportgen.dom.ExternalLink.append |
mlreportgen.dom.InternalLink | mlreportgen.dom.LinkTarget
13-74
Create Links
Related Examples
• “Create Image Maps” on page 13-85
• “Add Content to a Report” on page 13-11
More About
• “Report Formatting Approaches” on page 13-20
13-75
13 Create a Report Program
Create an Image
To create an image to a report, create an mlreportgen.dom.Image object. You can
append it to one of these document element objects:
• Document
• Group
• Paragraph
• ListItem
• TableEntry
For example, you can create a MATLAB figure, save it as an image, and add the image to
a report.
import mlreportgen.dom.*
d = Document('imageArea','html');
p = Paragraph('Plot 1');
p.Bold = true;
append(d,p);
x = 0:pi/100:2*pi;
y = sin(x);
plot(x,y);
saveas(gcf,'myPlot_img.png');
plot1 = Image('myPlot_img.png');
append(d,plot1);
13-76
Create and Format Images
close(d);
rptview(d.OutputPath);
Resize an Image
To resize an image object, you can:
Image Storage
Keep the original file until it has been copied into the document. The DOM API copies
the contents of the source image file into the output document either when you append
the Image object to the document (if you set the Document.StreamOutput property to
true) or when you close the document.
See Also
mlreportgen.dom.Height | mlreportgen.dom.Image |
mlreportgen.dom.ScaleToFit | mlreportgen.dom.Width
Related Examples
• “Add Content to a Report” on page 13-11
More About
• “Report Formatting Approaches” on page 13-20
13-77
13 Create a Report Program
In this section...
“Create a Microsoft Word Table of Contents” on page 13-78
“Create an HTML Table of Contents” on page 13-80
“Set Outline Levels of Section Heads” on page 13-82
You use a very similar procedure for Word reports you create using the DOM API, except
that you create the section heads programmatically instead of interactively. To generate
a table of contents in a DOM Word report, perform these steps.
1 Create a table of contents reference in the Word template to specify where in the
report to generate the TOC. See “Create a Word Table of Contents Reference” on
page 13-78.
2 Set the outline levels of the section heads that you want to appear in the table of
contents. See “Set Outline Levels of Section Heads” on page 13-82.
3 Update the generated document. See “Update the TOC in a Word Report” on page
13-79.
13-78
Create a Table of Contents
5 Select a TOC format option to generate a table of contents. For example, select the
Built-In format option. The TOC appears.
After you generate a Word report with the DOM API, open the report in Word and
update the document. Updating a document refers to the process of updating the parts of
a Word document that Word itself generates, such as a TOC, page numbers, and so on,
to reflect changes in the document content. The DOM rptview function causes Word to
update a report after opening it. If you use rptview to display your document in Word,
you do not need to do anything else to generate a TOC in your report.
13-79
13 Create a Report Program
However, if you open a newly generated report yourself in Word, without first using
rptview, perform these steps to get the TOC to appear.
1 Create an HTML TOC placeholder element in the template. See “Create an HTML
TOC Placeholder” on page 13-81
2 Set the outline levels of the section heads that you want to appear in the table of
contents. See “Set Outline Levels of Section Heads” on page 13-82.
3 Open the generated report in a browser.
13-80
Create a Table of Contents
An HTML TOC placeholder element is an HTML div element with an id attribute set to
toc.
<div id="toc"/>
Next,
If you use the DOM default HTML template (or a template based on the default
template), you can create a placeholder programmatically in your report. For example:
import mlreportgen.dom.*;
d = Document('MyReport','html');
append(d,'My Report');
13-81
13 Create a Report Program
toc = CustomElement('div');
toc.CustomAttributes = {CustomAttribute('id', 'toc')};
append(toc, CustomText()); % Workaround for browser bug
append(d, toc);
close(d);
rptview(d.OutputPath);
The document part template library of the DOM default template contains a document
part for creating a TOC placeholder. If you use this template or a template based on it,
you can use the document part to insert a TOC placeholder in your report. For example:
import mlreportgen.dom.*;
d = Document('MyReport','html');
append(d,'My Report');
append(d, DocumentPart(d,'ReportTOC'));
append(d, Heading(1,'Chapter 1'));
append(d, Heading(2,'Section 1'));
close(d);
rptview(d.OutputPath);
13-82
Create a Table of Contents
You can use styles defined in the report’s template to set the outline level of a paragraph.
For example, by default Word documents include a set of styles, Heading 1, Heading 2,
and so on, that define outline levels for paragraphs you want to appear in a TOC. Your
program can use these built-in styles to specify that paragraphs that serve as section
heads appear in the TOC. The following example illustrates the use of template-defined
styles to set the outline levels of section heads. This example assumes that the template
MyTemplate includes a TOC reference.
import mlreportgen.dom.*;
d = Document('MyReport','docx','MyTemplate');
close(d);
rptview(d.OutputPath); % Updates the TOC
You can also use Word or an HTML editor to define your own heading styles and then
use them to generate a report.
You can use format objects to set outline levels. This example assumes that the template
MyTemplate includes a TOC reference.
import mlreportgen.dom.*;
d = Document('MyReport','docx','MyTemplate');
h1 = {FontFamily('Arial'),FontSize('16pt'),OutlineLevel(1)};
h2 = {FontFamily('Arial'),FontSize('14pt'),OutlineLevel(2)};
p = append(d,Paragraph('Chapter 1'));
p.style = h1;
p = append(d, Paragraph('Section 1'));
p.style = h2;
close(d);
rptview(d.OutputPath); % Updates the TOC
13-83
13 Create a Report Program
import mlreportgen.dom.*;
d = Document('MyReport','docx','MyTemplate');
h1 = {FontFamily('Arial'),FontSize('16pt')};
h2 = {FontFamily('Arial'),FontSize('14pt')};
h = append(d, Heading(1,'Chapter 1'));
h.style = h1;
h = append(d, Heading(2,'Section 1'));
p.style = h2;
close(d);
rptview(d.OutputPath); % Updates the TOC
The Heading objects generate HTML h1, h2 (and so on) elements. By using Heading
objects in an HTML report, you can ensure that your report uses the default styles for
headings implemented by the browser in which you display the report.
See Also
Functions
rptview | unzipTemplate | zipTemplate
Classes
mlreportgen.dom.Heading
Related Examples
• “Create a Microsoft Word Template” on page 13-111
• “Create an HTML Template” on page 13-122
13-84
Create Image Maps
• Rectangle
• Circle
• Polygon
For example, you can create a link from a plot image to documentation about plotting.
import mlreportgen.dom.*
d = Document('imageArea','html');
x = 0:pi/100:2*pi;
y = sin(x);
plot(x,y);
annotation('textbox',[0.2,0.4,0.1,0.1],...
'String','Help for plot function');
saveas(gcf,'plot_img.png');
plot1 = Image('plot_img.png');
append(d,plot1);
area1 = ImageArea(...
['http://www.mathworks.com/help/matlab/ref/' ...
'plot.html?searchHighlight=plot'], ...
'plot function help',240,450,463,492);
map = ImageMap();
plot1.Map = map;
append(map,area1);
13-85
13 Create a Report Program
close(d);
rptview(d.OutputPath);
See Also
Classes
mlreportgen.dom.Image | mlreportgen.dom.ImageArea |
mlreportgen.dom.ImageMap
Functions
Related Examples
• “Add Content to a Report” on page 13-11
More About
• “Report Formatting Approaches” on page 13-20
13-86
Automatically Number Document Content
You can automatically number document content, such as chapter, section, table, and
figure headings. Append automatic numbering objects to the document where you want
numbers to appear. Each automatic number is associated with a numbering stream
that determines the value of each number in a sequence. Report generation replaces
an automatic numbering object with a number based on its position in the document
relative to other automatic numbers in the same stream. For example, the first automatic
numbering object in a stream can be replaced by 1, the second by 2, and so on. You can
use automatic numbering to create hierarchical numbering schemes such as Section 1.1.,
Section 1.2, and so on.
chapterNumber = AutoNumber('chapter');
Note: If the specified automatic numbering stream does not exist, the AutoNumber
constructor creates a numbering stream having the specified name. The
implicitly constructed stream renders automatic numbers as Arabic numerals.
To use a stream with different properties, create the stream explicitly, using a
createAutoNumberStream function of a Document object.
13-87
13 Create a Report Program
2 Append the AutoNumber to a Text, Paragraph, or Heading object that contains the
text that precedes the automatic number.
append(chapHead,chapterNumber);
3 Append an mlreportgen.dom.CounterInc format object to the Style property of
the content object that you want to automatically number. Appending a CounterInc
object increments the stream associated with the automatic number when the
paragraph or heading is output. The updated value replaces the AutoNumber object.
chapHead.Style = {CounterInc('chapter'), WhiteSpace('preserve')};
close(d);
rptview(d.OutputPath);
You can create hierarchical numbering schemes, such as 1.1, 1.2, 1.3, 2.1, 2.2, and so
on. Use an mlreportgen.dom.CounterReset format object to reset a child automatic
number to its initial value when its parent number changes. For example, this script
uses a CounterReset format object to reset the chapter table number stream at the
beginning of each chapter.
import mlreportgen.dom.*;
d = Document('MyReport','html');
13-88
Automatically Number Document Content
for i = 0:1;
tableHead = Paragraph('Table ');
append(tableHead,AutoNumber('chapter'))
append(tableHead,'.');
append(tableHead, AutoNumber('table'));
append(tableHead, ...
sprintf('. Rank %i Magic Square',rank+i));
tableHead.Style = {CounterInc('table'), ...
Bold, ...
FontSize('11pt'), ...
WhiteSpace('preserve')};
append(d,tableHead);
table = append(d,magic(rank+i));
table.Width = '2in';
end
end
close(d);
rptview(d.OutputPath);
For example, suppose that you add a chapter part template Chapter to the part
template library of the Word MyReportTemplate.dotx report template. This template
uses a Word sequence (SEQ) field to number the chapter heading. The template also
contains holes for the chapter title and the chapter content.
This script uses the chapter part template to create numbered chapters. The last
statement in this script opens the report in Word and updates it. Updating the report
causes Word to replace the SEQ fields with the chapter numbers.
13-89
13 Create a Report Program
import mlreportgen.dom.*
d = Document('MyReport','docx','MyReportTemplate');
close(d);
rptview(d.OutputPath);
You can use a similar approach to automatically number HTML reports, using the CSS
counter-increment and content properties in the template for your report.
See Also
Functions
mlreportgen.dom.Document.createAutoNumberStream |
mlreportgen.dom.Document.getAutoNumberStream
Classes
mlreportgen.dom.AutoNumber | mlreportgen.dom.AutoNumberStream |
mlreportgen.dom.CounterInc | mlreportgen.dom.CounterReset
13-90
Appending HTML to DOM Reports
You can append HTML markup for a report to a DOM report, which you can then
generate in Word or PDF format.
• Add content based on HTML markup.
You can append the HTML content to a DOM report. You can use the HTML content
as a building block in a DOM report that includes other report elements.
For example, this DOM code creates a Word report that displays Hello World,
based on the HTML content that you append to the report.
import mlreportgen.com.*;
d = Document('MyReport','docx');
addHTML(d,'<p style="color:blue"><b>Hello World</b></p>');
13-91
13 Create a Report Program
The HTML content that you append must be XML parsable. For a summary of those
requirements and for a list of supported HTML elements and HTML CSS formats,
see “HTML Code Requirements for DOM Reports” on page 13-101.
See Also
mlreportgen.dom.Document.addHTML |
mlreportgen.dom.Document.addHTMLFile | mlreportgen.dom.HTML |
mlreportgen.dom.HTMLFile
Related Examples
• “Append HTML Content to DOM Reports” on page 13-93
• “Append HTML File Contents to DOM Reports” on page 13-95
• “Use an HTML Cleanup Program” on page 13-97
More About
• “HTML Code Requirements for DOM Reports” on page 13-101
13-92
Append HTML Content to DOM Reports
In this section...
“Use an addHTML Method” on page 13-93
“Append an HTML Object” on page 13-94
“Address Errors” on page 13-94
You can append strings of HTML content to a DOM document or document part using
either of these approaches:
If the HTML content that you append does not meet DOM requirements, the DOM API
generates error messages. You can use an HTML cleanup program such as HTML Tidy
on a file containing the source HTML content. HTML Tidy fixes many issues and also
identifies issues you need to address manually. After you clean up the source HTML
content, append it to a DOM report.
For example, you can use addHTML to create an HTML object that you append to a DOM
report that produces Word output.
import mlreportgen.dom.*;
rpt = Document('HTMLToWordReport','docx');
htmlObj = addHTML(rpt,...
'<p><b>Hello</b> <i style="color:green">World</i></p>');
close(rpt);
rptview(rpt.OutputPath);
13-93
13 Create a Report Program
For example, you can create an HTML object from HTML markup to use for a Word report.
import mlreportgen.dom.*;
rpt = Document('MyRep1','docx');
html = HTML('<p><b>Hello</b> <i style="color:green">World</i></p>');
close(rpt);
rptview(rpt.OutputPath);
Address Errors
If you receive any MATLAB error messages, fix the source HTML markup and append
the HTML again. You can use an HTML cleanup program such as HTML Tidy on a file
containing the source HTML content. HTML Tidy fixes many issues and also identifies
issues you need to address manually. After you clean up the source HTML content,
append it to a DOM report. For details, see “Use an HTML Cleanup Program” on page
13-97.
See Also
mlreportgen.dom.Document.addHTML | mlreportgen.dom.HTML
Related Examples
• “Append HTML File Contents to DOM Reports” on page 13-95
• “Use an HTML Cleanup Program” on page 13-97
More About
• “Appending HTML to DOM Reports” on page 13-91
• “HTML Code Requirements for DOM Reports” on page 13-101
13-94
Append HTML File Contents to DOM Reports
In this section...
“Use an addHTMLFile Method” on page 13-95
“Append an HTMLFile Object” on page 13-95
“Address Errors” on page 13-96
You can append HTML files to a DOM document or document part using either of these
approaches:
If the HTML file contents that you append do not meet DOM requirements, the DOM
API generates error messages. You can use an HTML parser and cleanup program such
as HTML Tidy to fix many issues and to identify issues you need to address manually.
For example, you can use addHTMLFile to create an HTMLFile object that you append to
a DOM report that produces Word output.
import mlreportgen.dom.*;
rpt = Document('HTMLToWordReport','docx');
htmlObj = addHTML(rpt,...
'<p><b>Hello</b> <i style="color:green">World</i></p>');
close(rpt);
rptview(rpt.OutputPath);
13-95
13 Create a Report Program
For example, you can convert the contents of two HTML files to a DOM report in Word
format. This example assumes that there are HTML files called myHTMLfile1.html and
myHTMLfile2.htmlin the MATLAB current folder.
import mlreportgen.dom.*;
rpt = Document('MyHTMLReport','docx');
path = 'myHTMLfile1.html';
htmlFile1 = HTMLFile(path);
htmlFile2 = HTMLFile('myHTMLFile2.html');
append(htmlFile1,htmlFile2)
append(rpt,htmlFile1);
close(rpt);
rptview(rpt.OutputPath);
Address Errors
If you receive any MATLAB error messages, fix the source HTML markup and append
the HTML again. You can use an HTML cleanup program such as HTML Tidy on the
HTML file to fix many issues. HTML Tidy also identifies issues you need to address
manually. After you clean up the HTML content, append it to a DOM report. For details,
see “Use an HTML Cleanup Program” on page 13-97.
See Also
mlreportgen.dom.Document.addHTMLFile | mlreportgen.dom.HTMLFile
Related Examples
• “Append HTML Content to DOM Reports” on page 13-93
• “Use an HTML Cleanup Program” on page 13-97
More About
• “Appending HTML to DOM Reports” on page 13-91
• “HTML Code Requirements for DOM Reports” on page 13-101
13-96
Use an HTML Cleanup Program
1 Copy the following HTML content into a text editor such as Wordpad.
<html>
<head>
<title>Hi there</title>
</head>
<body>
<p>This is a page
a simple page with a simple table
<style>
table, th, td {
border: 1px solid black;
}
</style>
<table style="width:50%">
<tr>
<td><b>Name</B></td>
<td><b>Age</b></td>
<td><b>Occupation</b></td>
</tr>
<tr>
<td>Joe Smith</td>
<td>40</td>
<td>Plumber</td>
</tr><tr>
<td>Sue Jones</td>
<td>33</td>
<td>Scientist</td>
</tr>
<tr>
13-97
13 Create a Report Program
<td>Carlos Martinez</td>
<td>38</td>
<td>Lawyer</td>
</tr>
</table>
</body>
</html>
This HTML content has elements that are not XML parsable, including:
<p>This is a page
a simple page with a simple table
• Inconsistent case for an element tag:
<td><b>Name</B></td>
2 In the current MATLAB folder, save the file using the file name
simple_html_example.html.
3 Display the file in an HTML browser. Although the HTML content contains elements
that are not XML parsable, it displays properly in most HTML browsers, such as
Internet Explorer.
import mlreportgen.dom.*;
rpt = Document('html_report','docx');
htmlFile = HTMLFile('simple_html_example.html');
Save the batch file in the Windows path. Save the file as tidyup.bat. You can use
this batch file with other HTML files that you want to append to a DOM report.
8 Make a backup copy of the simple_html_example.html file, which contains the
HTML to append to the DOM report.
9 Run Tidy on simple_html_example.html. In a Windows command window, enter:
tidyup simple_html_example.html
10 In the folder where you ran tidyup, check the errs.txt file. That file summarizes
the changes Tidy made, and lists as errors issues that Tidy could not fix. In this
example, there are no errors, but if errs.txt did report errors, manually edit the
HTML file to address those issues.
11 In MATLAB, append the simple_html_example.html file to a DOM report and
display the report.
import mlreportgen.dom.*;
rpt = Document('html_report','docx');
htmlFile = HTMLFile('simple_html_example.html');
append(rpt,htmlFile);
close(rpt);
rptview(rpt.OutputPath);
Related Examples
• “Append HTML Content to DOM Reports” on page 13-93
13-99
13 Create a Report Program
More About
• “HTML Code Requirements for DOM Reports” on page 13-101
• “Appending HTML to DOM Reports” on page 13-91
13-100
HTML Code Requirements for DOM Reports
Tip You can use the HTML Tidy program to ensure that your HTML file is XML
parsable. For details, see “Use an HTML Cleanup Program” on page 13-97.
13-101
13 Create a Report Program
13-102
HTML Code Requirements for DOM Reports
For information about these elements, see the W3Schools tags documentation at
www.w3schools.com/tags.
• background-color
• border
• border-bottom
• border-bottom-color
• border-bottom-style
• boder-bottom-width
• border-color
• border-left
• border-left-color
• border-left-style
• boder-left-width
• border-right
• border-right-color
• border-rigtht-style
• border-right-width
• border-style
• border-top
• border-top-color
• border-top-style
• border-top-width
• color
• font-family
• font-size
13-103
13 Create a Report Program
• font-style
• font-weight
• height
• line-height
• margin
• margin-bottom
• margin-left
• margin-right
• margin-top
• padding
• padding-bottom
• padding-left
• padding-right
• padding-top
• text-align
• text-decoration
• text-indent
• vertical-align
• white-space
• width
For information about these CSS formats, see the W3Schools CSS documentation at
www.w3schools.com/cssref.
13-104
HTML Code Requirements for DOM Reports
Related Examples
• “Use an HTML Cleanup Program” on page 13-97
• “Append HTML Content to DOM Reports” on page 13-93
• “Append HTML File Contents to DOM Reports” on page 13-95
More About
• “Appending HTML to DOM Reports” on page 13-91
13-105
13 Create a Report Program
You can define additional messages to display during report generation. The DOM API
provides these classes for defining messages:
• ProgressMessage
• DebugMessage
• WarningMessage
• ErrorMessage
The DOM API provides additional classes for handling report message dispatching
and display. It uses MATLAB events and listeners to dispatch messages. A message is
dispatched based on event data for a specified DOM object. For an introduction to events
and listeners, see “Events and Listeners — Concepts”.
13-106
Display Report Generation Messages
dispatcher = MessageDispatcher.getTheDispatcher;
dispatcher.Filter.DebugMessagesPass = true;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'),...
CounterReset('table'),WhiteSpace('pre') };
append(p, AutoNumber('chapter'));
append(d,p);
close(d);
rptview('test','html');
delete(l);
13-107
13 Create a Report Program
dispatcher = MessageDispatcher.getTheDispatcher;
2 Add a listener using the MATLAB addlistener function.
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
3 Dispatch the message, using the Message.dispatch method. Specify the dispatcher
object and the message to dispatch. Here the message is a debug message called
starting chapter, and the Document object d is the source of the message.
dispatch(dispatcher,ProgressMessage('starting chapter',d));
4 Include code to delete the listener, after the code that generates the report.
delete(l);
import mlreportgen.dom.*;
d = Document('test','html');
dispatcher = MessageDispatcher.getTheDispatcher;
l = addlistener(dispatcher,'Message', ...
@(src, evtdata) disp(evtdata.Message.formatAsText));
open(d);
dispatch(dispatcher,ProgressMessage('starting chapter',d));
p = Paragraph('Chapter ');
p.Tag = 'chapter title';
p.Style = { CounterInc('chapter'),...
CounterReset('table'),WhiteSpace('pre') };
append(p, AutoNumber('chapter'));
append(d,p);
close(d);
rptview('test','html');
delete(l);
The MATLAB Command Window displays progress messages, including the starting
chapter message, as well as the messages the DOM API dispatches by default.
13-108
Display Report Generation Messages
See Also
Functions
mlreportgen.dom.MessageDispatcher.dispatch |
mlreportgen.dom.MessageDispatcher.getTheDispatcher
| mlreportgen.dom.ProgressMessage.formatAsHTML
| mlreportgen.dom.ProgressMessage.formatAsText |
mlreportgen.dom.ProgressMessage.passesFilter
Classes
mlreportgen.dom.DebugMessage | mlreportgen.dom.ErrorMessage |
mlreportgen.dom.MessageDispatcher | mlreportgen.dom.MessageEventData
| mlreportgen.dom.MessageFilter | mlreportgen.dom.ProgressMessage |
mlreportgen.dom.WarningMessage
13-109
13 Create a Report Program
To enable someone who does not have MATLAB installed to run your compiled program,
your program must execute the following statement before executing the first line of
DOM code that it executes to generate a report:
makeDOMCompilable();
13-110
Create a Microsoft Word Template
If you copy an existing template that is not based on the DOM API default Word
template, apply any standard Word styles such as Title, Heading 1, TOC 1, List 1,
Emphasis, etc. to an element in the template. You can apply the styles to placeholder
content and then remove the content. That process creates instances of the standard
styles in the template style sheet.
See the Word documentation for information about how to create templates and to copy
styles from one template to another.
Related Examples
• “Add Holes in a Microsoft Word Template” on page 13-112
• “Modify Styles in a Microsoft Word Template” on page 13-117
• “Create an HTML Template” on page 13-122
13-111
13 Create a Report Program
Tip If you do not see Developer check box in the list, set Customize the Ribbon to
Main Tabs.
• An inline hole is for document elements that a paragraph element can contain:
Text, Image, LinkTarget, ExternalLink, InternalLink, CharEntity, and
AutoNumber.
• A block hole can contain the same kinds of document elements as an inline hole, as
well as Paragraph, Table, OrderedList, UnorderedList, DocumentPart, and
Group document elements.
13-112
Add Holes in a Microsoft Word Template
Tip If the hole is the only hole in a paragraph or is at the end of a paragraph:
13-113
13 Create a Report Program
This step assumes that you have already created the hole. If have not create a hole,
see “Inline and Block Holes” on page 13-112.
4
In the Insert tab, select the Quick Parts button.
5 In the Quick Parts Gallery, select the part template that contains the hole (for
example, rgChapter).
6 Right-click in the text area of the hole whose default text style you want to specify.
For example, in rgChapter, right-click in the rgChapterTitle hole.
7 Select Properties.
8 In the Content Control Properties dialog box, select the Use a style to format text
typed into the empty control check box.
9 From the Style list, select a style to use an existing style or select New Style to
create a new style to use as the default style and click OK.
10 Select the part template and click the Quick Parts button.
11 Click Save Selection to Quick Part Gallery.
13-114
Add Holes in a Microsoft Word Template
12 In the Create New Building Block dialog box, set Name to the part template name
(for example, rgChapter) and the Category to mlreportgen. Click OK.
13 Save and close the template.
13-115
13 Create a Report Program
Related Examples
• “Modify Styles in a Microsoft Word Template” on page 13-117
• “Create an HTML Template” on page 13-122
• “Create and Format Tables” on page 13-58
13-116
Modify Styles in a Microsoft Word Template
In this section...
“Edit Styles in a Word Template” on page 13-117
“Add Styles to a Word Template” on page 13-118
13-117
13 Create a Report Program
3 In the Manage Styles dialog box, click Modify. The Modify Style dialog box appears.
4 In the Modify Style dialog box, change any of the style definitions. For example, you
could change the font family, font size, indentation, etc. To save your changes, click
OK and close the dialog box.
5 In Word, save and close the template.
For more information about using Word styles, see the Microsoft Word documentation.
13-118
Modify Styles in a Microsoft Word Template
13-119
13 Create a Report Program
3 If applicable, select an existing style to use as a starting point for the new style.
4 Click the New Style button.
13-120
Modify Styles in a Microsoft Word Template
5 Specify a name for the new style and define the style characteristics. To save the new
style definition, click OK and close the dialog box.
6 In Word, save and close the template.
Related Examples
• “Add Holes in a Microsoft Word Template” on page 13-112
• “Create an HTML Template” on page 13-122
13-121
13 Create a Report Program
To repackage a template after you edit it, use the zipTemplate function. For example,
to package the mytemplate.htmx template in a subfolder called mytemplate, in the
current folder:
zipTemplate('mytemplate.htmtx')
If you do not want to use the current folder, you can specify a path with the
unzipTemplate and zipTemplate functions.
See Also
Functions
unzipTemplate | zipTemplate
Classes
mlreportgen.dom.Document
Related Examples
• “Add Holes in an HTML Template” on page 13-124
• “Modify Styles in an HTML Template” on page 13-127
13-122
Create an HTML Template
13-123
13 Create a Report Program
In this section...
“Inline and Block Holes” on page 13-124
“Create an Inline Hole” on page 13-124
“Create a Block Hole” on page 13-125
Template holes are places in a template that a report script fills with generated content,
supporting a forms-based report.
• An inline hole is for document elements that a paragraph element can contain: Text,
Image, LinkTarget, ExternalLink, InternalLink, CharEntity, AutoNumber.
• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList,
DocumentPart, and Group.
<p>
<span>
<div class="Hole" data-default-hole-style-name="STYLE_NAME"
data-hole-id="HOLEID">
<span class="HoleId">HOLEID</span>
<span class="HoleDesc">HOLE_DESCRIPTION</span>
</div>
</span>
</p>
13-124
Add Holes in an HTML Template
Replace STYLE_NAME with the name of a default text (HTML span element) style to
use for formatting Text objects appended to this hole. If a Text object appended to
this hole does not specify a style name, the DOM API sets the text object StyleName
property to the default style name. The style must be defined in the style sheet of the
template. Defining in the template a default text style for hole content eliminates the
need to format hole content programmatically.
Set HOLEID to the ID of the hole, and use HOLE_DESCRIPTION to describe the hole.
5 Zip the template using the zipTemplate command.
Templates based on the DOM API default HTML template contain a style sheet for holes
that highlights the hole IDs when you display the template in a browser.
<div>
<span>
<div class="Hole" data-default-hole-style-name="STYLE_NAME"
data-hole-id="HOLEID">
<span class="HoleId">HOLEID</span>
<span class="HoleDesc">HOLE_DESCRIPTION</span>
</div>
</span>
</div>
Replace STYLE with the name of a default paragraph (HTML p element) style to
use for formatting text content appended to this hole. If you do not specify a style
name for a Text object appended to this hole, the DOM API sets the text object
StyleName property to the default style name. The template style sheet must define
the default style. Defining a default paragraph style for hole content eliminates the
need to format hole content programmatically.
Set HOLEID to the ID of the hole, and use HOLE_DESCRIPTION to describe the hole.
13-125
13 Create a Report Program
See Also
Functions
unzipTemplate | zipTemplate
Related Examples
• “Modify Styles in an HTML Template” on page 13-127
• “Create a Microsoft Word Template” on page 13-111
13-126
Modify Styles in an HTML Template
For information about editing a cascading style sheet, see documentation such as the
W3Schools.com CSS tutorial.
4 Save the style sheet.
Related Examples
• “Add Holes in an HTML Template” on page 13-124
• “Create a Microsoft Word Template” on page 13-111
13-127
13 Create a Report Program
You can divide a Word document into one or more sections, each with its own page
layout. Page layout includes page margins, page orientation, and headers and footers.
You can use the moveToNextHole function to move from section to section and from hole
to hole within a section. At each section hole, the DOM API sets a document or document
part CurrentDOCXSection property to the DOCXSection object associated with that
object. The DOCXSection object reflects the properties of the current section, as defined
in the template. For example, if you have defined the page orientation of that section to
be portrait, the page orientation is set as portrait in the current DOCXSection object.
You can change the template-defined section properties programmatically. For example,
the page orientation of the DOM default Word template is portrait. This example shows
how to change the orientation to landscape to accommodate wide tables. The code swaps
the height and width of the page to reflect the new page orientation.
import mlreportgen.dom.*
13-128
Create Microsoft Word Page Layout Sections
rpt = Document('test','docx');
open(rpt);
sect = rpt.CurrentDOCXSection;
pageSize = sect.PageSize;
pageSize.Orientation = 'landscape';
saveHeight = pageSize.Height;
pageSize.Height = pageSize.Width;
pageSize.Width = saveHeight;
table = append(rpt,magic(22));
table.Border = 'solid';
table.ColSep = 'solid';
table.RowSep = 'solid';
close(rpt);
rptview(rpt.OutputPath);
paraObj = append(rptObj,paraObj,docxSectionObj)
This us of the append function appends a paragraph to the report as the last paragraph
of the current section and then starts a new section whose properties are defined by a
DOCXSection object. For example, this script adds a landscape section to a report to
accommodate a large magic square.
import mlreportgen.dom.*
rpt = Document('test','docx');
sect = DOCXSection;
sect.PageSize.Orientation = 'landscape';
sect.PageSize.Height = '8.5in';
sect.PageSize.Width = '11in';
append(rpt,Paragraph('The next page shows magic square.'),sect);
13-129
13 Create a Report Program
table = append(rpt,magic(22));
table.Border = 'solid';
table.ColSep = 'solid';
table.RowSep = 'solid';
close(rpt);
rptview(rpt.OutputPath);
See Also
Classes
mlreportgen.dom.DOCXPageMargins | mlreportgen.dom.DOCXPageSize |
mlreportgen.dom.DOCXSection
Related Examples
• “Create a Microsoft Word Template” on page 13-111
13-130
Create Page Footers and Headers
You can create as many as three page headers and three page footers for a Word report
section:
You can create report page headers and footers programmatically or in the template used
to create a report or report part. You can append content to both template-defined and
programmatically defined headers and footers.
1 Reads the headers and footers from the template and converts them to
DOCXPageHeader and DOCXPageFooter objects, respectively
2 Associates the headers and footer objects with the DOCXSection object that defines
the properties of the section that contains the headers and footers
3 Adds the headers and footers to your report as your code navigates the sections
defined by the template
As your report generation program navigates the sections, it can append content to the
template-defined headers and footers.
To append content to a template-defined header or footer, you need to access it. Use the
CurrentDOCXSection property of a Document or DocumentPart object to access the
13-131
13 Create a Report Program
template-defined headers and footers for the current section of a document or document
part.
You can use the DOM API to append content to a template-defined header or footer
that appears on every page in a section. To append content to a header or footer in the
current section of a document or document part, first use the document or document part
CurrentDOCXSection property to access the DOCXPagerHeader or DOCXPageFooter
object. Then use the append method of a DOCXPageHeader or DOCXPageFooter object
to append content to the header or footer. Because header and footer objects are a kind
of document part object, you can append any kind of content to a page header or footer
that you can append to a document part, for example, images and tables as well as
paragraphs.
You can use holes in the header and footers of your main template to control the
positioning of content that you append to the headers and footers. For example, this
script appends today's date to a hole named Date on the first template-defined page
header of the first section of a report. This example assumes that the Word template
MyReportTemplate has one section that defines a first page, odd page, and even page
header and footer.
import mlreportgen.dom.*;
d = Document('MyReport','docx','MyReportTemplate');
open(d);
sect = d.CurrentDOCXSection;
for i = 1:numel(sect.PageHeaders)
if strcmpi(sect.PageHeaders(i).PageType,'first')
firstPageHeader = sect.PageHeaders(i);
while ~strcmp(firstPageHeader.CurrentHoleId,'#end#')
13-132
Create Page Footers and Headers
switch firstPageHeader.CurrentHoleId
case 'Date'
append(firstPageHeader,date);
end
moveToNextHole(firstPageHeader);
end
break;
end
end
close(d);
rptview(d.OutputPath);
Generate Header and Footer Content That Varies from Page to Page
You cannot programmatically append to headers and footers content that varies from
page to page, such as page numbers or running heads. To create content that varies, use
Word fields, which enable automatic content generation. For example, to include a page
number on each page of a section of your report, insert a page number field in the report
template in the page footer of a section. For more information, see the Microsoft Word
documentation.
This script creates a first page header from a template stored in the document part
template library of a report.
import mlreportgen.dom.*;
d = Document('MyReport','docx','MyReportTemplate');
open(d);
13-133
13 Create a Report Program
pageHeaders(1) = DOCXPageHeader('first',d,'FirstPageHeader');
while ~strcmp(pageHeaders(1).CurrentHoleId,'#end#')
switch pageHeaders(1).CurrentHoleId
case 'Date'
append(pageHeaders(1),date);
end
moveToNextHole(pageHeaders(1));
end
d.CurrentDOCXSection.PageHeaders = pageHeaders;
close(d);
rptview(d.OutputPath);
See Also
Functions
mlreportgen.dom.Document.createTemplate
Classes
mlreportgen.dom.Document | mlreportgen.dom.DocumentPart |
mlreportgen.dom.DOCXPageFooter | mlreportgen.dom.DOCXPageHeader |
mlreportgen.dom.DOCXSection
Related Examples
• “Create a Microsoft Word Template” on page 13-111
• “Create an HTML Template” on page 13-122
13-134