mlreportgen.dom.Document class

Package: mlreportgen.dom
Superclasses:

Document container

expand all in page

Description

Create mlreportgen.dom.Document object that defines:

  • The type of output: HTML, Microsoft® Word, or PDF.

  • Where and how to store the output.

  • The template to use to format the document.

Construction

documentObj = Document() creates an HTML document named Untitled.htmx in the current directory, using the default HTML template.

Append content and use a corresponding close command to generate the document.

documentObj = Document(outputPath) creates an HTML document at the specified location.

documentObj = Document(outputPath,type) creates a document of the specified type (for example, Word), using the default template for that type.

documentObj = Document(outputPath,type,templatePath) creates a document, using the specified document type and Word, PDF, or HTML template corresponding to the type setting.

Input Arguments

expand all

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). You can set this property only before opening the document.

How you specify the path depends on the value of the PackageType property.

  • 'zipped' — Name of zip file.

  • 'unzipped' — Folder for the output files.

  • 'both' — Name of zip file.

Data Types: char

Type of output, specified as 'html', 'docx', 'pdf', or 'html-file'.

  • 'html'— HTML output as a zipped or unzipped folder containing the HTML document text, image, style sheet, and JavaScript® files.

  • 'docx'— Word output.

  • 'pdf'— PDF document based on a PDF template.

  • '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 input argument, the template must be consistent with the type argument.

Full path of a custom template file or folder, specified as a character vector. If you omit a file extension, the template type is based on the document type, for example, .docx for Word.

Data Types: char

Output Arguments

expand all

Report definition document, represented by an mlreportgen.dom.Document object.

Properties

expand all

Children of this document element, specified as an array of DOM objects. This property is read-only.

This read-only property is the hole ID of the current hole in this document.

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, AutoNumber.

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

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 [].

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 and a writable file of the same name exists, attempting to close (i.e., write) this document causes an error. If the existing file is read-only, closing this document causes an error regardless of the setting of this property.

Data Types: logical

Custom content for HTML header, specified as a character vector. 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's template. Set this property only before opening the document.

ID for this document element, specified as a character vector or string scalar. The DOM generates a session-unique ID when it creates the document element. You can specify your own ID.

This read-only property lists the open status of this document element.

Path of this document's output file, specified as a character vector. If you do not specify the file extension, the DOM adds an extension based on the output type of the document. You can set this property only before opening the document.

For unzipped output packaging, the path specifies the folder for the output files. The default is the current folder.

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.

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

ValueSupported Report TypesDescription

'zipped'

'docx'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' 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' or 'html'

Generates zipped and unzipped outputs.

'single-file'

'pdf' or 'html-file'

Generates the report as a single file.

When the Type property is 'html', 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.

Parent of this document element, specified as a DOM object. This property is read-only.

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

Tag for this document, in the form CLASS:ID, where CLASS is the document class and ID is the value of the Id property of the object. You can specify a custom tag as a character vector.

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 template to use, specified as a character vector.

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 for output.

Type of output, specified as 'html', 'docx', 'pdf', or 'html-file'.

  • 'html' — HTML output as a zipped or unzipped folder containing the HTML document text, image, style sheet, and JavaScript files.

  • 'docx' — Word output.

  • 'pdf' — PDF 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, a PDF template package (.pdftx) for PDF output, and a single-file HTML template (.htmt) for html-file output.

Methods

Method

Purpose

addHTML

Append HTML text to document

addHTMLFile

Append HTML file contents to document

append

Append document element to the document

close

Close this document. You cannot close a document if it has not been opened or was previously closed

createAutoNumberStream

Create automatically generated numbering stream

mlreportgen.dom.Document.createTemplate

Create document template

fill

Fill document hole

getAutoNumberStream

Get the automated numbering stream

mlreportgen.dom.Document.getCoreProperties

Get core properties of document

mlreportgen.dom.Document.getImageDirectory

Get image folder of document

mlreportgen.dom.Document.getImagePrefix

Get generated image name prefix

getMainPartPath

Get relative path of main part of output document

mlreportgen.dom.Document.getOPCMainPart

Get full path of main part of output document

moveToNextHole

Move to next template hole

open

Open this document. You cannot open a document if it was previously opened or closed

package

Append file to OPC package of document

mlreportgen.dom.Document.setCoreProperties

Set core properties of document element

Examples

collapse all

Open Script

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.OutputPath);

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.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 the document and view it.

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

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

close(d); 
rptview(d.OutputPath);

See Also

MATLAB Report Generator Documentation

Support