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.

perl v5.40.0                                       2024-10-31              MsOffice::Word...te::Engine::TT2(3pm)