mlreportgen.dom.Template class

Package: mlreportgen.dom
Superclasses:

Create report template object

Description

Create a report template object.

Use mlreportgen.dom.Template objects to create templates. For example, you can append DOM content (e.g., Text, Paragraph, Image) objects and TemplateHole objects) to a Template object to create a template containing fixed content with holes for generated content.

Note

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 on Windows^® to create your template and copy the template to your Mac.

Construction

templateObj = Template() creates a template object based on the default HTML template. The resulting template is in the current folder and uses the name Untitled.htmtx.

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

templateObj = Template(templatePath) creates a template object that outputs a template file at the specified location. The default template type if you do not specify an extension is HTML.

templateObj = Template(templatePath,type) creates the template of the specified type. If you specify an extension using templatePath, the types must match.

Tip

Use a variable for the type argument to simplify your code. See Create a Template and Add Content for an example.

templateObj = Template(templatePath,type,sourceTemplatePath) creates a template based on the template sourceTemplatePath.

Input Arguments

templatePath — Template to create

character vector

Full path of template you want to create, specified as a character vector. You can use an extension to create a template of the corresponding type:

• .htmtx for HTML ( default)

• .docx for Word

• .htmt for single-file HTML

• .pdf for PDF

type — Type of template

'html' (default) | 'docx' | 'html-file'

Type of template, specified as one of these values:

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

• 'docx'— Word template

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

• .pdf — PDF template

If you use an extension with the templatePath input argument, the type argument must match.

sourceTemplatePath — Basis for new template

character vector

Template that is the basis for the new template, specified as a character vector. The source template type must match the type argument.

Output Arguments

templateObj — Template object to create

mlreportgen.dom.Template object

Template to create, returned as an mlreportgen.dom.Template object.

Properties

Children — Children of document element

array of DOM objects

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

CurrentHoleId — ID of current hole in document

character vector

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

CurrentHoleType — Type of current hole

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

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

CurrentPageLayout — Current page layout of this document

mlreportgen.dom.DOCXPageLayout object | mlreportgen.dom.PDFPageLayout object

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

ForceOverwrite — Option to overwrite existing output file

[] (default) | logical value

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

HTMLHeadExt — Custom content for HTML header

character vector

Custom content for HTML header, specified as a character vector.

Data Types: char

Id — ID for this document element

character vector | string scalar

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.

OpenStatus — Open status of document element

unopened (default) | open | closed

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

OutputPath — Path of output file or folder

character vector

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.

PackageType — Packaging for files generated

'zipped' (default) | 'unzipped' | 'both' | 'single-file'

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

StreamOutput — Option to stream output to disk

false (default) | logical value

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 — Tag for this document

session-unique tag (default) | character vector

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.

TemplatePath — Path of the template to use

character vector

The full path to the HTML or Word template to use, specified as a character vector.

TitleBarText — Title for HTML browser title bar

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 — Type of output

'html' (default) | 'docx' | 'html-file''pdf'

Type of output, specified as one of these values:

• '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.

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.

import mlreportgen.dom.*;

type = 'docx';

% Create a template object
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
% Position the paragraph and preserve white space in the text 
p = Paragraph('Author: ');
p.StyleName = 'Subtitle';
p.Style = {OuterMargin('0','0','1in','1in')};
p.WhiteSpace = 'preserve';

% Append an inline hole to paragraph  
hole = append(p,TemplateHole('AUTHOR'));
append(t,p);

close(t);

This example uses the template to fill the 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)