mlreportgen.dom.TemplateText Class

Namespace: mlreportgen.dom

Markup text from a document template

Description

Use an object of the mlreportgen.dom.TemplateText class to create a Document Object Model (DOM) representation of the XML markup read from the template of the document on opening. The object contains one of these segments of template text occurring between:

• the beginning of the template and the first hole in the template

• subsequent holes in the template

• the last hole and the end of the template

Moving from hole to hole causes these segments of text to be embedded in TemplateText objects and appended to the document's list of children. This guarantees that the template text will be included in the output document in the same order in which it occurs in the template interspersed with the content appended at each hole.

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

Class Attributes

HandleCompatible

true

For information on class attributes, see Class Attributes.

Properties

DOCXText — Microsoft^® Word XML markup text to output to a Word document

"" (default) | character vector | string scalar

Word XML markup text to output to a Word document, specified as a character vector or string scalar. If the document is of type "docx", it includes the value of this property. The markup must be valid Word XML markup that can be inserted into the w:body, w:p, or w:tc element of a Word document.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

HTMLText — HTML markup text to output to an HTML document

"" (default) | character vector | string scalar

HTML markup text to output to an HTML document, specified as a character vector or string scalar. If the document is of type "html", "html-file", or "html-multipage", it includes the value of this property. The text must be valid HTML markup that can be inserted into a body, p, or td element of an HTML document.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

PDFText — Formatting Objects markup to output to a PDF document

"" (default) | character vector | string scalar

Formatting Objects markup to output to a PDF document, specified as a character vector or string scalar. If the document is of type "pdf" or "pdfa" (since R2025a), it includes the value of this property. The value of this property must be valid Formatting Objects (FO) markup that can be inserted into a fo:flow, fo:block, or fo:table-cell element of the FO representation of PDF document content. For more information on FO, see https://www.w3.org/TR/xsl11/.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Parent — Parent of this object

document element object

Parent of this object, specified as a document element object. A document element must have only one parent.

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

clone

copiedObj = clone(soureceObj) returns a copy of the mlreportgen.dom.TemplateText object specified by soureceObj. The copy includes the children of the source object, but not the parent. Note Do not append the same object to a document more than once. Use clone to create a copy when you want to reuse the same content elsewhere in a document. Input Arguments soureceObj — Object to clone, specified as an mlreportgen.dom.TemplateText object Return Values copiedObj— Object copy, returned as an mlreportgen.dom.TemplateText object For more information, see the equivalent method for the mlreportgen.dom.Paragraph class, clone. Example: Update Template by Creating New TemplateDocumentPart from Existing TemplateDocumentPart

Examples

Replace Title Bar Text

import mlreportgen.dom.*;
d = Document('test');
d.TitleBarText = 'My Report';
open(d);
% Display browser title bar text that the DOM template parser inserts into
% the markup read from the beginning of the template.
disp(d.Children(2).HTMLText);

My Report

close(d);
rptview(d);

Update Template by Creating New TemplateDocumentPart from Existing TemplateDocumentPart

To add additional content or holes, or to change the styling in an existing template, create a new TemplateDocumentPart object to replace the existing TemplateDocumentPart object. You can replace the relevant document part while the rest of the source template content remains unchanged.

Use tmplview to display the template document part,"partToModify", in the source template. This document part currently contains the static text "Text in template document part" followed by a template hole, "templateHole". In this example, you add additional text before and after the template hole by finding the part to modify, copying the original text and template hole, and appending your additional text.

tmplview("existingTemplate","html",OpenDocument="partToModify");

Import the DOM API namespace so you do not have to use fully qualified class names.

import mlreportgen.dom.*

Create a template by copying the existing template.

t = Template("updatedTemplate","html","existingTemplate");
open(t);

Find the part to modify in the document parts.

toModifyIdx = strcmp({t.TemplateDocumentParts.Name},"partToModify");
toModifyPart = t.TemplateDocumentParts(toModifyIdx);

Define a new template document part based on the document part.

newTemplateDocPart = TemplateDocumentPart("partToModify");

Copy the children of the original template document part into the new document part before and after the template hole. When your for loop reaches the template hole, add the first line of new text, copy the template hole, and then add the second line of new text.

for child = toModifyPart.Children
    % If the child is a template hole
    if isa(child,"mlreportgen.dom.TemplateHole")
        switch child.HoleId       
            case "templateHole"
                append(newTemplateDocPart,...
                    Text("Text before template hole."));
                append(newTemplateDocPart,TemplateHole(child.HoleId));
                append(newTemplateDocPart,...
                    Text("Content after template hole"));
            otherwise
                append(newTemplateDocPart,TemplateHole(child.HoleId))
        end
        % If the child is not the template hole, copy the child to 
        % the new document part
    else  
        append(newTemplateDocPart,clone(child));
    end
end

Replace the part to modify with the new template document part.

t.TemplateDocumentParts(toModifyIdx) = newTemplateDocPart;

Close the template.

close(t);

Confirm the changes to the template document part by using tmplview.

tmplview("updatedTemplate.htmtx",OpenDocument="partToModify");

To learn how to examine the source or updated template file directly, see Open Template Files.

Tips

• To learn how to examine the source or updated template file directly, see Open Template Files.

Version History

Introduced in R2014b