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 within an existing template, create a new TemplateDocumentPart object to replace an existing TemplateDocumentPart object. You can replace the relevant document part while the rest of the source template content remains unchanged.

This image represents the template document part "partToModify" from the source template that needs to be replaced. It currently contains the static text Text in template document part followed by a template hole, "templateHole". To add additional text before and after the template hole, you will find the part to modify, copy the original text and template hole and append your additional text.

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

Define a new template document part based on that part.

newTemplateDocPart = TemplateDocumentPart("partToModify");

Copy the children of the old template document part into the new part before and after the template hole. When you get to 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 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
    elseif isa(child,"mlreportgen.dom.TemplateText")
        tt = TemplateText();
        tt.HTMLText = child.HTMLText;
        tt.DOCXText = child.DOCXText;
        tt.PDFText = child.PDFText;
        append(newTemplateDocPart,tt);
    else
        append(newTemplateDocPart,clone(child));
    end
end

Replace the part of modify with your new template document part.

t.TemplateDocumentParts(toModifyIdx) = newTemplateDocPart;

Close the template.

close(t);

This image represents the modified template document part in the updated template. It now contains the original text, the first new static text, the original template hole, and the second new static text.

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.

This image represents the template document part "partToModify" from the source template that needs to be modified. It currently contains the static text Text in template document part followed by a template hole "templateHole".

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

This image represents the modified template document part in the updated template. It now contains the updated static text Updated test in template document part and the original unmodified template hole "templateHole".

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.

This image represents the template document part "partToModify" from the source template that needs to be modified. It currently contains the static text Text in template document part followed by a template hole "templateHole".

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

This image represents the new template document part in the updated template. It now contains a new template hole "newTemplateHole" followed by a 2-by-2 table.

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