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
creates a documentObj
= mlreportgen.dom.DocumentDocument
object with default property values, which
specify an output file named Untitled.htmx
in the current
folder, using the default HTML template.
specifies the path and name of the output file and sets the OutputPath property to documentObj
= mlreportgen.dom.Document(outputPath
)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 |
---|---|---|
|
| Generates the report as a zip file at the location
specified by the |
"unzipped" |
| Generates the report as separate files in a folder that has
the file name of the |
"both" |
| Generates zipped and unzipped outputs. |
"single-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 |
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" |
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
, orAutoNumber
.A block hole can contain a
Paragraph
,Table
,OrderedList
,UnorderedList
,DocumentPart
, orGroup
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 R2014bR2024a: 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.
Comando MATLAB
Hai fatto clic su un collegamento che corrisponde a questo comando MATLAB:
Esegui il comando inserendolo nella finestra di comando MATLAB. I browser web non supportano i comandi MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)