| MsOffice::Word::Template::Engine::TT2(3pm) | User Contributed Perl Documentation | MsOffice::Word::Template::Engine::TT2(3pm) |
MsOffice::Word::Template::Engine::TT2 -- Word::Template engine based on the Template Toolkit
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.
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".
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.
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.
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.
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"]]
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 :
[[PROCESS barcode type="Code128" img="my_image" content=123456 options={border=>4, padding=>50}]]
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 ]]
Laurent Dami, <dami AT cpan DOT org<gt>
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.
| 2024-10-31 | perl v5.40.0 |