Modifying Templates Programmatically

If you need to update document parts of an existing Document Object Model (DOM) API template, you can choose from several approaches based on the type of changes the template requires. If the changes are minor and you are not likely to have to repeat them, consider making the changes manually on the command line. For more extensive changes or for changes that you may need to perform repeatedly, implement the changes by writing a script. Regardless of your approach, the updated template includes all unmodified document parts from the source template.

Some common reasons to modify a template:

• Adding additional content or holes or changing source styling

• Replacing text with other text (especially in PDFs)

• Making a large number of changes beyond adding additional content or changing source styles

You can use tmplview to preview your changes. (since R2024b)

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.

Update Template by Modifying Existing TemplateDocumentPart Object

To update the text within a template document part while leaving the rest of the source template unchanged, you can modify an existing template document part. This approach works best for PDF templates.

Use tmplview to display the template document part,"partToModify", that needs to be modified in the source template. It currently contains the static text "Text in template document part" followed by a template hole, "templateHole".

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 based on the existing template.

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

Find the part to modify in the template's document parts.

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

Modify the document part for PDF output

If the child is a Paragraph object, update the text to "Updated text in template part".

for child = toModifyPart.Children
    if isa(child,"mlreportgen.dom.Paragraph")
        child.Children(1).Content = "Updated text in template part";
    end
end

You can also make other changes, such as changing the style and appending extra content. For example, you could make the text to Bold by using child.Style = [child.Style, {Bold}];. See Use Style Sheet Styles for more information on using styles sheets in a template.

Modify the document part for HTML output

If the child is a TemplateText object and the HTMLtext in that object is "Text in template part", update the text to "Updated text in template part".

for child = toModifyPart.Children
    if isa(child,"mlreportgen.dom.TemplateText")
        child.HTMLText = strrep(child.HTMLText,...
            "Text in template part","Updated text in template part");
    end
end

Close the template.

close(t);

Use tmplview to display the template document part in the updated template. It now contains a new template hole "newTemplateHole" followed by a 2-by-2 table.

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

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

Update Template by Creating New TemplateDocumentPart Object

Update a template by creating a new TemplateDocumentPart object to add additional content to the source template. This is a good approach for making substantial changes to a source template.

Use tmplview to display the template document part,"partToModify", that needs to be modified in the source template. It currently contains the static text "Text in template document part" followed by a template hole, "templateHole".

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 based on the existing template.

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

Find the part to modify in the template's document parts.

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

Create a new template document part.

newTemplateDocPart = TemplateDocumentPart("partToModify");

Append new content to the template document part.

append(newTemplateDocPart, ...
    TemplateHole("newTemplateHole", "Completely new template hole"));
append(newTemplateDocPart, Table([1, 2; 3, 4]));

Replace the old template document part with the new one.

t.TemplateDocumentParts(toModifyIdx) = newTemplateDocPart;

Close the template.

close(t);

Use tmplview to display the template document part in the updated template. It now contains a new template hole "newTemplateHole" followed by a 2-by-2 table.

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

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