Additional Topics, Part 2¶
This tutorial covers some of the topics not covered in the Basic Tutorial. The focus here is on how to set up proper styling through DOCX Stub and how to utilise plugins to their fullest potential. A basic understanding of the topics covered in the Basic Tutorial is assumed. A passing understanding of the concepts in Writing Plugins may be required for an in-depth understanding.
For a tutorial covering topics more targeted towards content and configuration through XML Template and IPC File, see Additional Topics, Part 1.
Topics Covered:
Project¶
The project for this tutorial is Invoice
. The
discussion will only focus on the relevant portions of the relevant files, so
readers are encouraged to download and extract the entire project before
delving into the tutorial.
There will also be sections that demonstrate how to work through the MS Word user interface, as well as some XML formatting in a text editor.
The document created in the project will contain a made up customer invoice, along with a letter to the customer. It will look something like this:
The project uses two custom plugins and one built-in one to process the data.
The plugins are implemented in
invoice.py
and registered in
Company.iif
. If you have not
done so already, read through the Using Your Plugin portion of the
Writing Plugins tutorial.
Image Logging¶
Images that are generated for the document can be “logged” by copying them into the log directory, or if conventional logging is disabled, into to the document output directory. Image logging also applies to strings, LaTeX equations, and sometimes tables (all the common handlers implement it). For common handlers that just insert images or table data as-is into a document, this is not much of an advantage. However, when a figure handler generates a complex image or chart from scratch, it is often useful to have it output to disc as well as using it from memory.
Image logging is controlled by the log_images system keyword in the IPC File:
18 19 | log_file = True log_images = True |
Image logging is not enabled by default. With logging turned on, you will see the following additional files in your output directory:
Invoice_authorized_signature.png
This is the only actual image that is logged. It is a copy of the authorization signature that is inserted by the <figure> tag in the XML Template:
57 58 59 60 61 62 63 64 65
<par style="Normal"> <run>Kindest Regards,</run> </par> <par style="Figure Container"> <figure id="authorized_signature" handler="imprint.handlers.figure.ImageFile"/> </par> <par style="Normal"> <run><kwd name="AuthorizedSigner"/></run> </par>
Invoice_damage_assessment.txt
This is the output of the <string> tag in the XML Template. Strings are dumped into a text file for inspection, since they are generated content, like images.
25 26 27 28 29
<par style="Normal"> <run> <string id="damage_assessment" handler="invoice.damage_assessment"/> </run> </par>
Invoice_financial_data.csv
This is a copy of the financial data that is used to do the damage assessment and to generate the actual invoice. It is generated in response to the <table> tag in the XML Template:
84 85 86 87 88 89 90 91 92
<par style="Normal"> <run>Transaction Date: </run> <run style="Strong"><kwd name="InvoiceDate" format="%Y-%b-%d"/></run> </par> <table handler="invoice.invoice_table" id="financial_data" style="Plain Table 1" /> <par style="Post Table"> <run>Payment in full is due on </run> <run style="Strong"><kwd name="DueDate" format="%Y-%b-%d"/></run> </par>
Tables are not required to dump their data unless it really makes sense to do so. Due to the relatively flexible structure of tables in Word documents, the plugin itself is responsible for how the data is to be written. Other plugins rely on the tag to do their logging for them.
Todo
Some of the last paragraph above probably belongs in the plugin tutorial, not here.
Line and Page Breaks¶
The built-in tags support two types of breaks: line and page breaks. Both are
to be found in the Invoice
sample project.
Line Breaks¶
Line breaks are placed directly in a run of text using the <n> tag:
39 40 41 42 43 44 | <par style="List Paragraph"> <run><kwd name="AddressAttn"/><n/> <kwd name="Address1"/><n/> <kwd name="Address2"/><n/> <kwd name="Address3"/></run> </par> |
The result is a single run of text, but broken over multiple lines in a controlled manner:
Line breaks can only appear in a run of text. If they appear anywhere within a <par> tag, an attempt will be made to find or even create a suitable run for the line break. However, outside a paragraph, <n> gets ignored completely, with a warning.
Page Breaks¶
Unlike line breaks, page breaks can appear just about anywhere. This includes <run> and <par> tags, as well as the document root.
Page breaks are inserted with a <break> tag:
63 64 65 66 67 68 69 70 71 72 | <par style="Normal"> <run><kwd name="AuthorizedSigner"/></run> </par> <break/> <!-- Second (Invoice) Page --> <par style="Title"> <run>Customer Invoice</run> </par> |
The page break in this example separates the signature in the preface letter from the page containing the actual customer invoice. Usually, page breaks appear between paragraphs, as in this example, but that is not a requirement.
When a page break cuts a run or paragraph in two, a new paragraph and/or run with the same style is really created on the next page.