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 configuration-docx 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 plugin_tutorial may be required for an in-depth understanding.
For a tutorial covering topics more targeted towards content and configuration through configuration-xml and configuration-ipc, see additional_topics_1.
Topics Covered:
The project for this tutorial is Invoice </demos/Invoice.zip>. 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 </demos/Invoice/templates/invoice.py> and registered in Company.iif </demos/Invoice/templates/Company.iif>. If you have not done so already, read through the t_plugin-using portion of the t_plugin tutorial.
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 keywords-system-log_images system keyword <keywords-system> in the configuration-ipc:
/demos/Invoice/Invoice.ipc
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.pngThis is the only actual image that is logged. It is a copy of the authorization signature that is inserted by the
xml-spec-tags-figuretag in theconfiguration-xml:/demos/Invoice/templates/Invoice.xml
Invoice_damage_assessment.txtThis is the output of the
xml-spec-tags-stringtag in theconfiguration-xml. Strings are dumped into a text file for inspection, since they are generated content, like images./demos/Invoice/templates/Invoice.xml
Invoice_financial_data.csvThis 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
xml-spec-tags-tabletag in theconfiguration-xml:/demos/Invoice/templates/Invoice.xml
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.
Some of the last paragraph above probably belongs in the plugin tutorial, not here.
The built-in tags support two types of breaks: line and page breaks. Both are to be found in the Invoice </demos/Invoice.zip> sample project.
Line breaks are placed directly in a run of text using the xml-spec-tags-n tag:
/demos/Invoice/templates/Invoice.xml
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 xml-spec-tags-par tag, an attempt will be made to find or even create a suitable run for the line break. However, outside a paragraph, xml-spec-tags-n gets ignored completely, with a warning.
Unlike line breaks, page breaks can appear just about anywhere. This includes xml-spec-tags-run and xml-spec-tags-par tags, as well as the document root <xml-spec-root>.
Page breaks are inserted with a xml-spec-tags-break tag:
/demos/Invoice/templates/Invoice.xml
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.