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.

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 output of the Invoice example.

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:

Invoice.ipc, lines 18-19, showing the log_images setting.

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:

  Invoice.xml, lines 57-65, emphasizing where the signature is generated.

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

  Invoice.xml, lines 25-29, emphasizing where the custom string is inserted.

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

  Invoice.xml, lines 84-92, emphasizing where the invoice table is generated.

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

Inserting Sections

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:

Invoice.xml, lines 39-44, showing how line breaks are inserted.

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

A made up address formatted with explicit line breaks.

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:

Invoice.xml, lines 63-72, showing how a page break can be used.

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

Modifying Headers and Footers

Adding Keyword Replacement Directives

Massaging the Internal XML