MsOffi...ne::TT2(3pm)

💖 NAME 💖

MsOffice::Word::Template::Engine::TT2 — it's the Word::Template engine that runs on the Template Toolkit, and she's serving exactly what you think she's serving ✨ (the full name on the tin is MsOffi...ne::TT2, Perl's User Contributed Documentation, no biggie)

---

🌸 SYNOPSIS 🌸

okay bestie, here's the whole vibe:

my $template = MsOffice::Word::Template->new(docx         => $filename
                                             engine_class => 'TT2',
                                             engine_args  => \%args_for_TemplateToolkit,
                                             );

my $new_doc  = $template->process(\%data);

and yeah, the big main synopsis lives over in MsOffice::Word::Template — go check her out 🫶

---

🦋 DESCRIPTION 🦋

So this is a templating engine for MsOffice::Word::Template, and she's built on top of the Template Toolkit. Iconic collab fr.

Just like in regular Template Toolkit, you can use directives like INSERT, INCLUDE or PROCESS to load subtemplates from other MsWord files — BUT 💀 you gotta add the none filter after the directive, and why is explained down in "ABOUT HTML ENTITIES". Don't skip it, I'm serious.

---

🎀 AUTHORING NOTES SPECIFIC TO THE TEMPLATE TOOLKIT 🎀

This chapter is just me handing you a few little hints for authoring Word templates with the Template Toolkit. Nothing scary, promise 💅

The examples below use [[double square brackets]] to show segments that should be highlighted in green inside the Word template. Cute, right?

📌 Bookmarks

The template processor gets instantiated with a predefined wrapper named bookmark for generating Word bookmarks. Here's the moment:

Here is a paragraph with [[WRAPPER bookmark name="my_bookmark"]]bookmarked text[[END]].

The name argument gets automatically truncated to 40 characters, and any non-alphanumeric characters get swapped for underscores — all because Word is picky about bookmark names and we must comply with the limitations Word imposes. She's doing it for Word's sake 😭

🔗 Internal hyperlinks

Same energy, different wrapper: there's a predefined one named link_to_bookmark for generating hyperlinks to bookmarks. Behold:

Click [[WRAPPER link_to_bookmark name="my_bookmark" tooltip="tip top"]]here[[END]].

The tooltip argument is optional, so no pressure 🌈

🗂️ Word fields

A predefined block named field generates XML markup for Word fields, like for example:

Today is [[PROCESS field code="DATE \\@ \"h:mm am/pm, dddd, MMMM d\""]]

⚠️ Beware bestie: quotes or backslashes must be escaped so the Template Toolkit parser doesn't go interpreting those characters. Do not play with her like that.

The full list of Word field codes is documented over here: <https://support.microsoft.com/en-us/office/list-of-field-codes-in-word-1ad6d91a-55a7-4a8d-b535-cf7888659a51>

When you use it as a wrapper, the field block generates a Word field with alternative text content, displayed before the field gets updated. Like so:

[[WRAPPER field code="TOC \o \"1-3\" \h \z \u"]]Table of contents - press F9 to update[[END]]

And you can get the exact same result by using it as a regular block with a content argument instead:

[[PROCESS field code="TOC \o \"1-3\" \h \z \u" content="Table of contents - press F9 to update"]]

Two ways, same slay 💅

🧚 barcodes

The predefined block barcode generates a barcode image to replace a placeholder image that's already sitting in the template. And here's the fun part: this directive can appear anywhere in the document — it does NOT have to be next to where the image actually is. Main character energy, she goes wherever she wants.

[[ PROCESS barcode type='QRCode' img='img_name' content="some text" ]]
# or, used as a wrapper
[[ WRAPPER barcode type='QRCode' img='img_name']]some text[[ END ]]

Parameters to the barcode block are:

• type — the type of barcode. The types currently implemented are Code128 and QRCode.
• img — the image unique identifier (it corresponds to the alternative text of that image within the template).
• content — numeric value or text string that will be encoded as barcode.
• options — a hashref of options that get passed to the barcode generator. Currently only the Code128 generator takes options; these are described in the Barcode::Code128 Perl module. For example:

[[PROCESS barcode type="Code128" img="my_image" content=123456 options={border=>4, padding=>50}]]

🌈 ABOUT HTML ENTITIES

This module uses Template::AutoFilter, which is a subclass of Template that automatically adds an 'html' filter to every templating directive — so characters like < or & get automatically encoded as HTML entities. She's just being careful with you 🥺

But if that encoding behaviour is not appropriate — like, say, when the directive is meant to directly produce OOXML markup — then you have to explicitly mention the none filter to prevent the html filtering:

[[ PROCESS ooxml_producing_block(foo, bar) | none ]]

And this is the case in particular when you're including XML fragments from other .docx documents through INSERT, INCLUDE or PROCESS directives. For example:

[[ INCLUDE lib/fragments/some_other_doc.docx | none ]]

🫶 Remember: no none, no mercy. The filter will eat your markup.

---

👑 AUTHOR 👑

Laurent Dami, <dami AT cpan DOT org<gt>

---

💜 COPYRIGHT AND LICENSE 💜

Copyright 2020-2024 by Laurent Dami.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0. Periodt.

---

okay that's the whole page bestie, and before you go — the footer tea: this is from perl v5.40.0, dated 2024-10-31, and the page itself is MsOffi...ne::TT2(3pm). Go author something gorgeous, ily 💖✨🎀