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 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
creates a template object and sets the TemplatePath property to
templateObj
= mlreportgen.dom.TemplateUntitled.htmtx
.
creates a template object and sets the TemplatePath property to templateObj
= mlreportgen.dom.Template(templatePath
)templatePath
.
If templatePath
does not include a file extension, the
Type
property is set to the default value, HTML.
also sets the Type
property to templateObj
= mlreportgen.dom.Template(templatePath
,fileType
)fileType
. If
templatePath
includes a file extension, then
fileType
must match the file extension specified by
templatePath
.
creates a template object based on the template specified by
templateObj
= mlreportgen.dom.Template(templatePath
,fileType
,sourceTemplatePath
)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:
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 |
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
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
OpenStatus
— Open status of document element
'unopened'
(default) | 'open'
| 'closed'
Open status of this document, specified as 'unopened'
,
'open'
, or 'closed'
.
Attributes:
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™, 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
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 |
Note
This property cannot be changed after a document has been opened for output.
Attributes:
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:
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
Children
— Children of mlreportgen.dom.Template
object
array of document element objects
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
— Tag for mlreportgen.dom.Template
object
character vector | string scalar
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
Id
— Object identifier for mlreportgen.dom.Template
object
character vector | string scalar
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
Public Methods
Use the Template
methods the same way you use
the corresponding Document
methods.
Method | Purpose |
---|---|
Append document element to the document. | |
Close this document. You cannot close a document if it has not been opened or was previously closed. | |
Create default template. | |
Fill document hole. | |
Get core properties of document. | |
Get image directory for the document. | |
Get generated image name prefix for the document. | |
Get relative path of main part of output document. | |
Get full path of main part of output document. | |
Move to next template hole. | |
Open this document. You cannot open a document if it was previously opened or closed. | |
Append file to OPC package of document. | |
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
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)