Main Content

mlreportgen.dom.Template Class

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

Create report template object

expand all in page

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 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. If you need to create a Word template for generating Word documents on a Mac, you can create a template using the DOM API. Create a Template object and use mlreportgen.dom.TemplateHole to add holes. Alternatively, use Word to create your template 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.

example

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

Input Arguments

expand all

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

expand all

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

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

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

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

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

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

Attributes:

SetAccess
private
Transient
true
NonCopyable
true

Data Types: char | string

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.

PackageTypeOutputPath 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

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

ValueSupported Report TypesDescription

"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

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

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.

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:

ExtensionFile 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

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

Output file type, specified as one of these values:

ValueFile 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

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

Attributes:

SetAccess
private
NonCopyable
true

Tag for the mlreportgen.dom.Template 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

Object identifier for the mlreportgen.dom.Template 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

expand all

Examples

collapse all

Open Live Script

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

See Also

| | | |

Topics