mlreportgen.dom.Document Class

Namespace: mlreportgen.dom

Document container

Description

Use an object of the mlreportgen.dom.Document class to represent a Document Object Model (DOM) document. Use Document object properties to specify:

• Whether to generate an HTML, Microsoft^® Word, or PDF document

• Where and how to store the generated document

• The template to use to format the document

The mlreportgen.dom.Document class is a handle class.

Class Attributes

ConstructOnLoad	true
HandleCompatible	true

For information on class attributes, see Class Attributes.

Creation

Description

documentObj = mlreportgen.dom.Document creates a Document object with default property values, which specify an output file named Untitled.htmx in the current folder, using the default HTML template.

documentObj = mlreportgen.dom.Document(outputPath) specifies the path and name of the output file and sets the OutputPath property to outputPath.

documentObj = mlreportgen.dom.Document(outputPath,type) also specifies the output type and sets the Type property to type.

documentObj = mlreportgen.dom.Document(outputPath,type,templatePath) also specifies the path and name of the template file and sets the TemplatePath property to templatePath.

Properties

OutputPath — Path of output file or folder

"untitled" (default) | character vector | string scalar

Path of the output file or folder, specified as a character vector or string scalar. The default value is the path of a file or folder named untitled in the current folder. The path can be a full path, for example, "C:/myreports/reportA.docx". The path can also be relative to the current MATLAB folder, for example, "reportA". If you do not specify the file extension, the DOM adds an extension based on the document Type property. You can set this property only before opening the document.

Whether OutputPath specifies the path of a file or folder depends on the value of the PackageType property, as shown in the table.

PackageType	OutputPath Value
"zipped" or "single-file"	Path and name of ZIP file or single file
"unzipped"	Folder for the unzipped files
"both"	Path and name of ZIP file and folder for the unzipped files

Note

Generating a PDF report on a cloud drive, such as MATLAB^® Drive™, can result in an error that is caused by file contention between the report generation software and the cloud drive synchronization software. To avoid this error, generate reports on a local drive that does not synchronize with the cloud. Consider writing a script that generates a report on a local drive and then copies the report to the cloud drive.

Attributes:

NonCopyable

true

Data Types: char | string

PackageType — Packaging for files generated

"zipped" (default) | "unzipped" | "both" | "single-file"

Packaging used for the generated files, specified as one of the values in the table.

Value	Supported Report Types	Description
"zipped"	"docx", "html-multipage", or "html"	Generates the report as a zip file at the location specified by the OutputPath property. The zip file has an extension that matches the document type (docx for Word output or htmtx 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.
"unzipped"	"docx", "html-multipage", or "html"	Generates the report as separate files in a folder that has the file name of the OutputPath property. For example, if the OutputPath is s:\docs\MyDoc, the output folder is s:\docs\MyDoc.
"both"	"docx", "html-multipage", or "html"	Generates zipped and unzipped outputs.
"single-file"	"pdf" or "html-file"	Generates the report as a single file.

Tip

When the Type property is "html" or "html-multipage", to generate an HTML report that you can open without unzipping, set PackageType to "unzipped" or "both". In the folder that contains the generated files, open the root.html file.

Attributes:

NonCopyable

true

Data Types: char | string

ForceOverwrite — Option to overwrite existing output file

true (default) | false

Whether to overwrite an existing output file, specified as true or false. Set this property to true to overwrite an existing output file with the same name. If this property is false and a writable file with the same name exists, closing this document causes an error. If the existing file is read-only, closing this document causes an error regardless of this property setting.

Attributes:

NonCopyable

true

Data Types: logical

StreamOutput — Option to stream output to disk

false (default) | true

Option to stream the output to disk, specified as true or false. By default, document elements are stored in memory until the document is closed. Set this property to true to write the document elements to disk as the elements are appended to the document.

Attributes:

NonCopyable

true

Data Types: logical

TitleBarText — Text for HTML browser title bar

'' (default) | character vector | string scalar

Text for the HTML browser title bar, specified as a character vector or string scalar. For HTML documents, this property specifies the text that appears in the title bar of the browser used to display this document. Word and PDF documents ignore this property.

Set this property before opening the document.

Attributes:

NonCopyable

true

Data Types: char | string

HTMLHeadExt — Custom content for HTML header

'' (default) | character vector | string scalar

Custom content for the HTML header, specified as a character vector or string scalar. The value of this property is appended to the <head> element of this document after the content specified by the head section of the document template. Set this property only before opening the document.

Attributes:

NonCopyable

true

Data Types: char | string

TemplatePath — Path of template to use

character vector | string scalar

Full path of the template to use that can optionally include the file extension, specified as a character vector or string scalar. The file extension can be one of these values:

Extension	File Type
.htmtx	Zipped HTML
.dotx	Microsoft Word
.htmt	Single-file HTML
.pdfx	PDF

Note

This property cannot be changed after a document has been opened for output.

Attributes:

NonCopyable

true

Data Types: char | string

Type — Output file type

"html" (default) | "docx", | "html-file" | "html-multipage" | "pdf"

Output file type, specified as one of these values:

Value	File Type
"docx"	Microsoft Word
"html"	HTML output as a zipped or unzipped folder containing the HTML document text, image, style sheet, and JavaScript® files
"html-file"	HTML output consisting of a single file that contains the text, style sheets, JavaScript, and images for the report
"html-multipage" (since R2024a)	HTML output as a zipped or unzipped folder containing the HTML document text divided into multiple pages, image, style sheet, and JavaScript files
"pdf"	PDF

If you specify a template using the TemplatePath property, the template must be consistent with the Type property.

Attributes:

NonCopyable

true

Data Types: char | string

CurrentHoleId — ID of current hole in document

'' (default) | character vector | string scalar

ID of the current hole in the document, specified as a character vector or string scalar.

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

CurrentHoleType — Type of current hole

'' (default) | "Inline" | "Block"

Type of the current template hole, specified as "Inline" or "Block".

• An inline hole is for document elements that a paragraph element can contain: Text, Image, LinkTarget, ExternalLink, InternalLink, CharEntity, or AutoNumber.

• A block hole can contain a Paragraph, Table, OrderedList, UnorderedList, DocumentPart, or Group element.

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

CurrentPageLayout — Current page layout of this document

[] (default) | mlreportgen.dom.DOCXPageLayout object | mlreportgen.dom.PDFPageLayout object | []

Current page layout of this document, specified as an mlreportgen.dom.DOCXPageLayout object, mlreportgen.dom.PDFPageLayout object, or []. This property applies to Word and PDF documents. For Word documents, the value is a DOCXPageLayout object that specifies the current page layout. For PDF documents, the value is a PDFPageLayout object if the document currently specifies a page layout. For HTML documents, the value is always [].

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

OpenStatus — Open status of document

'unopened' (default) | 'open' | 'closed'

Open status of this document, specified as 'unopened', 'open', or 'closed'.

Note

If a mlreportgen.dom.Document object's OpenStatus property is "open" and you call rptview to view the report, OpenStatus will be set to "closed". Displaying a report requires executing the DOM API"s close command, which converts the report"s in-memory DOM representation to a file of the type specified by the Type property. rptview issues the required close command for you if Document.OpenStatus is not ready set to "closed" .

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

EndnoteOptions — Document endnote options

[] (default) | mlreportgen.dom.EndnoteOptions object

Since R2024a

Document endnote options, specified as an mlreportgen.dom.EndnoteOptions object. The document uses the default value if any property of EndnoteOptions is empty.

Note

If a page layout specifies endnote options, the page layout endnote options override the document endnote options specified here.

Attributes:

NonCopyable

true

FootnoteOptions — Document footnote options

[] (default) | mlreportgen.dom.FootnoteOptions object

Since R2024a

Document footnote options, specified as an mlreportgen.dom.FootnoteOptions object. The document uses the default value if any property of FootnoteOptions is empty.

Note

If a page layout specifies footnote options, the page layout footnote options override the document footnote options specified here.

Attributes:

NonCopyable

true

Parent — Parent of this mlreportgen.dom.Document object

document element object

Parent of this document element, specified as a document element. A document element may only have one parent.

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Children — Children of this mlreportgen.dom.Document object

document element object

Children of this document element, specified as an array of document element objects. Elements appended using the append method are added here.

Attributes:

SetAccess	private
Transient	true
NonCopyable	true

Tag — Tag for mlreportgen.dom.Document object

character vector | string scalar

Tag for the mlreportgen.dom.Document object, specified as a character vector or string scalar. The DOM API generates a session-unique tag as part of the creation of this object. The generated tag has the form CLASS:ID, where CLASS is the object class and ID is the value of the Id property of the object. Specify your own tag value to help you identify where to look when an issue occurs during document generation.

Attributes:

NonCopyable

true

Data Types: char | string

Id — Object identifier for mlreportgen.dom.Document object

character vector | string scalar

Object identifier for the mlreportgen.dom.Document object, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object. You can specify your own value for Id.

Attributes:

NonCopyable

true

Data Types: char | string

Methods

Public Methods

addHTML	Append HTML string to document
addHTMLFile	Append HTML file contents to document
append	Append DOM or MATLAB object to document
close	Close document
createAutoNumberStream	Create numbering stream
mlreportgen.dom.Document.createTemplate	Create DOM template file
fill	Fill document holes with generated content
getAutoNumberStream	Return numbering stream
mlreportgen.dom.Document.getCoreProperties	Get document or template core properties
mlreportgen.dom.Document.getImageDirectory	Get image folder of document
mlreportgen.dom.Document.getImagePrefix	Get generated image name prefix
getMainPartPath	Return path of main part of document output package
mlreportgen.dom.Document.getOPCMainPart	Return main part of document, document part, or template
moveToNextHole	Move document append point to next template hole
open	Open document
package	Add OPC part files to document package
mlreportgen.dom.Document.setCoreProperties	Set OPC core properties of output document or template

Examples

Create a Word Document

Create a Word document, add content, and view the report in Word.

import mlreportgen.dom.*;
d = Document("mydoc","docx");

append(d,"Hello World");

close(d);
rptview(d);

Create an HTML Document as a Single File

Create an HTML document as a single HTML file that includes an image. The example assumes that there is a MyImage.jpg file and a myHTMLTemplate.htmt HTML template file.

Create a document whose output is a single HTML file and uses the template myHTMLTemplate. Add text and an image to the report. Close and view the document.

import mlreportgen.dom.*;
d = Document("mydoc","html-file","myHTMLTemplate.htmt"); 
open(d); 

append(d,"Hello world"); 
append(d,Image("C:/images/LocalSystem/MyImage.jpg"));

close(d); 
rptview(d); 

Version History

Introduced in R2014b

R2024a: Footnote and Endnote support in DOM API

The DOM API supports both footnotes, mlreportgen.dom.Footnote, and endnotes, mlreportgen.dom.Endnote. Options for these are set using the mlreportgen.dom.FootnoteOptions and mlreportgen.dom.EndnoteOptions classes. You can customize both the numbering and styling of the footnote and endnotes. Footnotes and endnotes are available for Microsoft Word and PDF output formats.