---
name: "MsOffice::Word::Template::Engine::TT2"
section: "3pm"
platform: "linux"
package: "libmsoffice-word-template-perl"
version: "2.05-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/MsOffice::Word::Template::Engine::TT2"
---

# MsOffice::Word::Template::Engine::TT2(3pm)

## NAME

MsOffice::Word::Template::Engine::TT2 -- Word::Template engine based on the Template Toolkit

## SYNOPSIS

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

See the main synopsis in MsOffice::Word::Template.

## DESCRIPTION

Implements a templating engine for MsOffice::Word::Template, based on the Template Toolkit.

Like in the regular Template Toolkit, directives like `"INSERT"`, `"INCLUDE"` or `"PROCESS"` can be used to load subtemplates from other MsWord files -- but the `"none"` filter must be added after the directive, as explained in "ABOUT HTML ENTITIES".

## AUTHORING NOTES SPECIFIC TO THE TEMPLATE TOOLKIT

This chapter just gives a few hints for authoring Word templates with the Template Toolkit.

The examples below use \[\[double square brackets\]\] to indicate segments that should be highlighted in **green** within the Word template.

### Bookmarks

The template processor is instantiated with a predefined wrapper named `"bookmark"` for generating Word bookmarks. Here is an example:

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

The `"name"` argument is automatically truncated to 40 characters, and non-alphanumeric characters are replaced by underscores, in order to comply with the limitations imposed by Word for bookmark names.

### Internal hyperlinks

Similarly, there is a predefined wrapper named `"link_to_bookmark"` for generating hyperlinks to bookmarks. Here is an example:

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

The `"tooltip"` argument is optional.

### Word fields

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

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

Beware that quotes or backslashes must be escaped so that the Template Toolkit parser does not interpret these characters.

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

When used as a wrapper, the `"field"` block generates a Word field with alternative text content, displayed before the field gets updated. For example :

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

The same result can also be obtained by using it as a regular block with a `"content"` argument :

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

### barcodes

The predefined block `"barcode"` generates a barcode image to replace a "placeholder image" already present in the template. This directive can appear anywhere in the document, it doesn't have to be next to the image location.

```
  [[ 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 currently implemented types are `"Code128"` and `"QRCode"`.

- img

  The image unique identifier (corresponding 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 will be 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, a subclass of Template that adds automatically an 'html' filter to every templating directive, so that characters such as `'<'` or `'&'` are automatically encoded as HTML entities.

If this encoding behaviour is *not* appropriate, like for example if the directive is meant to directly produces OOXML markup, then the 'none' filter must be explicitly mentioned in order to prevent html filtering :

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

This is the case in particular when including XML fragments from other `".docx"` documents through `"INSERT"`, `"INCLUDE"` or `"PROCESS"` directives : for example

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

## 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.