The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
MsOffice-Word-Template-2.04
River stage zero No dependents
/ MsOffice::Word::Template::Engine::TT2

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.

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 library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.