= POD Document Templates =

This page covers a very specific kind of "document template" - one which is supported through the "magic" of the [[https://www.appyframework.org/pod.html|appy.pod]] package.

In terms of Rattail, this `appy.pod` package has been leveraged in a few ways, to generate e.g.:

 * billing invoices to send to clients
 * basic contracts for new clients
 * simple reports
 * simple spreadsheets

Whether it's worth fooling with `appy.pod` templates, vs. making the app responsible for generating such documents "from scratch" is a question of your requirements and developer preference etc.  In particular, I find spreadsheets to be easier to generate directly instead of maintaining `appy.pod` templates for those.  But the nice thing about `appy.pod` is that it leverages !LibreOffice (or !OpenOffice) and can generate any of its supported formats, e.g. PDF, for a rather polished final product.

Anyway the rest of this page obviously assumes `appy.pod` is in use and will describe that approach.

TODO: should describe the setup required

In general how this works is, the Poser app logic will collect data and parameters etc. and then pass all that at once to the `appy.pod` engine which will merge that data with a "template" file on disk, and produce an output file as a result.

This means there are 2 primary concerns: a) the app logic which collects data, and b) the template file.  The app logic is really a concern for the developer and not the administrator, so we'll only be focusing on the template file here.  Even this much may be the responsibility of the developer, depending on your situation.

== Template Syntax ==

Please also see the official docs for `appy.pod` - what follows is largely just a summary of these:

 * [[https://www.appyframework.org/pod.html|An introduction to pod]]
 * [[https://www.appyframework.org/podWritingTemplates.html|Writing simple templates]]
 * [[https://www.appyframework.org/podWritingAdvancedTemplates.html|Writing advanced templates]]

Inserting a value from Python is done by creating a "field" which you can do by pressing Ctrl+F2.  The field should be of type "Conditional text".  You always set the "Condition" to "true".  You set "Then" to a valid Python variable name, which must be included in the data collected by the Poser app logic.  You then click Insert and Close, and the new field should then be visible in your document.  You can double-click it to edit as needed.