Main Content

mlreportgen.dom.Template class

Package: 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.

example

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

expand all

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

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.

Data Types: char

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. If this property is false and a writable file of the same name exists, attempting to close (i.e., write) this template 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.

Data Types: char

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.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Data Types: char | string

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

Path of the output file or folder, specified as a character vector. If you do not specify the file extension, the DOM adds an extension based on the document format. 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.

Data Types: char

Packaging for output files generated, specified as one of these values:

  • 'zipped' — Applies only to Word, PDF, and multifile HTML output.

  • 'unzipped' — Applies only to Word, PDF, and multifile HTML output.

  • 'both' — Applies only to Word, PDF, and multifile HTML output.

  • 'single-file' — Creates the report as a single file. This value appears if you set the document’s Type property to 'html-file'. You cannot set or change this value yourself.

For zipped packaging, the document output is a zip file located at the location specified by the OutputPath property. The zip file has the extension that matches the document type: docx for Word output, pdftx for PDF 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.

For unzipped packaging, the document output is stored in a folder having the root file name of the OutputPath property. For example, if the OutputPath is s:\docs\MyDoc, the output folder is s:\docs\MyDoc.

If you set PackageType to both, generating the report produces zipped and unzipped output.

Data Types: char

Tag that identifies this document. The tag has the form CLASS:ID, where CLASS is the document class and ID is the value of the Id property of the object.

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.

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 template to create, specified as a string scalar or character vector, that can optionally include the file extension. The file extension can be one of these values:

ExtensionFile Type
.htmtx

Compressed HTML

.docx

Microsoft Word

.htmt

single-file HTML

.pdf

PDF

Data Types: string | char

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.

Data Types: char

Output file type, specified as a string scalar or character vector with one of these values:

ValueFile Type
"htmtx"

Compressed HTML

"docx"

Microsoft Word

"html"

single-file HTML

"pdf"

PDF

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

  • 'docx' — Word output

  • 'html-file' — HTML output consisting of a single file that contains the text, style sheets, JavaScript, and images for the report

  • 'pdf' — PDF output

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

Data Types: string | char

Methods

expand all

Examples

collapse all

Open Live Script

Create a template with a hole for the title and a hole for the author and append content to each hole.

Create the template

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

import mlreportgen.dom.*;

Specify the type of template and create a template object. To create a template of a different type, change the value of the type variable.

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 style.

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

Use the template

Create a document TitleAuthor that uses the template mytemplate.

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

Create a loop to cycle through the holes and 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