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 ]]