mlreportgen.dom.Template Class

Namespace: mlreportgen.dom
Superclasses: mlreportgen.dom.Document

Create report template object

Description

Use mlreportgen.dom.Template objects to create report templates. For example, you can append DOM content, such as Text, Paragraph, or Image objects, and TemplateHole objects to a mlreportgen.dom.Template object to create a template containing fixed content with holes for generated content.

Note

Microsoft^® Word for Mac does not support creating holes for DOM API templates. To create a Word template for generating Word documents on a Mac, use one of these approaches:

• Create a mlreportgen.dom.Template object and use the mlreportgen.dom.TemplateHole class to add holes.

• Create your template in Word on Windows^® and copy the template to your Mac.

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

Creation

Description

templateObj = mlreportgen.dom.Template creates a template object and sets the TemplatePath property to Untitled.htmtx.

templateObj = mlreportgen.dom.Template(templatePath) creates a template object and sets the TemplatePath property to templatePath. If templatePath does not include a file extension, the Type property is set to the default value, HTML.

templateObj = mlreportgen.dom.Template(templatePath,fileType) also sets the Type property to fileType. If templatePath includes a file extension, then fileType must match the file extension specified by templatePath.

templateObj = mlreportgen.dom.Template(templatePath,fileType,sourceTemplatePath) creates a template object based on the template specified by sourceTemplatePath.

Input Arguments

sourceTemplatePath — Base for new template

character vector | string scalar

Path to the template to use as the base for the new template, specified as a character vector or string scalar. The source template type must match the fileType argument.

Properties

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:

GetAccess	public
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:

GetAccess	public
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:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

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:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: logical

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:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

OpenStatus — Open status of document element

"unopened" (default) | "open" | "closed"

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

Attributes:

GetAccess	public
SetAccess	private
Transient	true
NonCopyable	true

Data Types: char | string

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™ or Microsoft OneDrive™, can cause file contention between the report generation software and the cloud drive synchronization software resulting in a version of this error:

Error closing document package: Could not commit changes: removeAll failed: fl:filesystem:AccessDenied: 
C:\Users\jdoe\OneDrive\Documents\MATLAB\reports\temp_FO\stylesheets: Permission denied.

To avoid this issue, 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:

GetAccess	public
SetAccess	public
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 these values:

Value	Supported Report Types	Description
"zipped"	"docx" "html" "html-multipage" (since R2024a)	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" "html-multipage" (since R2024a)	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" "html-multipage" (since R2024a)	Generates zipped and unzipped outputs.
"single-file"	"html-file" "pdf" "pdfa" (since R2025a)	Generates the report as a single file.

Tip

When the Type property is "html" or "html-multipage" (since R2024a), 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:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Stylesheet — Stylesheet to apply to template object

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

Object of type mlreportgen.dom.TemplateStylesheet that represents the template's stylesheet. The stylesheet contains style definitions that can be used to format report elements such as paragraphs, lists, and tables. The styles can be used by the main template body, document part templates, or other documents that use the template generated from this template object. When this Template is opened using the open method, the stylesheet object is created and automatically populated with styles that are present in the template on which this Template is based. Use the Stylesheet property to access and modify existing styles and add new styles. When the Template object is closed, the styles are written to the output template package (HTML, PDF, DOCX) or template document (HTML-FILE).

Attributes:

SetAccess	private
NonCopyable	true

TemplateDocumentParts — Document parts to use in template objects

[] (default) | array of mlreportgen.dom.TemplateDocumentPart objects

Document parts to use in template objects, specified as an array of mlreportgen.dom.TemplateDocumentPart objects to include in the template. When you close the Template object, Report Generator writes these document part templates to the output template package (HTML, PDF, DOCX) or template document (HTML-FILE). If the template document that the Template object is using contains any document parts, Report Generator automatically populates this property with TemplateDocumentPart objects that contain DOM representations of the existing document parts when the Template object is opened.

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:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

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:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Type — Output file type

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

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
"pdfa" (since R2025a)	PDF/A

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

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Children — Children of this object

array of document element objects

Children of this object, specified as an array of document element objects. This property contains the document element objects appended using the append method.

Attributes:

GetAccess	public
SetAccess	private
NonCopyable	true

Tag — Tag

character vector | string scalar

Tag, 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. Use this value to help identify where an issue occurs during document generation.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Id — Object identifier

character vector | string scalar

Object identifier, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Methods

Public 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. You cannot close a document if it has not been opened or was previously closed.
mlreportgen.dom.Document.createTemplate	Create default template.
fill	Fill document hole.
mlreportgen.dom.Document.getCoreProperties	Get core properties of document.
mlreportgen.dom.Document.getImageDirectory	Get image directory for the document.
mlreportgen.dom.Document.getImagePrefix	Get generated image name prefix for the document.
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

Create a Template and Add Content

This example creates a template with a hole for the title and a hole for the author. You can change the value of the type variable to create a template of one of the other types.

Create the template

Import the mlreportgen.dom namespace so that you do not have to include the fully qualified name when you call the object constructors and methods.

import mlreportgen.dom.*;

Specify the type of template and create a template object.

type = "docx";
t = Template("mytemplate",type);

Add a title hole to the template and apply the Title style.

hole = append(t,TemplateHole("TITLE"));
hole.Description = ("Title Description");
hole.DefaultHoleStyleName = "Title";

Add a paragraph with boilerplate text and apply the Subtitle format.

p = Paragraph("Author: ");
p.StyleName = "Subtitle";

Position the paragraph and preserve white space in the text.

p.Style = {OuterMargin("0","0","1in","1in")};
p.WhiteSpace = "preserve";

Append an inline hole to the paragraph.

hole = append(p,TemplateHole("AUTHOR"));
append(t,p);

Close your created template object.

close(t);

Fill the template holes

Create a document TitleAuthor that uses the template mytemplate.

rpt = Document("TitleAuthor",type,"mytemplate");
open(rpt);

Create a loop to cycle through the holes.

Append content to each hole.

while(~strcmp(rpt.CurrentHoleId,"#end#"))
    switch(rpt.CurrentHoleId)
        case "TITLE"
            append(rpt,Paragraph("This Is My Title"));
        case "AUTHOR"
            append(rpt,"My Name");
    end
    
    moveToNextHole(rpt);
end

Generate and view the report.

close(rpt);
rptview(rpt.OutputPath)

Version History

Introduced in R2014b